claude-mpm 3.5.2__py3-none-any.whl → 3.5.6__py3-none-any.whl

claude_mpm/core/claude_runner.py

@@ -74,8 +74,16 @@ class ClaudeRunner:
                 self.logger.warning(f"Failed to initialize project logger: {e}")
         
         # Initialize services with proper error handling
+        # Determine the user's working directory from environment
+        user_working_dir = None
+        if 'CLAUDE_MPM_USER_PWD' in os.environ:
+            user_working_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+            self.logger.info(f"Using user working directory from CLAUDE_MPM_USER_PWD: {user_working_dir}")
+        
         try:
-            self.deployment_service = AgentDeploymentService()
+            # Pass the user working directory to the deployment service
+            # This ensures agents are deployed to the correct user directory, not the framework directory
+            self.deployment_service = AgentDeploymentService(working_directory=user_working_dir)
         except ImportError as e:
             self.logger.error(f"Failed to import AgentDeploymentService: {e}")
             raise RuntimeError("Required module AgentDeploymentService not available. Please reinstall claude-mpm.") from e
@@ -110,6 +118,22 @@ class ClaudeRunner:
             self.logger.error(f"Failed to load configuration: {e}")
             raise RuntimeError(f"Configuration initialization failed: {e}") from e
         
+        # Initialize response logging if enabled
+        self.response_logger = None
+        response_config = self.config.get('response_logging', {})
+        if response_config.get('enabled', False):
+            try:
+                from claude_mpm.services.claude_session_logger import get_session_logger
+                self.response_logger = get_session_logger(self.config)
+                if self.project_logger:
+                    self.project_logger.log_system(
+                        "Response logging initialized",
+                        level="INFO",
+                        component="logging"
+                    )
+            except Exception as e:
+                self.logger.warning(f"Failed to initialize response logger: {e}")
+        
         # Initialize hook service
         try:
             self.hook_service = HookService(self.config)
@@ -199,7 +223,7 @@ class ClaudeRunner:
             return False
         
         except FileNotFoundError as e:
-            error_msg = f"Agent templates not found: {e}"
+            error_msg = f"Agent files not found: {e}"
             self.logger.error(error_msg)
             print(f"❌ {error_msg}")
             print("💡 Ensure claude-mpm is properly installed")
@@ -228,16 +252,21 @@ class ClaudeRunner:
     def ensure_project_agents(self) -> bool:
         """Ensure system agents are available in the project directory.
         
-        Deploys system agents to project's .claude-mpm/agents/ directory
-        if they don't exist or are outdated. This enables project-level
-        agent customization and ensures all agents are available locally.
+        Deploys system agents to project's .claude/agents/ directory
+        if they don't exist or are outdated. This ensures agents are
+        available for Claude Code to use. Project-specific JSON templates
+        should be placed in .claude-mpm/agents/.
         
         Returns:
             bool: True if agents are available, False on error
         """
         try:
-            # Check if we're in a project directory
-            project_dir = Path.cwd()
+            # Use the correct user directory, not the framework directory
+            if 'CLAUDE_MPM_USER_PWD' in os.environ:
+                project_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+            else:
+                project_dir = Path.cwd()
+            
             project_agents_dir = project_dir / ".claude-mpm" / "agents"
             
             # Create directory if it doesn't exist
@@ -250,10 +279,12 @@ class ClaudeRunner:
                     component="deployment"
                 )
             
-            # Deploy agents to project directory with project deployment mode
+            # Deploy agents to project's .claude/agents directory (not .claude-mpm)
             # This ensures all system agents are deployed regardless of version
+            # .claude-mpm/agents/ should only contain JSON source templates
+            # .claude/agents/ should contain the built MD files for Claude Code
             results = self.deployment_service.deploy_agents(
-                target_dir=project_dir / ".claude-mpm",
+                target_dir=project_dir / ".claude",
                 force_rebuild=False,
                 deployment_mode="project"
             )
