claude-mpm 5.0.9__py3-none-any.whl → 5.6.23__py3-none-any.whl

claude_mpm/core/output_style_manager.py

@@ -5,6 +5,7 @@ This module handles:
 2. Output style extraction from framework instructions
 3. One-time deployment to Claude Code >= 1.0.83 at startup
 4. Fallback injection for older versions
+5. Support for multiple output styles (professional and teaching modes)
 
 The output style is set once at startup and not monitored or enforced after that.
 Users can change it if they want, and the system will respect their choice.
@@ -12,9 +13,9 @@ Users can change it if they want, and the system will respect their choice.
 
 import json
 import re
-import subprocess
+import subprocess  # nosec B404
 from pathlib import Path
-from typing import Dict, Optional
+from typing import Any, Dict, Literal, Optional, TypedDict, cast
 
 from ..utils.imports import safe_import
 
@@ -25,22 +26,74 @@ get_logger = safe_import("claude_mpm.core.logger", "core.logger", ["get_logger"]
 _CACHED_CLAUDE_VERSION: Optional[str] = None
 _VERSION_DETECTED: bool = False
 
+# Output style types
+OutputStyleType = Literal[
+    "professional", "teaching", "research", "founders"
+]  # "founders" is deprecated, use "research"
+
+
+class StyleConfig(TypedDict):
+    """Configuration for an output style."""
+
+    source: Path
+    target: Path
+    name: str
+
 
 class OutputStyleManager:
-    """Manages output style deployment and version-based handling."""
+    """Manages output style deployment and version-based handling.
+
+    Supports three output styles:
+    - professional: Default Claude MPM style (claude-mpm.md)
+    - teaching: Adaptive teaching mode (claude-mpm-teacher.md)
+    - research: Codebase research mode for founders, PMs, and developers (claude-mpm-research.md)
+    """
 
-    def __init__(self):
+    def __init__(self) -> None:
         """Initialize the output style manager."""
-        self.logger = get_logger("output_style_manager")
+        self.logger = get_logger("output_style_manager")  # type: ignore[misc]
         self.claude_version = self._detect_claude_version()
+
+        # Deploy to ~/.claude/output-styles/ directory (official Claude Code location)
         self.output_style_dir = Path.home() / ".claude" / "output-styles"
-        self.output_style_path = self.output_style_dir / "claude-mpm.md"
         self.settings_file = Path.home() / ".claude" / "settings.json"
 
-        # Cache the output style content path
-        self.mpm_output_style_path = (
-            Path(__file__).parent.parent / "agents" / "OUTPUT_STYLE.md"
-        )
+        # Style definitions
+        self.styles: Dict[str, StyleConfig] = {
+            "professional": StyleConfig(
+                source=Path(__file__).parent.parent
+                / "agents"
+                / "CLAUDE_MPM_OUTPUT_STYLE.md",
+                target=self.output_style_dir / "claude-mpm.md",
+                name="Claude MPM",
+            ),
+            "teaching": StyleConfig(
+                source=Path(__file__).parent.parent
+                / "agents"
+                / "CLAUDE_MPM_TEACHER_OUTPUT_STYLE.md",
+                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_RESEARCH_OUTPUT_STYLE.md",
+                target=self.output_style_dir / "claude-mpm-research.md",
+                name="Claude MPM Research",
+            ),
+        }
+
+        # Default style path (for backward compatibility)
+        self.output_style_path = self.styles["professional"]["target"]
+        self.mpm_output_style_path = self.styles["professional"]["source"]
 
     def _detect_claude_version(self) -> Optional[str]:
         """
@@ -58,7 +111,7 @@ class OutputStyleManager:
 
         try:
             # Run claude --version command
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607
                 ["claude", "--version"],
                 capture_output=True,
                 text=True,
@@ -158,56 +211,77 @@ class OutputStyleManager:
         """
         return not self.supports_output_styles()
 
-    def extract_output_style_content(self, framework_loader=None) -> str:
+    def extract_output_style_content(
+        self, framework_loader: Any = None, style: OutputStyleType = "professional"
+    ) -> str:
         """
-        Read output style content from OUTPUT_STYLE.md.
+        Read output style content from style source file.
 
         Args:
             framework_loader: Optional framework loader (kept for compatibility, not used)
+            style: Style type to extract ("professional" or "teaching")
 
         Returns:
             Complete output style content from file
         """
-        # Always read from the complete OUTPUT_STYLE.md file
-        if self.mpm_output_style_path.exists():
-            content = self.mpm_output_style_path.read_text()
-            self.logger.info(f"Read OUTPUT_STYLE.md directly ({len(content)} chars)")
+        style_config = self.styles[style]
+        source_path = style_config["source"]
+
+        if source_path.exists():
+            content = source_path.read_text()
+            self.logger.info(
+                f"Read {style} style from {source_path.name} ({len(content)} chars)"
+            )
             return content
+
         # Fallback error
-        error_msg = f"OUTPUT_STYLE.md not found at {self.mpm_output_style_path}"
+        error_msg = f"{style} style not found at {source_path}"
         self.logger.error(error_msg)
         raise FileNotFoundError(error_msg)
 
-    def save_output_style(self, content: str) -> Path:
+    def save_output_style(
+        self, content: str, style: OutputStyleType = "professional"
+    ) -> Path:
         """
-        Save output style content to OUTPUT_STYLE.md.
+        Save output style content to source file.
 
         Args:
             content: The formatted output style content
+            style: Style type to save ("professional" or "teaching")
 
         Returns:
             Path to the saved file
         """
         try:
+            style_config = self.styles[style]
+            source_path = style_config["source"]
+
             # Ensure the parent directory exists
-            self.mpm_output_style_path.parent.mkdir(parents=True, exist_ok=True)
+            source_path.parent.mkdir(parents=True, exist_ok=True)
 
             # Write the content
-            self.mpm_output_style_path.write_text(content, encoding="utf-8")
-            self.logger.info(f"Saved output style to {self.mpm_output_style_path}")
+            source_path.write_text(content, encoding="utf-8")
+            self.logger.info(f"Saved {style} style to {source_path}")
 
-            return self.mpm_output_style_path
+            return source_path
         except Exception as e:
-            self.logger.error(f"Failed to save output style: {e}")
+            self.logger.error(f"Failed to save {style} style: {e}")
             raise
 
-    def deploy_output_style(self, content: str) -> bool:
+    def deploy_output_style(
+        self,
+        content: Optional[str] = None,
+        style: OutputStyleType = "professional",
+        activate: bool = True,
+    ) -> bool:
         """
         Deploy output style to Claude Code if version >= 1.0.83.
-        Deploys the style file and activates it once.
+        Deploys the style file and optionally activates it.
 
         Args:
-            content: The output style content to deploy
+            content: The output style content to deploy (if None, reads from source)
+            style: Style type to deploy ("professional" or "teaching")
+            activate: Whether to activate the style after deployment
 
         Returns:
             True if deployed successfully, False otherwise
@@ -219,26 +293,51 @@ class OutputStyleManager:
             return False
 
         try:
-            # Ensure output-styles directory exists
+            style_config = self.styles[style]
+            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)
+
+            # Ensure styles directory exists
             self.output_style_dir.mkdir(parents=True, exist_ok=True)
 
             # Write the output style file
-            self.output_style_path.write_text(content, encoding="utf-8")
-            self.logger.info(f"Deployed output style to {self.output_style_path}")
+            target_path.write_text(content, encoding="utf-8")
+            self.logger.info(f"Deployed {style} style to {target_path}")
 
-            # Activate the claude-mpm style
-            self._activate_output_style()
+            # Activate the style if requested
+            if activate:
+                self._activate_output_style(
+                    style_name, is_fresh_install=is_fresh_install
+                )
 
             return True
 
         except Exception as e:
-            self.logger.error(f"Failed to deploy output style: {e}")
+            self.logger.error(f"Failed to deploy {style} style: {e}")
             return False
 
-    def _activate_output_style(self) -> bool:
+    def _activate_output_style(
+        self, style_name: str = "Claude MPM", is_fresh_install: bool = False
+    ) -> bool:
         """
-        Update Claude Code settings to activate the claude-mpm output style.
-        Sets activeOutputStyle to "claude-mpm" once at startup.
+        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
@@ -257,9 +356,13 @@ class OutputStyleManager:
             # Check current active style
             current_style = settings.get("activeOutputStyle")
 
-            # Update active output style to claude-mpm if not already set
-            if current_style != "claude-mpm":
-                settings["activeOutputStyle"] = "claude-mpm"
+            # Only set activeOutputStyle if:
+            # 1. No active style is set (first deployment), OR
+            # 2. This is a fresh install (file didn't exist before deployment)
+            should_activate = current_style is None or is_fresh_install
+
+            if should_activate and current_style != style_name:
+                settings["activeOutputStyle"] = style_name
 
                 # Ensure settings directory exists
                 self.settings_file.parent.mkdir(parents=True, exist_ok=True)
@@ -270,10 +373,13 @@ class OutputStyleManager:
                 )
 
                 self.logger.info(
-                    f"✅ Activated claude-mpm output style (was: {current_style or 'none'})"
+                    f"✅ Activated {style_name} output style (was: {current_style or 'none'})"
                 )
             else:
