claude-mpm 4.1.6__py3-none-any.whl → 4.24.0__py3-none-any.whl

claude_mpm/core/socketio_pool.py

@@ -17,7 +17,7 @@ import threading
 import time
 from collections import defaultdict, deque
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from enum import Enum
 from typing import Any, Deque, Dict, List, Optional
 
@@ -97,11 +97,9 @@ class CircuitBreaker:
             return True
         if self.state == CircuitState.OPEN:
             # Check if recovery timeout has passed
-            if (
-                self.last_failure_time
-                and datetime.now() - self.last_failure_time
-                > timedelta(seconds=self.recovery_timeout)
-            ):
+            if self.last_failure_time and datetime.now(
+                timezone.utc
+            ) - self.last_failure_time > timedelta(seconds=self.recovery_timeout):
                 self.state = CircuitState.HALF_OPEN
                 self.logger.info(
                     "Circuit breaker transitioning to HALF_OPEN for testing"
@@ -127,7 +125,7 @@ class CircuitBreaker:
     def record_failure(self):
         """Record failed execution."""
         self.failure_count += 1
-        self.last_failure_time = datetime.now()
+        self.last_failure_time = datetime.now(timezone.utc)
 
         if self.state == CircuitState.HALF_OPEN:
             # Test failed, go back to OPEN
@@ -184,7 +182,7 @@ class SocketIOConnectionPool:
         # Health monitoring
         self.health_thread = None
         self.health_running = False
-        self.last_health_check = datetime.now()
+        self.last_health_check = datetime.now(timezone.utc)
 
         # Server configuration
         self.server_url = None
@@ -311,7 +309,7 @@ class SocketIOConnectionPool:
                         self.server_url = f"http://localhost:{port}"
                         self.logger.debug(f"Detected Socket.IO server on port {port}")
                         return
-            except:
+            except Exception:
                 continue
 
         # Fall back to default
@@ -375,7 +373,7 @@ class SocketIOConnectionPool:
                 # Check if connection is still valid
                 for conn_id, stats in self.connection_stats.items():
                     if stats.is_connected:
-                        stats.last_used = datetime.now()
+                        stats.last_used = datetime.now(timezone.utc)
                         return client
 
             # Create new connection if under limit
@@ -581,7 +579,7 @@ class SocketIOConnectionPool:
                     loop.stop()
                     loop.run_until_complete(loop.shutdown_asyncgens())
                     loop.close()
-                except:
+                except Exception:
                     pass
 
     async def _connect_client(self, client: socketio.AsyncClient):
@@ -596,9 +594,9 @@ class SocketIOConnectionPool:
                 timeout=2.0,
             )
 
-        except asyncio.TimeoutError:
+        except asyncio.TimeoutError as e:
             self.logger.debug("Socket.IO connection timeout")
-            raise TimeoutError("Socket.IO connection timeout")
+            raise TimeoutError("Socket.IO connection timeout") from e
         except Exception as e:
             self.logger.debug(f"Client connection failed: {e}")
             raise
@@ -623,7 +621,7 @@ class SocketIOConnectionPool:
                 self._check_connections_health()
 
                 # Update last health check time
-                self.last_health_check = datetime.now()
+                self.last_health_check = datetime.now(timezone.utc)
 
             except Exception as e:
                 self.logger.error(f"Health monitor error: {e}")
@@ -655,7 +653,9 @@ class SocketIOConnectionPool:
                     continue
 
                 # 3. Connection idle for too long (>5 minutes)
-                idle_time = (datetime.now() - stats.last_used).total_seconds()
+                idle_time = (
+                    datetime.now(timezone.utc) - stats.last_used
+                ).total_seconds()
                 if idle_time > 300 and conn_id not in [
                     id for id, _ in enumerate(self.available_connections)
                 ]:

claude_mpm/core/tool_access_control.py

@@ -1,9 +1,10 @@
 """Tool access control system for managing which tools agents can use."""
 