@@ -286,8 +317,164 @@ class ClaudeRunner:
                 )
             return False
     
+    def deploy_project_agents_to_claude(self) -> bool:
+        """Deploy project agents from .claude-mpm/agents/ to .claude/agents/.
+        
+        This method handles the deployment of project-specific agents (JSON format)
+        from the project's agents directory to Claude's agent directory.
+        Project agents take precedence over system agents.
+        
+        WHY: Project agents allow teams to define custom, project-specific agents
+        that override system agents. These are stored in JSON format in 
+        .claude-mpm/agents/ and need to be deployed to .claude/agents/
+        as MD files for Claude to use them.
+        
+        Returns:
+            bool: True if deployment successful or no agents to deploy, False on error
+        """
+        try:
+            # Use the correct user directory, not the framework directory
+            if 'CLAUDE_MPM_USER_PWD' in os.environ:
+                project_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+            else:
+                project_dir = Path.cwd()
+            
+            project_agents_dir = project_dir / ".claude-mpm" / "agents"
+            claude_agents_dir = project_dir / ".claude" / "agents"
+            
+            # Check if project agents directory exists
+            if not project_agents_dir.exists():
+                self.logger.debug("No project agents directory found")
+                return True  # Not an error - just no project agents
+            
+            # Get JSON agent files from agents directory
+            json_files = list(project_agents_dir.glob("*.json"))
+            if not json_files:
+                self.logger.debug("No JSON agents in project")
+                return True
+            
+            # Create .claude/agents directory if needed
+            claude_agents_dir.mkdir(parents=True, exist_ok=True)
+            
+            self.logger.info(f"Deploying {len(json_files)} project agents to .claude/agents/")
+            if self.project_logger:
+                self.project_logger.log_system(
+                    f"Deploying project agents from {project_agents_dir} to {claude_agents_dir}",
+                    level="INFO",
+                    component="deployment"
+                )
+            
+            deployed_count = 0
+            updated_count = 0
+            errors = []
+            
+            # Deploy each JSON agent
+            # CRITICAL: PM (Project Manager) must NEVER be deployed as it's the main Claude instance
+            EXCLUDED_AGENTS = {'pm', 'project_manager'}
+            
+            # Initialize deployment service with proper base agent path
+            # Use the existing deployment service's base agent path if available
+            base_agent_path = project_agents_dir / "base_agent.json"
+            if not base_agent_path.exists():
+                # Fall back to system base agent
+                base_agent_path = self.deployment_service.base_agent_path
+            
+            # Create a single deployment service instance for all agents
+            project_deployment = AgentDeploymentService(
+                templates_dir=project_agents_dir,
+                base_agent_path=base_agent_path,
+                working_directory=project_dir  # Pass the project directory
+            )
+            
+            # Load base agent data once
+            base_agent_data = {}
+            if base_agent_path and base_agent_path.exists():
+                try:
+                    import json
+                    base_agent_data = json.loads(base_agent_path.read_text())
+                except Exception as e:
+                    self.logger.warning(f"Could not load base agent: {e}")
+            
+            for json_file in json_files:
+                try:
+                    agent_name = json_file.stem
+                    
+                    # Skip PM agent - it's the main Claude instance, not a subagent
+                    if agent_name.lower() in EXCLUDED_AGENTS:
+                        self.logger.info(f"Skipping {agent_name} (PM is the main Claude instance)")
+                        continue
+                    
+                    target_file = claude_agents_dir / f"{agent_name}.md"
+                    
+                    # Check if agent needs update
+                    needs_update = True
+                    if target_file.exists():
+                        # Check if it's a project agent (has project marker)
+                        existing_content = target_file.read_text()
+                        if "author: claude-mpm-project" in existing_content or "source: project" in existing_content:
+                            # Compare modification times
+                            if target_file.stat().st_mtime >= json_file.stat().st_mtime:
+                                needs_update = False
+                                self.logger.debug(f"Project agent {agent_name} is up to date")
+                    
+                    if needs_update:
+                        # Build the agent markdown using the pre-initialized service and base agent data
+                        agent_content = project_deployment._build_agent_markdown(
+                            agent_name, json_file, base_agent_data
+                        )
+                        
+                        # Mark as project agent
+                        agent_content = agent_content.replace(
+                            "author: claude-mpm",
+                            "author: claude-mpm-project"
+                        )
+                        
+                        # Write the agent file
+                        is_update = target_file.exists()
+                        target_file.write_text(agent_content)
+                        
+                        if is_update:
+                            updated_count += 1
+                            self.logger.info(f"Updated project agent: {agent_name}")
+                        else:
+                            deployed_count += 1
+                            self.logger.info(f"Deployed project agent: {agent_name}")
+                            
+                except Exception as e:
+                    error_msg = f"Failed to deploy project agent {json_file.name}: {e}"
+                    self.logger.error(error_msg)
+                    errors.append(error_msg)
+            
+            # Report results
+            if deployed_count > 0 or updated_count > 0:
+                print(f"✓ Deployed {deployed_count} project agents, updated {updated_count}")
+                if self.project_logger:
+                    self.project_logger.log_system(
+                        f"Project agent deployment: {deployed_count} deployed, {updated_count} updated",
+                        level="INFO",
+                        component="deployment"
+                    )
+            
+            if errors:
+                for error in errors:
+                    print(f"⚠️  {error}")
+                return False
+            
+            return True
+            
+        except Exception as e:
+            error_msg = f"Failed to deploy project agents: {e}"
+            self.logger.error(error_msg)
+            print(f"⚠️  {error_msg}")
+            if self.project_logger:
+                self.project_logger.log_system(error_msg, level="ERROR", component="deployment")
+            return False
+    
     def run_interactive(self, initial_context: Optional[str] = None):
         """Run Claude in interactive mode."""