-                self.logger.debug("Claude MPM output style already active")
+                self.logger.debug(
+                    f"Preserving user preference: {current_style or 'none'} "
+                    f"(skipping activation of {style_name})"
+                )
 
             return True
 
@@ -319,7 +425,9 @@ class OutputStyleManager:
 
         return status
 
-    def get_injectable_content(self, framework_loader=None) -> str:
+    def get_injectable_content(
+        self, framework_loader: Any = None, style: OutputStyleType = "professional"
+    ) -> str:
         """
         Get output style content for injection into instructions (for Claude < 1.0.83).
 
@@ -328,12 +436,13 @@ class OutputStyleManager:
 
         Args:
             framework_loader: Optional FrameworkLoader instance to reuse loaded content
+            style: Style type to extract ("professional" or "teaching")
 
         Returns:
             Simplified output style content for injection
         """
         # Extract the same content but without YAML frontmatter
-        full_content = self.extract_output_style_content(framework_loader)
+        full_content = self.extract_output_style_content(framework_loader, style=style)
 
         # Remove YAML frontmatter
         lines = full_content.split("\n")
@@ -351,3 +460,69 @@ class OutputStyleManager:
 
         # If no frontmatter found, return as-is
         return full_content
+
+    def deploy_all_styles(self, activate_default: bool = True) -> Dict[str, bool]:
+        """
+        Deploy all available output styles to Claude Code.
+
+        Args:
+            activate_default: Whether to activate the professional style after deployment
+
+        Returns:
+            Dictionary mapping style names to deployment success status
+        """
+        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
+            style_type = cast("OutputStyleType", style_type_key)
+            success = self.deploy_output_style(style=style_type, activate=False)
+            results[style_type] = success
+
+        # 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", is_fresh_install=not professional_style_existed
+            )
+
+        return results
+
+    def deploy_teaching_style(self, activate: bool = False) -> bool:
+        """
+        Deploy the teaching style specifically.
+
+        Args:
+            activate: Whether to activate the teaching style after deployment
+
+        Returns:
+            True if deployed successfully, False otherwise
+        """
+        return self.deploy_output_style(style="teaching", activate=activate)
+
+    def list_available_styles(self) -> Dict[str, Dict[str, str]]:
+        """
+        List all available output styles with their metadata.
+
+        Returns:
+            Dictionary mapping style types to their configuration
+        """
+        available_styles = {}
+
+        for style_type, config in self.styles.items():
+            source_exists = config["source"].exists()
+            target_exists = config["target"].exists()
+
+            available_styles[style_type] = {
+                "name": config["name"],
+                "source_path": str(config["source"]),
+                "target_path": str(config["target"]),
+                "source_exists": str(source_exists),
+                "deployed": str(target_exists),
+            }
+
+        return available_styles

