claude-mpm 3.5.4__py3-none-any.whl → 3.6.0__py3-none-any.whl

claude_mpm/schemas/agent_schema.json

@@ -0,0 +1,435 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "version": "1.2.0",
+  "title": "Claude MPM Agent Schema",
+  "description": "Schema definition for Claude MPM agent templates. This schema enforces the structure and validation rules for all agent configurations in the Claude MPM system.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "agent_id",
+    "agent_version",
+    "agent_type",
+    "metadata",
+    "capabilities",
+    "instructions"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Schema version for the agent template format. This ensures compatibility between the agent template and the schema validator. Must be updated when breaking changes are made to the schema.",
+      "examples": ["1.0.0", "1.2.0"]
+    },
+    "agent_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Unique agent identifier used for agent discovery and loading. This ID must be unique across all agents in the system and follows snake_case naming convention.",
+      "examples": ["research_agent", "engineer_agent", "qa_agent", "security_agent"]
+    },
+    "agent_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the agent template itself (not the schema). Increment major for breaking changes, minor for new features, patch for bug fixes.",
+      "examples": ["1.0.0", "2.1.3"]
+    },
+    "agent_type": {
+      "type": "string",
+      "description": "Type of agent that determines its primary function and default capabilities. This categorization helps in agent discovery and capability matching.",
+      "enum": [
+        "base",
+        "engineer",
+        "qa",
+        "documentation",
+        "research",
+        "security",
+        "ops",
+        "data_engineer",
+        "version_control"
+      ]
+    },
+    "metadata": {
+      "type": "object",
+      "required": [
+        "name",
+        "description",
+        "tags"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 3,
+          "maxLength": 50,
+          "description": "Human-readable agent name displayed in UI and logs. Should be concise but descriptive."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 10,
+          "maxLength": 200,
+          "description": "Brief description of agent purpose and capabilities. Used in agent selection and documentation."
+        },
+        "category": {
+          "type": "string",
+          "enum": ["engineering", "research", "quality", "operations", "specialized"],
+          "description": "Agent category for organization"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "minItems": 1,
+          "maxItems": 10,
+          "uniqueItems": true,
+          "description": "Tags for agent discovery and categorization. Used by the agent registry for searching and filtering."
+        },
+        "author": {
+          "type": "string",
+          "description": "Agent template author"
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Creation timestamp"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Last update timestamp"
+        },
+        "color": {
+          "type": "string",
+          "enum": ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"],
+          "description": "Agent color for visual identification in Claude Code interface. Helps distinguish agents at a glance."
+        }
+      }
+    },
+    "dependencies": {
+      "type": "object",
+      "description": "External dependencies required for this agent to function properly",
+      "properties": {
+        "python": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Python packages required (pip installable) with optional version specifiers",
+          "examples": [["tree-sitter>=0.21.0", "pandas>=2.0.0"]]
+        },
+        "system": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "System-level dependencies (e.g., commands that should be available in PATH)",
+          "examples": [["ripgrep", "git", "docker"]]
+        },
+        "optional": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether these dependencies are optional (agent can function without them)"
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "required": [
+        "model",
+        "tools",
+        "resource_tier"
+      ],
+      "properties": {
+        "model": {
+          "type": "string",
+          "enum": [
+            "opus",
+            "sonnet",
+            "haiku"
+          ],
+          "description": "Claude model tier to use for this agent. Choose based on task complexity and performance requirements: opus (most capable), sonnet (balanced), haiku (fastest)."
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "Read",
+              "Write",
+              "Edit",
+              "MultiEdit",
+              "Grep",
+              "Glob",
+              "LS",
+              "Bash",
+              "WebSearch",
+              "WebFetch",
+              "NotebookRead",
+              "NotebookEdit",
+              "TodoWrite",
+              "ExitPlanMode",
+              "git",
+              "docker",
+              "kubectl",
+              "terraform",
+              "aws",
+              "gcloud",
+              "azure"
+            ]
+          },
+          "uniqueItems": true,
+          "description": "Available tools for the agent. Tools determine what operations the agent can perform."
+        },
+        "resource_tier": {
+          "type": "string",
+          "enum": [
+            "basic",
+            "standard",
+            "intensive",
+            "lightweight"
+          ],
+          "description": "Resource allocation tier that determines memory, CPU, and timeout limits. See definitions section for specific limits."
+        },
+        "max_tokens": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 200000,
+          "default": 8192,
+          "description": "Maximum tokens for response generation. Higher values allow longer responses but increase cost and latency."
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.7,
+          "description": "Model temperature setting controlling response randomness. Lower values for consistency, higher for creativity."
+        },
+        "timeout": {
+          "type": "integer",
+          "minimum": 30,
+          "maximum": 3600,
+          "default": 300,
+          "description": "Operation timeout in seconds. Should align with resource_tier settings."
+        },
+        "memory_limit": {
+          "type": "integer",
+          "minimum": 512,
+          "maximum": 8192,
+          "description": "Memory limit in MB (for resource tier)"
+        },
+        "cpu_limit": {
+          "type": "integer",
+          "minimum": 10,
+          "maximum": 100,
+          "description": "CPU limit percentage (for resource tier)"
+        },
+        "network_access": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether agent needs network access"
+        },
+        "file_access": {
+          "type": "object",
+          "properties": {
+            "read_paths": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Allowed read paths"
+            },
+            "write_paths": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Allowed write paths"
+            }
+          }
+        },
+        "allowed_tools": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Glob patterns for allowed file paths. Restricts which files the agent can access (e.g., 'tests/**' for test files only)."
+        },
+        "disallowed_tools": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Tool names to explicitly disallow, overriding the tools array. Use for security restrictions (e.g., 'Bash' to prevent shell access)."
+        }
+      }
+    },
+    "instructions": {
+      "type": "string",
+      "minLength": 100,
+      "maxLength": 8000,
+      "description": "Agent system instructions that define behavior, approach, and constraints. This becomes the agent's system prompt."
+    },
+    "knowledge": {
+      "type": "object",
+      "description": "Agent-specific knowledge and context",
+      "properties": {
+        "domain_expertise": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Areas of expertise"
+        },
+        "best_practices": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Best practices the agent follows"
+        },
+        "constraints": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Operating constraints"
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "scenario": {"type": "string"},
+              "approach": {"type": "string"}
+            }
+          },
+          "description": "Example scenarios and approaches"
+        }
+      }
+    },
+    "interactions": {
+      "type": "object",
+      "description": "Agent interaction patterns",
+      "properties": {
+        "input_format": {
+          "type": "object",
+          "properties": {
+            "required_fields": {
+              "type": "array",
+              "items": {"type": "string"}
+            },
+            "optional_fields": {
+              "type": "array",
+              "items": {"type": "string"}
+            }
+          }
+        },
+        "output_format": {
+          "type": "object",
+          "properties": {
+            "structure": {
+              "type": "string",
+              "enum": ["markdown", "json", "structured", "free-form"]
+            },
+            "includes": {
+              "type": "array",
+              "items": {"type": "string"}
+            }
+          }
+        },
+        "handoff_agents": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Agents this agent can hand off to"
+        },
+        "triggers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "condition": {"type": "string"},
+              "action": {"type": "string"}
+            }
+          },
+          "description": "Conditions that trigger specific actions"
+        }
+      }
+    },
+    "testing": {
+      "type": "object",
+      "description": "Testing configuration for the agent",
+      "properties": {
+        "test_cases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["input", "expected_behavior"],
+            "properties": {
+              "name": {"type": "string"},
+              "input": {"type": "string"},
+              "expected_behavior": {"type": "string"},
+              "validation_criteria": {
+                "type": "array",
+                "items": {"type": "string"}
+              }
+            }
+          }
+        },
+        "performance_benchmarks": {
+          "type": "object",
+          "properties": {
+            "response_time": {"type": "integer"},
+            "token_usage": {"type": "integer"},
+            "success_rate": {"type": "number"}
+          }
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Hook configurations for extensibility",
+      "properties": {
+        "pre_execution": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {"type": "string"},
+              "enabled": {"type": "boolean"}
+            }
+          }
+        },
+        "post_execution": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {"type": "string"},
+              "enabled": {"type": "boolean"}
+            }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "model_mappings": {
+      "description": "Mappings for model normalization from full names to tiers",
+      "mappings": {
+        "claude-3-5-sonnet-20241022": "sonnet",
+        "claude-3-5-sonnet-20240620": "sonnet",
+        "claude-sonnet-4-20250514": "sonnet",
+        "claude-4-sonnet-20250514": "sonnet",
+        "claude-3-sonnet-20240229": "sonnet",
+        "claude-3-opus-20240229": "opus",
+        "claude-opus-4-20250514": "opus",
+        "claude-4-opus-20250514": "opus",
+        "claude-3-haiku-20240307": "haiku",
+        "claude-3-5-haiku-20241022": "haiku"
+      }
+    },
+    "resource_tier_limits": {
+      "intensive": {
+        "memory_limit": {"min": 4096, "max": 8192},
+        "cpu_limit": {"min": 60, "max": 100},
+        "timeout": {"min": 600, "max": 3600}
+      },
+      "standard": {
+        "memory_limit": {"min": 2048, "max": 4096},
+        "cpu_limit": {"min": 30, "max": 60},
+        "timeout": {"min": 300, "max": 1200}
+      },
+      "lightweight": {
+        "memory_limit": {"min": 512, "max": 2048},
+        "cpu_limit": {"min": 10, "max": 30},
+        "timeout": {"min": 30, "max": 600}
+      }
+    }
+  }
+}