-import logging
 from typing import Dict, List, Set
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
 
 
 class ToolAccessControl:

claude_mpm/core/types.py

@@ -16,10 +16,12 @@ Module-specific types should remain in their respective modules.
 """
 
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from typing import Any, Dict, List, Optional, Tuple, Union
 
+from .enums import HealthStatus
+
 
 # Service operation results
 @dataclass
@@ -206,7 +208,7 @@ class TaskInfo:
         if self.metadata is None:
             self.metadata = {}
         if self.created_at is None:
-            self.created_at = datetime.now()
+            self.created_at = datetime.now(timezone.utc)
         if self.updated_at is None:
             self.updated_at = self.created_at
 
@@ -230,15 +232,6 @@ class SocketMessage:
 
 
 # Health monitoring types
-class HealthStatus(Enum):
-    """Service health status levels."""
-
-    HEALTHY = "healthy"
-    DEGRADED = "degraded"
-    UNHEALTHY = "unhealthy"
-    UNKNOWN = "unknown"
-
-
 @dataclass
 class HealthCheck:
     """Health check result."""

claude_mpm/core/typing_utils.py

@@ -32,6 +32,8 @@ from typing import (
 
 from typing_extensions import NotRequired, TypeAlias, TypedDict
 
+from claude_mpm.core.enums import OperationResult, ServiceState
+
 # Generic type variables
 T = TypeVar("T")
 TSession = TypeVar("TSession")  # Generic session type
@@ -42,15 +44,14 @@ TService = TypeVar("TService")  # Generic service type
 PathLike: TypeAlias = Union[str, Path]
 JSONValue: TypeAlias = Union[str, int, float, bool, None, Dict[str, Any], List[Any]]
 JSONDict: TypeAlias = Dict[str, JSONValue]
+
 Headers: TypeAlias = Dict[str, str]
 ErrorCode: TypeAlias = Union[int, str]
 LogLevel: TypeAlias = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 
 # Session types
 SessionId: TypeAlias = str
-SessionStatus: TypeAlias = Literal[
-    "initializing", "running", "stopped", "error", "completed"
-]
+SessionStatus: TypeAlias = ServiceState  # Replaced Literal with ServiceState enum
 LaunchMethod: TypeAlias = Literal["exec", "subprocess", "oneshot"]
 
 
@@ -152,7 +153,7 @@ class WebSocketMessage(TypedDict):
 class ClaudeStatus(TypedDict):
     """Claude process status."""
 
-    status: Literal["starting", "running", "stopped", "error"]
+    status: ServiceState  # Replaced Literal with ServiceState enum
     message: str
     timestamp: NotRequired[datetime]
     pid: NotRequired[int]
@@ -163,7 +164,7 @@ class DelegationInfo(TypedDict):
 
     agent: AgentId
     task: str
-    status: Literal["detected", "started", "completed", "failed"]
+    status: OperationResult  # Replaced Literal with OperationResult enum
     timestamp: NotRequired[datetime]
     result: NotRequired[str]
 
@@ -194,7 +195,7 @@ class HookContext(TypedDict):
 
 # Service types
 ServiceName: TypeAlias = str
-ServiceStatus: TypeAlias = Literal["idle", "running", "stopped", "error"]
+ServiceStatus: TypeAlias = ServiceState  # Replaced Literal with ServiceState enum
 
 
 class ServiceConfig(TypedDict):

claude_mpm/core/unified_agent_registry.py

@@ -27,17 +27,18 @@ Architecture:
 
 import contextlib
 import json
-import logging
 import time
 from dataclasses import asdict, dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set, Union
 
+from claude_mpm.core.logging_utils import get_logger
+
 from .unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class AgentTier(Enum):
@@ -167,11 +168,26 @@ 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}")
+
         # User-level agents
         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():
@@ -328,7 +344,48 @@ class UnifiedAgentRegistry:
                 file_path, agent_format
             )
 
-            return AgentMetadata(
+            # For JSON files, extract additional metadata
+            version = "1.0.0"
+            author = ""
+            tags = []
+
+            if agent_format == AgentFormat.JSON:
+                try:
+                    content = file_path.read_text(encoding="utf-8")
+                    data = json.loads(content)
+
+                    # Extract version
+                    version = data.get("agent_version", data.get("version", "1.0.0"))
+
+                    # Extract author (use project name for local agents)
+                    author = data.get("author", "")
+                    if not author and ".claude-mpm" in str(file_path):
+                        # For local agents, use project directory name as author
+                        project_root = file_path
+                        while project_root.parent != project_root:
+                            if (project_root / ".claude-mpm").exists():
+                                author = project_root.name
+                                break
+                            project_root = project_root.parent
+
+                    # Extract tags (handle both list and comma-separated string formats)
+                    if "metadata" in data:
+                        tags_raw = data["metadata"].get("tags", [])
+                        if isinstance(tags_raw, str):
+                            tags = [
+                                tag.strip()
+                                for tag in tags_raw.split(",")
+                                if tag.strip()
+                            ]
+                        else:
+                            tags = tags_raw if isinstance(tags_raw, list) else []
+
+                except Exception as e:
+                    logger.debug(
+                        f"Could not extract extra JSON metadata from {file_path}: {e}"
+                    )
+
+            metadata = AgentMetadata(
                 name=agent_name,
                 agent_type=agent_type,
                 tier=tier,
@@ -337,8 +394,24 @@ class UnifiedAgentRegistry:
                 last_modified=file_path.stat().st_mtime,
                 description=description,
                 specializations=specializations,
+                version=version,
+                author=author,
+                tags=tags,
             )
 
+            # Set higher priority for local agents
+            if ".claude-mpm" in str(file_path):
+                if tier == AgentTier.PROJECT:
+                    # Highest priority for project-local agents
+                    metadata.tags.append("local")
+                    metadata.tags.append("project")
+                elif tier == AgentTier.USER:
+                    # High priority for user-local agents
+                    metadata.tags.append("local")
+                    metadata.tags.append("user")
+
+            return metadata
+
         except Exception as e:
             logger.error(f"Failed to create metadata for {file_path}: {e}")
             return None
@@ -387,8 +460,39 @@ class UnifiedAgentRegistry:
 
             if agent_format == AgentFormat.JSON:
                 data = json.loads(content)
-                description = data.get("description", "")
-                specializations = data.get("specializations", [])
+
+                # Ensure data is a dictionary, not a list
+                if not isinstance(data, dict):
+                    logger.warning(
+                        f"Invalid JSON structure in {file_path}: expected object, got {type(data).__name__}"
+                    )
+                    return "", []
+
+                # Handle local agent JSON templates with metadata structure
+                if "metadata" in data:
+                    metadata = data["metadata"]
+                    description = metadata.get(
+                        "description", data.get("description", "")
+                    )
+                    specializations = metadata.get(
+                        "specializations", data.get("specializations", [])
+                    )
+
+                    # Extract tags as specializations if present (handle both formats)
+                    tags_raw = metadata.get("tags", [])
+                    if isinstance(tags_raw, str):
+                        tags = [
+                            tag.strip() for tag in tags_raw.split(",") if tag.strip()
+                        ]
+                    else:
+                        tags = tags_raw if isinstance(tags_raw, list) else []
+                    if tags and not specializations:
+                        specializations = tags
+                else:
+                    # Fallback to direct fields
+                    description = data.get("description", "")
+                    specializations = data.get("specializations", [])
+
             elif agent_format in [AgentFormat.YAML, AgentFormat.YAML]:
                 try:
                     import yaml
@@ -420,8 +524,8 @@ class UnifiedAgentRegistry:
             for _i, line in enumerate(lines[1:], 1):
                 if line.strip() == "---":
                     break
-                if line.startswith("description:"):
-                    return line.split(":", 1)[1].strip().strip("\"'")
+                if line.strip().startswith("description:"):
+                    return line.strip().split(":", 1)[1].strip().strip("\"'")
 
         # Look for first paragraph
         for line in lines:
@@ -455,7 +559,7 @@ class UnifiedAgentRegistry:
         """Apply tier precedence rules to resolve conflicts."""
         # Group agents by their actual name (without tier suffix)
         agent_groups = {}
-        for registry_key, metadata in self.registry.items():
+        for _registry_key, metadata in self.registry.items():
             # Extract the actual agent name (registry_key is "name_tier")
             agent_name = metadata.name  # Use the actual name from metadata
             if agent_name not in agent_groups:
@@ -615,7 +719,7 @@ class UnifiedAgentRegistry:
 
         export_data = {
             "metadata": {
-                "export_time": datetime.now().isoformat(),
+                "export_time": datetime.now(timezone.utc).isoformat(),
                 "total_agents": len(self.registry),
                 "discovery_paths": [str(p) for p in self.discovery_paths],
             },
@@ -624,7 +728,7 @@ class UnifiedAgentRegistry:
             },
         }
 
-        with open(output_path, "w") as f:
+        with output_path.open("w") as f:
             json.dump(export_data, f, indent=2)
 
         logger.info(f"Exported {len(self.registry)} agents to {output_path}")
@@ -633,7 +737,7 @@ class UnifiedAgentRegistry:
         """Import registry from JSON file."""
         input_path = Path(input_path)
 
-        with open(input_path) as f:
+        with input_path.open() as f:
             data = json.load(f)
 
         # Clear current registry

claude_mpm/core/unified_config.py

@@ -436,7 +436,7 @@ class ConfigurationService:
                 if config_path.exists():
                     import yaml
 
-                    with open(config_path) as f:
+                    with config_path.open() as f:
                         file_config = yaml.safe_load(f) or {}
                     config_data.update(file_config)
                     break
@@ -448,7 +448,7 @@ class ConfigurationService:
             raise ConfigurationError(
                 f"Failed to load configuration: {e}",
                 context={"error_type": type(e).__name__},
-            )
+            ) from e
 
     @property
     def config(self) -> UnifiedConfig:
@@ -515,7 +515,7 @@ class ConfigurationService:
                 return True
             raise ConfigurationError("Invalid SocketIO port range")
         except Exception as e:
-            raise ConfigurationError(f"Configuration validation failed: {e}")
+            raise ConfigurationError(f"Configuration validation failed: {e}") from e
 
     def export_to_file(self, file_path: Union[str, Path], format: str = "yaml") -> None:
         """