+        # TODO: Add response logging for interactive mode
+        # This requires capturing stdout from the exec'd process or using subprocess with PTY
+        
         # Connect to Socket.IO server if enabled
         if self.enable_websocket:
             try:
@@ -336,10 +523,13 @@ class ClaudeRunner:
                 component="session"
             )
         
-        # Setup agents
+        # Setup agents - first deploy system agents, then project agents
         if not self.setup_agents():
             print("Continuing without native agents...")
         
+        # Deploy project-specific agents if they exist
+        self.deploy_project_agents_to_claude()
+        
         # Build command with system instructions
         cmd = [
             "claude",
@@ -587,10 +777,13 @@ class ClaudeRunner:
                 component="session"
             )
         
-        # Setup agents
+        # Setup agents - first deploy system agents, then project agents
         if not self.setup_agents():
             print("Continuing without native agents...")
         
+        # Deploy project-specific agents if they exist
+        self.deploy_project_agents_to_claude()
+        
         # Combine context and prompt
         full_prompt = prompt
         if context:
@@ -671,6 +864,22 @@ class ClaudeRunner:
                 response = result.stdout.strip()
                 print(response)
                 
+                # Log response if logging enabled
+                if self.response_logger and response:
+                    execution_time = time.time() - start_time
+                    response_summary = prompt[:200] + "..." if len(prompt) > 200 else prompt
+                    self.response_logger.log_response(
+                        request_summary=response_summary,
+                        response_content=response,
+                        metadata={
+                            "mode": "oneshot",
+                            "model": "opus",
+                            "exit_code": result.returncode,
+                            "execution_time": execution_time
+                        },
+                        agent="claude-direct"
+                    )
+                
                 # Broadcast output to WebSocket clients
                 if self.websocket_server and response:
                     self.websocket_server.claude_output(response, "stdout")
