claude-mpm 4.7.4__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/utils/robust_installer.py

@@ -9,6 +9,7 @@ DESIGN DECISION: We implement exponential backoff for retries and provide
 multiple installation strategies (pip, conda, source) to maximize success rate.
 """
 
+import os
 import re
 import subprocess
 import sys
@@ -80,6 +81,7 @@ class RobustPackageInstaller:
         self.use_cache = use_cache
         self.attempts: List[InstallAttempt] = []
         self.success_cache: Dict[str, bool] = {}
+        self.in_virtualenv = self._check_virtualenv()
         self.is_pep668_managed = self._check_pep668_managed()
         self.pep668_warning_shown = False
 
@@ -201,6 +203,35 @@ class RobustPackageInstaller:
         except Exception as e:
             return False, f"Unexpected error: {e!s}"
 
+    def _check_virtualenv(self) -> bool:
+        """
+        Check if running inside a virtual environment.
+
+        WHY: Virtual environments are already isolated and don't need
+        --user or --break-system-packages flags. In fact, using --user
+        in a virtualenv causes errors.
+
+        Returns:
+            True if in a virtualenv, False otherwise
+        """
+        # Multiple ways to detect virtualenv
+        return (
+            (
+                # venv creates sys.base_prefix
+                hasattr(sys, "base_prefix")
+                and sys.base_prefix != sys.prefix
+            )
+            or (
+                # virtualenv creates sys.real_prefix
+                hasattr(sys, "real_prefix")
+            )
+            or (
+                # VIRTUAL_ENV environment variable
+                os.environ.get("VIRTUAL_ENV")
+                is not None
+            )
+        )
+
     def _check_pep668_managed(self) -> bool:
         """
         Check if Python environment is PEP 668 externally managed.
@@ -211,6 +242,11 @@ class RobustPackageInstaller:
         Returns:
             True if PEP 668 managed, False otherwise
         """
+        # If in virtualenv, PEP 668 doesn't apply
+        if self.in_virtualenv:
+            logger.debug("Running in virtualenv, PEP 668 restrictions don't apply")
+            return False
+
         # Check for EXTERNALLY-MANAGED marker file
         stdlib_path = sysconfig.get_path("stdlib")
         marker_file = Path(stdlib_path) / "EXTERNALLY-MANAGED"
@@ -240,7 +276,7 @@ class RobustPackageInstaller:
                 "Your Python installation is marked as externally managed (PEP 668).\n"
                 "This typically means you're using a system Python managed by Homebrew, apt, etc.\n"
                 "\n"
-                "Installing packages with --break-system-packages --user flags...\n"
+                "Installing packages with --break-system-packages flag...\n"
                 "\n"
                 "RECOMMENDED: Use a virtual environment instead:\n"
                 "  python -m venv .venv\n"
@@ -255,8 +291,10 @@ class RobustPackageInstaller:
         """
         Build the installation command for a given strategy.
 
-        WHY: PEP 668 support added to handle externally managed Python
-        environments by adding appropriate flags when needed.
+        WHY: Proper environment detection ensures we use the right pip flags:
+        - Virtualenv: No special flags needed (already isolated)
+        - PEP 668 system: Use --break-system-packages only
+        - Normal system: Use --user for user-local install
 
         Args:
             package_spec: Package specification