@@ -531,12 +531,12 @@ class ConfigurationService:
             if format.lower() == "yaml":
                 import yaml
 
-                with open(file_path, "w") as f:
+                with file_path.open("w") as f:
                     yaml.dump(self._config.dict(), f, default_flow_style=False)
             elif format.lower() == "json":
                 import json
 
-                with open(file_path, "w") as f:
+                with file_path.open("w") as f:
                     json.dump(self._config.dict(), f, indent=2)
             else:
                 raise ConfigurationError(f"Unsupported export format: {format}")
@@ -545,4 +545,4 @@ class ConfigurationService:
             raise ConfigurationError(
                 f"Failed to export configuration: {e}",
                 context={"file_path": str(file_path), "format": format},
-            )
+            ) from e

claude_mpm/core/unified_paths.py

@@ -24,7 +24,6 @@ Architecture:
 - Cached properties with smart invalidation
 """
 
-import logging
 import os
 import sys
 from enum import Enum
@@ -32,7 +31,9 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Optional, Union
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
 
 
 class PathType(Enum):
@@ -82,11 +83,12 @@ class PathContext:
             # Check if we're in a src/ directory structure with pyproject.toml
             current = module_path
             for _ in range(5):  # Check up to 5 levels up
-                if (current / "pyproject.toml").exists():
-                    # Found pyproject.toml, check if this looks like a development setup
-                    if (current / "src" / "claude_mpm").exists():
-                        logger.debug(f"Found development installation at {current}")
-                        return True
+                if (current / "pyproject.toml").exists() and (
+                    current / "src" / "claude_mpm"
+                ).exists():
+                    # Found pyproject.toml with development setup
+                    logger.debug(f"Found development installation at {current}")
+                    return True
                 if current == current.parent:
                     break
                 current = current.parent
@@ -177,7 +179,7 @@ class PathContext:
         """
         # Check for environment variable override
         if os.environ.get("CLAUDE_MPM_DEV_MODE", "").lower() in ("1", "true", "yes"):