@@ -884,17 +1093,46 @@ class ClaudeRunner:
     def _load_system_instructions(self) -> Optional[str]:
         """Load and process system instructions from agents/INSTRUCTIONS.md.
         
-        WHY: Process template variables like {{capabilities-list}} to include
-        dynamic agent capabilities in the PM's system instructions.
+        Implements project > framework precedence:
+        1. First check for project-specific instructions in .claude-mpm/agents/INSTRUCTIONS.md
+        2. If not found, fall back to framework instructions in src/claude_mpm/agents/INSTRUCTIONS.md
+        
+        WHY: Allows projects to override the default PM instructions with project-specific
+        guidance, while maintaining backward compatibility with the framework defaults.
+        
+        DESIGN DECISION: Using CLAUDE_MPM_USER_PWD environment variable to locate the
+        correct project directory, ensuring we check the right location even when
+        claude-mpm is invoked from a different directory.
         """
         try:
-            # Find the INSTRUCTIONS.md file
-            module_path = Path(__file__).parent.parent
-            instructions_path = module_path / "agents" / "INSTRUCTIONS.md"
+            # Determine the user's project directory
+            if 'CLAUDE_MPM_USER_PWD' in os.environ:
+                project_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+            else:
+                project_dir = Path.cwd()
             
-            if not instructions_path.exists():
-                self.logger.warning(f"System instructions not found: {instructions_path}")
-                return None
+            # Check for project-specific INSTRUCTIONS.md first
+            project_instructions_path = project_dir / ".claude-mpm" / "agents" / "INSTRUCTIONS.md"
+            
+            instructions_path = None
+            instructions_source = None
+            
+            if project_instructions_path.exists():
+                instructions_path = project_instructions_path
+                instructions_source = "PROJECT"
+                self.logger.info(f"Found project-specific INSTRUCTIONS.md: {instructions_path}")
+            else:
+                # Fall back to framework instructions
+                module_path = Path(__file__).parent.parent
+                framework_instructions_path = module_path / "agents" / "INSTRUCTIONS.md"
+                
+                if framework_instructions_path.exists():
+                    instructions_path = framework_instructions_path
+                    instructions_source = "FRAMEWORK"
+                    self.logger.info(f"Using framework INSTRUCTIONS.md: {instructions_path}")
+                else:
+                    self.logger.warning(f"No INSTRUCTIONS.md found in project or framework")
+                    return None
             
             # Read raw instructions
             raw_instructions = instructions_path.read_text()
@@ -904,13 +1142,15 @@ class ClaudeRunner:
                 from claude_mpm.services.framework_claude_md_generator.content_assembler import ContentAssembler
                 assembler = ContentAssembler()
                 processed_instructions = assembler.apply_template_variables(raw_instructions)
-                self.logger.info("Loaded and processed PM framework system instructions with dynamic capabilities")
+                self.logger.info(f"Loaded and processed {instructions_source} PM instructions with dynamic capabilities")
                 return processed_instructions
             except ImportError:
                 self.logger.warning("ContentAssembler not available, using raw instructions")
+                self.logger.info(f"Loaded {instructions_source} PM instructions (raw)")
                 return raw_instructions
             except Exception as e:
                 self.logger.warning(f"Failed to process template variables: {e}, using raw instructions")
+                self.logger.info(f"Loaded {instructions_source} PM instructions (raw, processing failed)")
                 return raw_instructions
             
         except Exception as e:
@@ -1185,6 +1425,10 @@ class ClaudeRunner:
         import tty
         import signal
         
+        # Collect output for response logging if enabled
+        collected_output = [] if self.response_logger else None
+        collected_input = [] if self.response_logger else None
+        
         # Save original terminal settings
         original_tty = None
         if sys.stdin.isatty():
@@ -1247,6 +1491,13 @@ class ClaudeRunner:
                         data = os.read(master_fd, 4096)
                         if data:
                             os.write(sys.stdout.fileno(), data)