claude_mpm/scripts/__init__.py

@@ -0,0 +1,15 @@
+"""
+Production scripts for claude-mpm.
+
+WHY: This module contains production-ready scripts that can be run independently
+for various claude-mpm operations like activity logging, monitoring, etc.
+
+DESIGN DECISION: These scripts are kept as part of the main package rather than
+in the top-level scripts/ directory to ensure they have proper access to the
+claude_mpm module and can be distributed with the package.
+"""
+
+# Export commonly used scripts for programmatic access
+from .start_activity_logging import signal_handler
+
+__all__ = ['signal_handler']

claude_mpm/scripts/start_activity_logging.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+Start the event aggregator service for activity logging.
+
+This script starts the event aggregator that captures all agent activity
+from the Socket.IO dashboard and saves it to .claude-mpm/activity/
+"""
+
+import sys
+import time
+import signal
+from pathlib import Path
+
+# Since we're now inside the claude_mpm package, use relative imports
+from ..core.config import Config
+from ..services.event_aggregator import EventAggregator
+from ..core.logger import get_logger
+
+logger = get_logger("activity_logging")
+
+def signal_handler(signum, frame):
+    """Handle shutdown signals gracefully."""
+    logger.info("Shutting down activity logging...")
+    if aggregator:
+        aggregator.stop()
+    sys.exit(0)
+
+if __name__ == "__main__":
+    # Load configuration
+    config = Config()
+    
+    # Check if event aggregator is enabled
+    if not config.get('event_aggregator.enabled', True):
+        logger.warning("Event aggregator is disabled in configuration")
+        logger.warning("Enable it by setting event_aggregator.enabled: true")
+        sys.exit(1)
+    
+    # Get configuration values
+    activity_dir = config.get('event_aggregator.activity_directory', '.claude-mpm/activity')
+    dashboard_port = config.get('event_aggregator.dashboard_port', 8765)
+    
+    logger.info("=" * 60)
+    logger.info("Starting Activity Logging Service")
+    logger.info("=" * 60)
+    logger.info(f"Activity Directory: {activity_dir}")
+    logger.info(f"Dashboard Port: {dashboard_port}")
+    logger.info("Connecting to Socket.IO dashboard...")
+    
+    # Initialize aggregator
+    aggregator = EventAggregator(
+        host="localhost",
+        port=dashboard_port,
+        save_dir=None  # Will use config value
+    )
+    
+    # Set up signal handlers
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+    
+    # Start the aggregator
+    try:
+        aggregator.start()
+        logger.info("✅ Activity logging started successfully!")
+        logger.info(f"📁 Saving activity to: {aggregator.save_dir}")
+        logger.info("Press Ctrl+C to stop")
+        
+        # Keep running and show periodic status
+        while aggregator.running:
+            time.sleep(30)
+            
+            # Show status every 30 seconds
+            status = aggregator.get_status()
+            if status['active_sessions'] > 0:
+                logger.info(f"📊 Status: {status['active_sessions']} active sessions, "
+                          f"{status['total_events']} events captured")
+            
+    except KeyboardInterrupt:
+        logger.info("Received shutdown signal")
+    except Exception as e:
+        logger.error(f"Error running activity logging: {e}")
+    finally:
+        if aggregator:
+            aggregator.stop()
+            # Save any remaining sessions
+            aggregator._save_all_sessions()
+            logger.info("Activity logging stopped")