claude_mpm/core/shared/config_loader.py

@@ -51,7 +51,9 @@ class ConfigLoader:
         search_paths=[".", ".claude-mpm", "agents"],
         env_prefix="CLAUDE_MPM_AGENT_",
         defaults={"timeout": 30, "max_retries": 3, "log_level": "INFO"},
-        required_keys=["name", "model"],
+        required_keys=[
+            "name"
+        ],  # model is optional - defaults to sonnet if not specified
     )
 
     MEMORY_CONFIG = ConfigPattern(

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
 
@@ -55,8 +63,8 @@ class CircuitState(Enum):
 class ConnectionStats:
     """Connection statistics for monitoring."""
 
-    created_at: datetime = field(default_factory=datetime.now)
-    last_used: datetime = field(default_factory=datetime.now)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    last_used: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
     events_sent: int = 0
     errors: int = 0
     consecutive_errors: int = 0
@@ -70,7 +78,7 @@ class BatchEvent:
     namespace: str
     event: str
     data: Dict[str, Any]
-    timestamp: datetime = field(default_factory=datetime.now)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
 
 
 class CircuitBreaker:
@@ -309,7 +317,7 @@ class SocketIOConnectionPool:
                         self.server_url = f"http://localhost:{port}"
                         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
@@ -579,7 +587,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_agent_registry.py

@@ -84,6 +84,12 @@ class AgentMetadata:
     version: str = "1.0.0"
     author: str = ""
     tags: List[str] = None
+    # NEW: Collection-based identification fields
+    collection_id: Optional[str] = None  # Format: owner/repo-name
+    source_path: Optional[str] = None  # Relative path in repo
+    canonical_id: Optional[str] = (
+        None  # Format: collection_id:agent_id or legacy:filename
+    )
 
     def __post_init__(self):
         """Initialize default values for mutable fields."""
@@ -168,26 +174,16 @@ class UnifiedAgentRegistry:
         if project_path.exists():
             self.discovery_paths.append(project_path)
 
-        # Also check for local JSON templates in .claude-mpm/agents/
-        local_project_path = self.path_manager.project_root / ".claude-mpm" / "agents"
-        if (
-            local_project_path.exists()
-            and local_project_path not in self.discovery_paths
-        ):
-            self.discovery_paths.append(local_project_path)
-            logger.debug(f"Added local project templates path: {local_project_path}")
+        # NOTE: .claude-mpm/agents/ is deprecated in the simplified architecture
+        # Source agents come from ~/.claude-mpm/cache/agents/
+        # Deployed agents go to .claude/agents/
 
-        # User-level agents
+        # User-level agents (deprecated in simplified architecture)
+        # Keeping for backward compatibility but not actively used
         user_path = self.path_manager.get_user_agents_dir()
         if user_path.exists():
             self.discovery_paths.append(user_path)
 
-        # Also check for user JSON templates in ~/.claude-mpm/agents/
-        local_user_path = Path.home() / ".claude-mpm" / "agents"
-        if local_user_path.exists() and local_user_path not in self.discovery_paths:
-            self.discovery_paths.append(local_user_path)
-            logger.debug(f"Added local user templates path: {local_user_path}")
-
         # System-level agents (includes templates as a subdirectory)
         system_path = self.path_manager.get_system_agents_dir()
         if system_path.exists():
@@ -690,6 +686,111 @@ class UnifiedAgentRegistry:
         """Get all memory-aware agents."""
         return self.list_agents(agent_type=AgentType.MEMORY_AWARE)
 
+    def get_agents_by_collection(self, collection_id: str) -> List[AgentMetadata]:
+        """Get all agents from a specific collection.
+
+        NEW: Enables collection-based agent selection.
+
+        Args:
+            collection_id: Collection identifier (e.g., "bobmatnyc/claude-mpm-agents")
+
+        Returns:
+            List of agents from the specified collection
+
+        Example:
+            >>> registry = get_agent_registry()
+            >>> agents = registry.get_agents_by_collection("bobmatnyc/claude-mpm-agents")
+            >>> len(agents)
+            45
+        """
+        if not self.registry:
+            self.discover_agents()
+
+        collection_agents = [
+            agent
+            for agent in self.registry.values()
+            if agent.collection_id == collection_id
+        ]
+
+        return sorted(collection_agents, key=lambda a: a.name)
+
+    def list_collections(self) -> List[Dict[str, Any]]:
+        """List all available collections with agent counts.
+
+        NEW: Provides overview of available collections.
+
+        Returns:
+            List of collection info dictionaries with:
+            - collection_id: Collection identifier
+            - agent_count: Number of agents in collection
+            - agents: List of agent names in collection
+
+        Example:
+            >>> registry = get_agent_registry()
+            >>> collections = registry.list_collections()
+            >>> collections
+            [
+                {
+                    "collection_id": "bobmatnyc/claude-mpm-agents",
+                    "agent_count": 45,
+                    "agents": ["pm", "engineer", "qa", ...]
+                }
+            ]
+        """
+        if not self.registry:
+            self.discover_agents()
+
+        # Group agents by collection_id
+        collections_map: Dict[str, List[str]] = {}
+
+        for agent in self.registry.values():
+            if not agent.collection_id:
+                # Skip agents without collection (legacy or local)
+                continue
+
+            if agent.collection_id not in collections_map:
+                collections_map[agent.collection_id] = []
+
+            collections_map[agent.collection_id].append(agent.name)
+
+        # Convert to list format
+        collections = [
+            {
+                "collection_id": coll_id,
+                "agent_count": len(agent_names),
+                "agents": sorted(agent_names),
+            }
+            for coll_id, agent_names in collections_map.items()
+        ]
+
+        return sorted(collections, key=lambda c: c["collection_id"])
+
+    def get_agent_by_canonical_id(self, canonical_id: str) -> Optional[AgentMetadata]:
+        """Get agent by canonical ID (primary matching key).
+
+        NEW: Primary matching method using canonical_id.
+
+        Args:
+            canonical_id: Canonical identifier (e.g., "bobmatnyc/claude-mpm-agents:pm")
+
+        Returns:
+            AgentMetadata if found, None otherwise
+
+        Example:
+            >>> registry = get_agent_registry()
+            >>> agent = registry.get_agent_by_canonical_id("bobmatnyc/claude-mpm-agents:pm")
+            >>> agent.name
+            'Project Manager Agent'
+        """
+        if not self.registry:
+            self.discover_agents()
+
+        for agent in self.registry.values():
+            if agent.canonical_id == canonical_id:
+                return agent
+
+        return None
+
     def add_discovery_path(self, path: Union[str, Path]) -> None:
         """Add a new path for agent discovery."""
         path = Path(path)
@@ -809,6 +910,21 @@ def get_registry_stats() -> Dict[str, Any]:
     return get_agent_registry().get_registry_stats()
 
 
+def get_agents_by_collection(collection_id: str) -> List[AgentMetadata]:
+    """Get all agents from a specific collection."""
+    return get_agent_registry().get_agents_by_collection(collection_id)
+
+
+def list_collections() -> List[Dict[str, Any]]:
+    """List all available collections."""
+    return get_agent_registry().list_collections()
+
+
+def get_agent_by_canonical_id(canonical_id: str) -> Optional[AgentMetadata]:
+    """Get agent by canonical ID."""
+    return get_agent_registry().get_agent_by_canonical_id(canonical_id)
+
+
 # Legacy function names for backward compatibility
 def listAgents() -> List[str]:
     """Legacy function: Get list of agent names."""
@@ -838,14 +954,16 @@ __all__ = [
     "discover_agents",
     "discover_agents_sync",
     "get_agent",
+    "get_agent_by_canonical_id",
     "get_agent_names",
     "get_agent_registry",
+    "get_agents_by_collection",
     "get_core_agents",
     "get_project_agents",
     "get_registry_stats",
     "get_specialized_agents",
-    # Legacy compatibility
     "listAgents",
     "list_agents",
     "list_agents_all",
+    "list_collections",
 ]