+                            # Collect output for response logging
+                            if collected_output is not None:
+                                try:
+                                    output_text = data.decode('utf-8', errors='replace')
+                                    collected_output.append(output_text)
+                                except Exception:
+                                    pass
                             # Broadcast output to WebSocket clients
                             if self.websocket_server:
                                 try:
@@ -1265,12 +1516,38 @@ class ClaudeRunner:
                         data = os.read(sys.stdin.fileno(), 4096)
                         if data:
                             os.write(master_fd, data)
+                            # Collect input for response logging
+                            if collected_input is not None:
+                                try:
+                                    input_text = data.decode('utf-8', errors='replace')
+                                    collected_input.append(input_text)
+                                except Exception:
+                                    pass
                     except OSError:
                         break
             
             # Wait for process to complete
             process.wait()
             
+            # Log the interactive session if response logging is enabled
+            if self.response_logger and collected_output is not None and collected_output:
+                try:
+                    full_output = ''.join(collected_output)
+                    full_input = ''.join(collected_input) if collected_input else "Interactive session"
+                    self.response_logger.log_response(
+                        request_summary=f"Interactive session: {full_input[:200]}..." if len(full_input) > 200 else f"Interactive session: {full_input}",
+                        response_content=full_output,
+                        metadata={
+                            "mode": "interactive-subprocess",
+                            "model": "opus",
+                            "exit_code": process.returncode,
+                            "session_type": "subprocess"
+                        },
+                        agent="claude-interactive"
+                    )
+                except Exception as e:
+                    self.logger.debug(f"Failed to log interactive session: {e}")
+            
             if self.project_logger:
                 self.project_logger.log_system(
                     f"Claude subprocess exited with code {process.returncode}",

claude_mpm/core/config_paths.py

@@ -35,7 +35,6 @@ class ConfigPaths:
     RESPONSES_DIR = "responses"
     
     # Agent subdirectories
-    AGENT_PROJECT_SPECIFIC = "project-specific"
     AGENT_USER_AGENTS = "user-agents"
     AGENT_USER_DEFINED = "user-defined"
     AGENT_SYSTEM = "templates"

claude_mpm/core/factories.py

@@ -57,14 +57,20 @@ class AgentServiceFactory(ServiceFactory):
         config = container.resolve(Config)
         
         # Get directories from config if not provided
+        import os
+        
         if framework_dir is None:
             framework_dir = Path(config.get('framework.dir', 'framework'))
             
         if project_dir is None:
-            project_dir = Path(config.get('project.dir', '.'))
+            # Check for user working directory from environment
+            if 'CLAUDE_MPM_USER_PWD' in os.environ:
+                project_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+            else:
+                project_dir = Path(config.get('project.dir', '.'))
             
-        # Create service with dependencies
-        service = AgentDeploymentService()
+        # Create service with proper working directory
+        service = AgentDeploymentService(working_directory=project_dir)
         
         # Inject any required dependencies
         if hasattr(service, 'set_directories'):

claude_mpm/dashboard/.claude-mpm/memories/README.md

@@ -0,0 +1,36 @@
+# Agent Memory System
+
+## Purpose
+Each agent maintains project-specific knowledge in these files. Agents read their memory file before tasks and update it when they learn something new.
+
+## Manual Editing
+Feel free to edit these files to:
+- Add project-specific guidelines
+- Remove outdated information  
+- Reorganize for better clarity
+- Add domain-specific knowledge
+
+## Memory Limits
+- Max file size: 8KB (~2000 tokens)
+- Max sections: 10
+- Max items per section: 15
+- Files auto-truncate when limits exceeded
+
+## File Format
+Standard markdown with structured sections. Agents expect:
+- Project Architecture
+- Implementation Guidelines
+- Common Mistakes to Avoid
+- Current Technical Context
+
+## How It Works
+1. Agents read their memory file before starting tasks
+2. Agents add learnings during or after task completion
+3. Files automatically enforce size limits
+4. Developers can manually edit for accuracy
+
+## Memory File Lifecycle
+- Created automatically when agent first runs
+- Updated through hook system after delegations
+- Manually editable by developers
+- Version controlled with project

claude_mpm/dashboard/README.md

@@ -0,0 +1,121 @@
+# Claude MPM Web Dashboard
+
+This directory contains the modular web dashboard for Claude MPM monitoring and management.
+
+## Structure
+
+```
+src/claude_mpm/dashboard/
+├── static/
+│   ├── css/
+│   │   └── dashboard.css          # Main stylesheet
+│   └── js/
+│       ├── socket-client.js       # Socket.IO connection management
+│       ├── dashboard.js          # Main dashboard application
+│       └── components/
+│           ├── event-viewer.js    # Event display and filtering
+│           ├── module-viewer.js   # Event detail viewer
+│           └── session-manager.js # Session management
+├── templates/
+│   └── index.html               # Main dashboard HTML
+├── index.html                   # Root index with redirect
+├── test_dashboard.html          # Test version for verification
+└── README.md                    # This file
+```
+
+## Components
+
+### SocketClient (`socket-client.js`)
+- Manages WebSocket connections to the Claude MPM server
+- Handles event reception and processing
+- Provides callbacks for connection state changes
+- Maintains event history and session tracking
+
+### EventViewer (`components/event-viewer.js`)
+- Displays events in a filterable list
+- Supports search, type filtering, and session filtering
+- Handles event selection and keyboard navigation
+- Updates metrics display (total events, events per minute, etc.)
+
+### ModuleViewer (`components/module-viewer.js`)
+- Shows detailed information about selected events
+- Provides structured views for different event types
+- Displays raw JSON data for debugging
+- Organizes events by class/category
+
+### SessionManager (`components/session-manager.js`)
+- Manages session selection and filtering
+- Updates session dropdown with available sessions
+- Tracks current active session
+- Updates footer information
+
+### Dashboard (`dashboard.js`)
+- Main application coordinator
+- Handles tab switching between Events, Agents, Tools, and Files
+- Manages component interactions
+- Provides global functions for backward compatibility
+
+## Features
+
+### File-Centric Files Tab
+The Files tab now shows a file-centric view where:
+- Each file appears only once in the list
+- Files show read/write icons based on operations performed
+- Most recently accessed files appear at the bottom
+- Clicking a file shows all operations performed on it with timestamps and agent information
+
+### Tab Organization
+- **Events**: All events with filtering and search
+- **Agents**: Agent-specific events and operations
+- **Tools**: Tool usage and parameters
+- **Files**: File operations organized by file path
+
+### Enhanced Event Details
+- Structured views for different event types
+- Todo checklists with status indicators
+- Agent and tool information
+- Session tracking and filtering
+
+## Usage
+
+### Development
+For development and testing, use `test_dashboard.html` which includes module verification.
+
+### Production
+Use `templates/dashboard.html` as the main template, ensuring all static files are served correctly.
+
+### Integration
+The dashboard can be integrated into a Flask/FastAPI application by serving the static files and using the template.
+
+## Migration from Original
+
+The original monolithic `claude_mpm_socketio_dashboard.html` has been replaced with a modular structure:
+
+1. **CSS**: Extracted to `static/css/dashboard.css`
+2. **JavaScript**: Split into logical modules in `static/js/`
+3. **HTML**: Clean template in `templates/dashboard.html`
+
+All original functionality has been preserved while improving:
+- Code organization and maintainability
+- Module reusability
+- Easier debugging and development
+- Better separation of concerns
+
+## Backward Compatibility
+
+Global functions are maintained for compatibility:
+- `connectSocket()`
+- `disconnectSocket()`
+- `clearEvents()`
+- `exportEvents()`
+- `clearSelection()`
+- `switchTab(tabName)`
+
+## Browser Support
+
+Requires modern browsers with support for:
+- ES6 Classes
+- Fetch API
+- Custom Events
+- CSS Grid/Flexbox
+- Socket.IO 4.x