-            logger.info(
+            logger.debug(
                 "Development mode forced via CLAUDE_MPM_DEV_MODE environment variable"
             )
             return DeploymentContext.DEVELOPMENT
@@ -197,10 +199,10 @@ class PathContext:
                         'name = "claude-mpm"' in pyproject_content
                         or '"claude-mpm"' in pyproject_content
                     ):
-                        logger.info(
+                        logger.debug(
                             f"Detected claude-mpm development directory at {current}"
                         )
-                        logger.info(
+                        logger.debug(
                             "Using development mode for local source preference"
                         )
                         return DeploymentContext.DEVELOPMENT
@@ -218,7 +220,7 @@ class PathContext:
             # 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.info("Detected editable/development installation")
+                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":
@@ -232,7 +234,7 @@ class PathContext:
                         if (current / "src" / "claude_mpm").exists() and (
                             current / "pyproject.toml"
                         ).exists():
-                            logger.info(
+                            logger.debug(
                                 "Running pipx from development directory, using development mode"
                             )
                             return DeploymentContext.DEVELOPMENT
@@ -248,33 +250,33 @@ class PathContext:
                 module_path.parent.name == "src"
                 and (module_path.parent.parent / "src" / "claude_mpm").exists()
             ):
-                logger.info(
+                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.info(f"Detected pipx installation at {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):
-                logger.info(f"Detected system package installation at {module_path}")
+                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.info(f"Detected pip installation at {module_path}")
+                logger.debug(f"Detected pip installation at {module_path}")
                 return DeploymentContext.PIP_INSTALL
 
             # Default to pip install
-            logger.info(f"Defaulting to pip installation for {module_path}")
+            logger.debug(f"Defaulting to pip installation for {module_path}")
             return DeploymentContext.PIP_INSTALL
 
         except ImportError:
-            logger.info(
+            logger.debug(
                 "ImportError during context detection, defaulting to development"
             )
             return DeploymentContext.DEVELOPMENT
@@ -320,7 +322,8 @@ class UnifiedPathManager:
         ]
         self._initialized = True
 
-        logger.info(
+        # Use debug level for initialization details
+        logger.debug(
             f"UnifiedPathManager initialized with context: {self._deployment_context.value}"
         )
 
@@ -394,7 +397,7 @@ class UnifiedPathManager:
                     return current
                 current = current.parent
 
-            raise FileNotFoundError("Could not determine framework root")
+            raise FileNotFoundError("Could not determine framework root") from None
 
     @property
     @lru_cache(maxsize=1)

claude_mpm/dashboard/.claude-mpm/socketio-instances.json

@@ -0,0 +1 @@
+{}

claude_mpm/dashboard/__init__.py

@@ -0,0 +1,12 @@
+"""
+Dashboard package for Claude MPM.
+
+This package contains the web-based dashboard components for Claude MPM,
+including the analysis runner, dashboard opener, and static web assets.
+
+The dashboard provides real-time monitoring, analysis visualization, and
+interactive debugging capabilities for Claude MPM operations.
+
+This __init__.py file is required to make this directory recognizable as a
+Python package by setuptools for proper distribution and imports.
+"""