@@ -267,14 +305,19 @@ class RobustPackageInstaller:
         """
         base_cmd = [sys.executable, "-m", "pip", "install"]
 
-        # Add PEP 668 bypass flags if needed
-        if self.is_pep668_managed:
+        # Determine appropriate flags based on environment
+        if self.in_virtualenv:
+            # In virtualenv - no special flags needed
+            logger.debug("Installing in virtualenv (no special flags)")
+        elif self.is_pep668_managed:
+            # System Python with PEP 668 - use --break-system-packages only
             self._show_pep668_warning()
-            # Add flags to bypass PEP 668 restrictions
-            base_cmd.extend(["--break-system-packages", "--user"])
-            logger.debug(
-                "Added --break-system-packages --user flags for PEP 668 environment"
-            )
+            base_cmd.append("--break-system-packages")
+            logger.debug("Added --break-system-packages flag for PEP 668 environment")
+        else:
+            # Normal system Python - use --user for user-local install
+            base_cmd.append("--user")
+            logger.debug("Added --user flag for user-local installation")
 
         # Add cache control
         if not self.use_cache:
@@ -612,11 +655,16 @@ class RobustPackageInstaller:
         try:
             cmd = [sys.executable, "-m", "pip", "install"]
 
-            # Add PEP 668 bypass flags if needed
-            if self.is_pep668_managed:
+            # Add appropriate flags based on environment
+            if self.in_virtualenv:
+                logger.debug("Batch install in virtualenv (no special flags)")
+            elif self.is_pep668_managed:
                 self._show_pep668_warning()
-                cmd.extend(["--break-system-packages", "--user"])
-                logger.debug("Added PEP 668 flags for batch installation")
+                cmd.append("--break-system-packages")
+                logger.debug("Added --break-system-packages for batch installation")
+            else:
+                cmd.append("--user")
+                logger.debug("Added --user flag for batch installation")
 
             cmd.extend(packages)
 
@@ -654,12 +702,18 @@ class RobustPackageInstaller:
         lines.append("INSTALLATION REPORT")
         lines.append("=" * 60)
 
-        # Add PEP 668 status
-        if self.is_pep668_managed:
-            lines.append("")
+        # Add environment status
+        lines.append("")
+        if self.in_virtualenv:
+            lines.append("✓ Environment: Virtual Environment (isolated)")
+            lines.append("  No special pip flags needed")
+        elif self.is_pep668_managed:
             lines.append("⚠️  PEP 668 Managed Environment: YES")
-            lines.append("   Installations used --break-system-packages --user flags")
+            lines.append("   Installations used --break-system-packages flag")
             lines.append("   Consider using a virtual environment for better isolation")
+        else:
+            lines.append("Environment: System Python")
+            lines.append("   Installations used --user flag for user-local install")
 
         # Summary
         total_attempts = len(self.attempts)
@@ -672,7 +726,7 @@ class RobustPackageInstaller:
         lines.append("")
 
         # Details by package
-        packages = {}
+        packages: Dict[str, List[InstallAttempt]] = {}
         for attempt in self.attempts:
             if attempt.package not in packages:
                 packages[attempt.package] = []

{claude_mpm-4.7.4.dist-info → claude_mpm-4.18.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.7.4
+Version: 4.18.2
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -49,12 +49,12 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: pyee>=13.0.0
 Requires-Dist: importlib-resources>=5.0; python_version < "3.9"
 Requires-Dist: pathspec>=0.11.0
+Requires-Dist: kuzu-memory>=1.1.5
 Provides-Extra: mcp
 Requires-Dist: mcp>=0.1.0; extra == "mcp"
 Requires-Dist: mcp-vector-search>=0.1.0; extra == "mcp"
 Requires-Dist: mcp-browser>=0.1.0; extra == "mcp"
 Requires-Dist: mcp-ticketer>=0.1.0; extra == "mcp"
-Requires-Dist: kuzu-memory>=1.1.5; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
@@ -157,10 +157,13 @@ A powerful orchestration framework for **Claude Code (CLI)** that enables multi-
 ## Features
 
 - 🤖 **Multi-Agent System**: 15 specialized agents for comprehensive project management
+- 🎯 **Skills System**: 20 bundled skills with auto-linking, three-tier organization (bundled/user/project), and interactive configuration
 - 🧠 **Persistent Knowledge System**: Project-specific kuzu-memory integration for intelligent context retention
 - 🔄 **Session Management**: Resume previous sessions with `--resume`
+- 📋 **Resume Log System**: Proactive context management with automatic 10k-token session logs at 70%/85%/95% thresholds
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
-- 🔌 **Optional MCP Services**: mcp-vector-search and kuzu-memory with automatic fallback installation
+- 🔌 **Smart MCP Services**: Interactive auto-install for mcp-vector-search on first use (pip/pipx choice)
+- 🔍 **Semantic Code Search**: Optional vector search with graceful fallback to grep/glob
 - 📁 **Multi-Project Support**: Per-session working directories with persistent knowledge graphs
 - 🔍 **Git Integration**: View diffs and track changes across projects
 - 🎯 **Smart Task Orchestration**: PM agent intelligently routes work to specialists
@@ -193,10 +196,12 @@ claude-mpm mcp-pipx-config
 ```
 
 **💡 Optional Dependencies**:
-- `[mcp]` - Include MCP services (mcp-vector-search, mcp-browser, mcp-ticketer, kuzu-memory)
+- `[mcp]` - Include MCP services (mcp-vector-search, mcp-browser, mcp-ticketer)
 - `[monitor]` - Full monitoring dashboard with Socket.IO and async web server components
 - **Combine both**: Use `"claude-mpm[mcp,monitor]"` to install all features
-- Without optional dependencies, MCP services auto-install on first use via pipx
+- **Note**: kuzu-memory is now a required dependency, always included with Claude MPM
+- **Auto-Install**: mcp-vector-search offers interactive installation on first use (pip/pipx choice)
+- Without pre-installed MCP dependencies, services install on-demand with user confirmation
 
 **🎉 Pipx Support Now Fully Functional!** Recent improvements ensure complete compatibility:
 - ✅ Socket.IO daemon script path resolution (fixed)
@@ -215,6 +220,11 @@ claude-mpm
 # Start with monitoring dashboard
 claude-mpm run --monitor
 
+# Use semantic code search (auto-installs mcp-vector-search on first use)
+claude-mpm search "authentication logic"
+# or inside Claude Code session:
+/mpm-search "authentication logic"
+
 # Use MCP Gateway for external tool integration
 claude-mpm mcp
 
@@ -297,6 +307,41 @@ Claude MPM includes 15 specialized agents:
 ### Agent Memory System
 Agents learn project-specific patterns using a simple list format and can update memories via JSON response fields (`remember` for incremental updates, `MEMORIES` for complete replacement). Initialize with `claude-mpm memory init`.
 
+### Skills System
+
+Claude MPM includes a powerful skills system that eliminates redundant agent guidance through reusable skill modules:
+
+**20 Bundled Skills** covering essential development workflows (all versioned starting at 0.1.0):
+- Git workflow, TDD, code review, systematic debugging
+- API documentation, refactoring patterns, performance profiling
+- Docker containerization, database migrations, security scanning
+- JSON/PDF/XLSX handling, async testing, ImageMagick operations
+- Local development servers: Next.js, FastAPI, Vite, Express
+- Web performance: Lighthouse metrics, Core Web Vitals optimization
+
+**Three-Tier Organization:**
+- **Bundled**: Core skills included with Claude MPM (~15,000 lines of reusable guidance)
+- **User**: Custom skills in `~/.config/claude-mpm/skills/`
+- **Project**: Project-specific skills in `.claude-mpm/skills/`
+
+**Version Tracking:**
+- All skills support semantic versioning (MAJOR.MINOR.PATCH)
+- Check versions with `/mpm-version` command in Claude Code
+- See [Skills Versioning Guide](docs/user/skills-versioning.md) for details
+
+**Quick Access:**
+```bash
+# Interactive skills management
+claude-mpm configure
+# Choose option 2: Skills Management
+
+# Auto-link skills to agents based on their roles
+# Configure custom skill assignments
+# View current skill mappings
+```
+
+Skills are automatically injected into agent prompts, reducing template size by 85% while maintaining full capability coverage.
+
 ### MCP Gateway (Model Context Protocol)
 
 Claude MPM includes a powerful MCP Gateway that enables:
@@ -319,6 +364,72 @@ claude-mpm cleanup-memory
 claude-mpm cleanup-memory --days 7
 ```
 
+### Resume Log System
+
+**NEW in v4.17.2** - Proactive context management for seamless session continuity.
+
+The Resume Log System automatically generates structured 10k-token logs when approaching Claude's context window limits, enabling you to resume work without losing important context.
+
+**Key Features**:
+- 🎯 **Graduated Thresholds**: Warnings at 70% (60k buffer), 85% (30k buffer), and 95% (10k buffer)
+- 📋 **Structured Logs**: 10k-token budget intelligently distributed across 7 key sections
+- 🔄 **Seamless Resumption**: Automatically loads previous session context on startup
+- 📁 **Human-Readable**: Markdown format for both Claude and human review
+- ⚙️ **Zero-Configuration**: Works automatically with sensible defaults
+
+**How It Works**:
+1. Monitor token usage continuously throughout session
+2. Display proactive warnings at 70%, 85%, and 95% thresholds
+3. Automatically generate resume log when approaching limits
+4. Load previous resume log when starting new session
+5. Continue work seamlessly with full context preservation
+
+**Example Resume Log Structure**:
+```markdown
+# Session Resume Log: 20251101_115000
+
+## Context Metrics (500 tokens)
+- Token usage and percentage
+
+## Mission Summary (1,000 tokens)
+- Overall goal and purpose
+
+## Accomplishments (2,000 tokens)
+- What was completed
+
+## Key Findings (2,500 tokens)
+- Important discoveries
+
+## Decisions & Rationale (1,500 tokens)
+- Why choices were made
+
+## Next Steps (1,500 tokens)
+- What to do next
+
+## Critical Context (1,000 tokens)
+- Essential state, IDs, paths
+```
+
+**Configuration** (`.claude-mpm/configuration.yaml`):
+```yaml
+context_management:
+  enabled: true
+  budget_total: 200000
+  thresholds:
+    caution: 0.70   # First warning - plan transition
+    warning: 0.85   # Strong warning - wrap up
+    critical: 0.95  # Urgent - stop new work
+  resume_logs:
+    enabled: true
+    auto_generate: true
+    max_tokens: 10000
+    storage_dir: ".claude-mpm/resume-logs"
+```
+
+**QA Status**: 40/41 tests passing (97.6% coverage), APPROVED FOR PRODUCTION ✅
+
+See [docs/user/resume-logs.md](docs/user/resume-logs.md) for complete documentation.
+
 ### Real-Time Monitoring
 The `--monitor` flag opens a web dashboard showing live agent activity, file operations, and session management.
 
@@ -357,19 +468,25 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 - **Single Entry Point**: [docs/README.md](docs/README.md) is your navigation hub
 - **Clear User Paths**: Organized by user type and experience level
 - **Cross-Referenced**: Links between related topics and sections
-- **Up-to-Date**: Version 4.3.3 with current information
+- **Up-to-Date**: Version 4.16.3 with web performance optimization skill
+
+## Recent Updates (v4.16.3)
+
+**Web Performance Optimization**: New `web-performance-optimization` skill for Lighthouse metrics, Core Web Vitals (LCP, INP, CLS), and framework-specific optimization patterns.
+
+## Previous Updates (v4.16.1)
 
-## Recent Updates (v4.3.3)
+**Local Development Skills**: Added 4 new toolchain-specific skills: `nextjs-local-dev`, `fastapi-local-dev`, `vite-local-dev`, and `express-local-dev` for professional local server management with PM2, HMR, and production-grade patterns.
 
-**Enhanced PM Instructions**: PM2 deployment support and mandatory web-qa verification for quality assurance.
+**Skills System Integration**: 20 bundled skills with auto-linking, three-tier organization, and interactive configuration. Eliminates 85% of redundant guidance across agent templates (~15,000 lines of reusable content).
 
-**Improved Version Management**: Better version comparison logic and agent override warnings for smoother operations.
+**Enhanced Documentation**: Complete documentation suite with PDF guides, reorganized structure, and comprehensive design documents for skills integration.
 
-**Code Quality Improvements**: Auto-fix code formatting and import management with enhanced standard tools recognition.
+**Agent Template Improvements**: Cleaned agent templates with skills integration, removing redundant guidance while maintaining full capability coverage.
 
-**Documentation Overhaul**: Unified documentation architecture with single entry point and clear navigation paths.
+**Interactive Skills Management**: New skills wizard accessible via `claude-mpm configure` for viewing, configuring, and auto-linking skills to agents.
 
-**Performance Enhancements**: Continued 50-80% performance improvements through intelligent caching and lazy loading.
+**Bug Fixes**: Resolved agent template inconsistencies and improved configuration management.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/user/MIGRATION.md](docs/user/MIGRATION.md) for upgrade instructions.