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

claude_mpm/models/resume_log.py

@@ -0,0 +1,340 @@
+"""Resume Log Data Model.
+
+This module defines the data structure for session resume logs that enable
+seamless context restoration when Claude hits token limits.
+
+Design Philosophy:
+- Target 10k tokens maximum per resume log
+- Human-readable markdown format
+- Structured sections with token budgets
+- Optimized for Claude consumption on session resume
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class ContextMetrics:
+    """Context window usage metrics."""
+
+    total_budget: int = 200000
+    used_tokens: int = 0
+    remaining_tokens: int = 0
+    percentage_used: float = 0.0
+    stop_reason: Optional[str] = None
+    model: str = "claude-sonnet-4.5"
+    session_id: str = ""
+    timestamp: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "total_budget": self.total_budget,
+            "used_tokens": self.used_tokens,
+            "remaining_tokens": self.remaining_tokens,
+            "percentage_used": self.percentage_used,
+            "stop_reason": self.stop_reason,
+            "model": self.model,
+            "session_id": self.session_id,
+            "timestamp": self.timestamp,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ContextMetrics":
+        """Create from dictionary."""
+        return cls(
+            total_budget=data.get("total_budget", 200000),
+            used_tokens=data.get("used_tokens", 0),
+            remaining_tokens=data.get("remaining_tokens", 0),
+            percentage_used=data.get("percentage_used", 0.0),
+            stop_reason=data.get("stop_reason"),
+            model=data.get("model", "claude-sonnet-4.5"),
+            session_id=data.get("session_id", ""),
+            timestamp=data.get("timestamp", datetime.now(timezone.utc).isoformat()),
+        )
+
+
+@dataclass
+class ResumeLog:
+    """Resume log containing all information needed to restore session context.
+
+    Token Budget Distribution (10k tokens total):
+    - Context Metrics: 500 tokens
+    - Mission Summary: 1,000 tokens
+    - Accomplishments: 2,000 tokens
+    - Key Findings: 2,500 tokens
+    - Decisions & Rationale: 1,500 tokens
+    - Next Steps: 1,500 tokens
+    - Critical Context: 1,000 tokens
+    """
+
+    # Session identification
+    session_id: str
+    previous_session_id: Optional[str] = None
+    created_at: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+
+    # Context metrics
+    context_metrics: ContextMetrics = field(default_factory=ContextMetrics)
+
+    # Core content sections (with token budgets)
+    mission_summary: str = ""  # 1,000 tokens - What was the overall goal?
+    accomplishments: List[str] = field(
+        default_factory=list
+    )  # 2,000 tokens - What was completed?
+    key_findings: List[str] = field(
+        default_factory=list
+    )  # 2,500 tokens - What was discovered?
+    decisions_made: List[Dict[str, str]] = field(
+        default_factory=list
+    )  # 1,500 tokens - What choices were made and why?
+    next_steps: List[str] = field(
+        default_factory=list
+    )  # 1,500 tokens - What needs to happen next?
+    critical_context: Dict[str, Any] = field(
+        default_factory=dict
+    )  # 1,000 tokens - Essential state/data
+
+    # Metadata
+    files_modified: List[str] = field(default_factory=list)
+    agents_used: Dict[str, int] = field(default_factory=dict)
+    errors_encountered: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+    def to_markdown(self) -> str:
+        """Generate markdown format for Claude consumption.
+
+        Returns:
+            Markdown-formatted resume log
+        """
+        sections = []
+
+        # Header
+        sections.append(f"# Session Resume Log: {self.session_id}\n")
+        sections.append(f"**Created**: {self.created_at}")
+        if self.previous_session_id:
+            sections.append(f"**Previous Session**: {self.previous_session_id}")
+        sections.append("")
+
+        # Context Metrics (500 tokens)
+        sections.append("## Context Metrics\n")
+        sections.append(f"- **Model**: {self.context_metrics.model}")
+        sections.append(
+            f"- **Tokens Used**: {self.context_metrics.used_tokens:,} / {self.context_metrics.total_budget:,}"
+        )
+        sections.append(
+            f"- **Percentage**: {self.context_metrics.percentage_used:.1f}%"
+        )
+        sections.append(
+            f"- **Remaining**: {self.context_metrics.remaining_tokens:,} tokens"
+        )
+        if self.context_metrics.stop_reason:
+            sections.append(f"- **Stop Reason**: {self.context_metrics.stop_reason}")
+        sections.append("")
+
+        # Mission Summary (1,000 tokens)
+        sections.append("## Mission Summary\n")
+        sections.append(
+            self.mission_summary
+            if self.mission_summary
+            else "_No mission summary provided_"
+        )
+        sections.append("")
+
+        # Accomplishments (2,000 tokens)
+        sections.append("## Accomplishments\n")
+        if self.accomplishments:
+            for i, item in enumerate(self.accomplishments, 1):
+                sections.append(f"{i}. {item}")
+        else:
+            sections.append("_No accomplishments recorded_")
+        sections.append("")
+
+        # Key Findings (2,500 tokens)
+        sections.append("## Key Findings\n")
+        if self.key_findings:
+            for i, finding in enumerate(self.key_findings, 1):
+                sections.append(f"{i}. {finding}")
+        else:
+            sections.append("_No key findings recorded_")
+        sections.append("")
+
+        # Decisions & Rationale (1,500 tokens)
+        sections.append("## Decisions & Rationale\n")
+        if self.decisions_made:
+            for i, decision in enumerate(self.decisions_made, 1):
+                decision_text = decision.get("decision", "")
+                rationale = decision.get("rationale", "")
+                sections.append(f"{i}. **Decision**: {decision_text}")
+                if rationale:
+                    sections.append(f"   **Rationale**: {rationale}")
+        else:
+            sections.append("_No decisions recorded_")
+        sections.append("")
+
+        # Next Steps (1,500 tokens)
+        sections.append("## Next Steps\n")
+        if self.next_steps:
+            for i, step in enumerate(self.next_steps, 1):
+                sections.append(f"{i}. {step}")
+        else:
+            sections.append("_No next steps defined_")
+        sections.append("")
+
+        # Critical Context (1,000 tokens)
+        sections.append("## Critical Context\n")
+        if self.critical_context:
+            for key, value in self.critical_context.items():
+                sections.append(f"- **{key}**: {value}")
+        else:
+            sections.append("_No critical context preserved_")
+        sections.append("")
+
+        # Metadata
+        sections.append("## Session Metadata\n")
+        if self.files_modified:
+            sections.append(f"**Files Modified** ({len(self.files_modified)}):")
+            for file in self.files_modified[:20]:  # Limit to first 20
+                sections.append(f"- {file}")
+            if len(self.files_modified) > 20:
+                sections.append(f"- ... and {len(self.files_modified) - 20} more")
+            sections.append("")
+
+        if self.agents_used:
+            sections.append("**Agents Used**:")
+            for agent, count in self.agents_used.items():
+                sections.append(f"- {agent}: {count} delegations")
+            sections.append("")
+
+        if self.errors_encountered:
+            sections.append(f"**Errors** ({len(self.errors_encountered)}):")
+            for error in self.errors_encountered[:5]:  # Limit to first 5
+                sections.append(f"- {error}")
+            sections.append("")
+
+        if self.warnings:
+            sections.append(f"**Warnings** ({len(self.warnings)}):")
+            for warning in self.warnings[:5]:  # Limit to first 5
+                sections.append(f"- {warning}")
+            sections.append("")
+
+        return "\n".join(sections)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "session_id": self.session_id,
+            "previous_session_id": self.previous_session_id,
+            "created_at": self.created_at,
+            "context_metrics": self.context_metrics.to_dict(),
+            "mission_summary": self.mission_summary,
+            "accomplishments": self.accomplishments,
+            "key_findings": self.key_findings,
+            "decisions_made": self.decisions_made,
+            "next_steps": self.next_steps,
+            "critical_context": self.critical_context,
+            "files_modified": self.files_modified,
+            "agents_used": self.agents_used,
+            "errors_encountered": self.errors_encountered,
+            "warnings": self.warnings,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ResumeLog":
+        """Create from dictionary."""
+        context_metrics_data = data.get("context_metrics", {})
+        context_metrics = ContextMetrics.from_dict(context_metrics_data)
+
+        return cls(
+            session_id=data.get("session_id", ""),
+            previous_session_id=data.get("previous_session_id"),
+            created_at=data.get("created_at", datetime.now(timezone.utc).isoformat()),
+            context_metrics=context_metrics,
+            mission_summary=data.get("mission_summary", ""),
+            accomplishments=data.get("accomplishments", []),
+            key_findings=data.get("key_findings", []),
+            decisions_made=data.get("decisions_made", []),
+            next_steps=data.get("next_steps", []),
+            critical_context=data.get("critical_context", {}),
+            files_modified=data.get("files_modified", []),
+            agents_used=data.get("agents_used", {}),
+            errors_encountered=data.get("errors_encountered", []),
+            warnings=data.get("warnings", []),
+        )
+
+    def save(self, storage_dir: Optional[Path] = None) -> Path:
+        """Save resume log to markdown file.
+
+        Args:
+            storage_dir: Directory to save the log (default: .claude-mpm/resume-logs)
+
+        Returns:
+            Path to saved file
+        """
+        if storage_dir is None:
+            storage_dir = Path.home() / ".claude-mpm" / "resume-logs"
+
+        storage_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate filename
+        file_path = storage_dir / f"session-{self.session_id}.md"
+
+        try:
+            # Write markdown file
+            markdown_content = self.to_markdown()
+            file_path.write_text(markdown_content, encoding="utf-8")
+
+            logger.info(f"Resume log saved: {file_path}")
+            return file_path
+
+        except Exception as e:
+            logger.error(f"Failed to save resume log: {e}")
+            raise
+
+    @classmethod
+    def load(
+        cls, session_id: str, storage_dir: Optional[Path] = None
+    ) -> Optional["ResumeLog"]:
+        """Load resume log from file.
+
+        Args:
+            session_id: Session ID to load
+            storage_dir: Directory to load from (default: .claude-mpm/resume-logs)
+
+        Returns:
+            ResumeLog instance or None if not found
+        """
+        if storage_dir is None:
+            storage_dir = Path.home() / ".claude-mpm" / "resume-logs"
+
+        file_path = storage_dir / f"session-{session_id}.md"
+
+        if not file_path.exists():
+            logger.debug(f"Resume log not found: {file_path}")
+            return None
+
+        try:
+            # For now, we just return the markdown content
+            # In the future, could parse markdown back to structured data
+            _ = file_path.read_text(encoding="utf-8")
+            logger.info(f"Resume log loaded: {file_path}")
+
+            # Return a basic ResumeLog with the markdown content embedded
+            return cls(
+                session_id=session_id,
+                mission_summary=f"Loaded from previous session. See full context in {file_path}",
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to load resume log: {e}")
+            return None

claude_mpm/services/agents/auto_config_manager.py

@@ -23,15 +23,14 @@ from typing import Any, Dict, List, Optional
 import yaml
 
 from ...core.base_service import BaseService
+from ...core.enums import OperationResult, ValidationSeverity
 from ..core.interfaces.agent import IAgentRegistry, IAutoConfigManager
 from ..core.models.agent_config import (
     AgentRecommendation,
     ConfigurationPreview,
     ConfigurationResult,
-    ConfigurationStatus,
     ValidationIssue,
     ValidationResult,
-    ValidationSeverity,
 )
 from ..core.models.toolchain import ToolchainAnalysis
 from .observers import IDeploymentObserver, NullObserver
@@ -216,7 +215,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
 
             if not recommendations:
                 return ConfigurationResult(
-                    status=ConfigurationStatus.SUCCESS,
+                    status=OperationResult.SUCCESS,
                     message="No agents recommended for this project configuration",
                     recommendations=recommendations,
                     metadata={
@@ -241,7 +240,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
                     f"Validation failed with {validation_result.error_count} errors"
                 )
                 return ConfigurationResult(
-                    status=ConfigurationStatus.VALIDATION_ERROR,
+                    status=OperationResult.ERROR,
                     validation_errors=[
                         issue.message for issue in validation_result.errors
                     ],
@@ -260,7 +259,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
             if dry_run:
                 self.logger.info("Dry-run mode: skipping deployment")
                 return ConfigurationResult(
-                    status=ConfigurationStatus.SUCCESS,
+                    status=OperationResult.SUCCESS,
                     validation_warnings=[
                         issue.message for issue in validation_result.warnings
                     ],
@@ -280,7 +279,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
                 if not confirmed:
                     self.logger.info("User cancelled auto-configuration")
                     return ConfigurationResult(
-                        status=ConfigurationStatus.USER_CANCELLED,
+                        status=OperationResult.CANCELLED,
                         recommendations=recommendations,
                         message="Auto-configuration cancelled by user",
                         metadata={
@@ -318,9 +317,9 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
 
                 return ConfigurationResult(
                     status=(
-                        ConfigurationStatus.PARTIAL_SUCCESS
+                        OperationResult.WARNING
                         if deployed_agents
-                        else ConfigurationStatus.FAILURE
+                        else OperationResult.FAILED
                     ),
                     deployed_agents=deployed_agents,
                     failed_agents=failed_agents,
@@ -347,7 +346,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
             )
 
             return ConfigurationResult(
-                status=ConfigurationStatus.SUCCESS,
+                status=OperationResult.SUCCESS,
                 deployed_agents=deployed_agents,
                 validation_warnings=[
                     issue.message for issue in validation_result.warnings
@@ -365,7 +364,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
             observer.on_error("auto-configuration", str(e), e)
 
             return ConfigurationResult(
-                status=ConfigurationStatus.FAILURE,
+                status=OperationResult.FAILED,
                 message=f"Auto-configuration failed: {e}",
                 metadata={
                     "duration_ms": (time.time() - start_time) * 1000,
@@ -679,7 +678,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
                     agent_id, agent_name, success=True
                 )
                 deployed.append(agent_id)
-                self.logger.info(f"Successfully deployed agent: {agent_id}")
+                self.logger.debug(f"Successfully deployed agent: {agent_id}")
 
             except Exception as e:
                 self.logger.error(

claude_mpm/services/agents/deployment/agent_configuration_manager.py

@@ -71,7 +71,7 @@ class AgentConfigurationManager:
             # Cache the result
             self._base_agent_cache = (base_agent_data, base_agent_version)
 
-            self.logger.info(f"Loaded base agent from {self.base_agent_path}")
+            self.logger.debug(f"Loaded base agent from {self.base_agent_path}")
             return self._base_agent_cache
 
         except Exception as e:

claude_mpm/services/agents/deployment/agent_record_service.py

@@ -107,7 +107,7 @@ class AgentRecordService(BaseService):
                     record = self._deserialize_record(record_data)
                     records[agent_name] = record
 
-                self.logger.info(f"Loaded {len(records)} agent records")
+                self.logger.debug(f"Loaded {len(records)} agent records")
             else:
                 self.logger.debug("No existing records file found")
 

claude_mpm/services/agents/deployment/agent_validator.py

@@ -329,10 +329,26 @@ class AgentValidator:
             "type": "agent",  # Default type
         }
 
-        # Extract from YAML frontmatter
+        # Extract ONLY from YAML frontmatter (between --- markers)
         lines = content.split("\n")
+        in_frontmatter = False
+        frontmatter_ended = False
+
         for line in lines:
             stripped_line = line.strip()
+
+            # Track frontmatter boundaries
+            if stripped_line == "---":
+                if not in_frontmatter:
+                    in_frontmatter = True
+                    continue
+                frontmatter_ended = True
+                break  # Stop parsing after frontmatter ends
+
+            # Only parse within frontmatter
+            if not in_frontmatter or frontmatter_ended:
+                continue
+
             if stripped_line.startswith("name:"):
                 agent_info["name"] = stripped_line.split(":", 1)[1].strip().strip("\"'")
             elif stripped_line.startswith("description:"):

claude_mpm/services/agents/deployment/async_agent_deployment.py

@@ -224,7 +224,7 @@ class AsyncAgentDeploymentService:
 
         elapsed = (time.time() - start_time) * 1000
         self._metrics["time_saved_ms"] += max(0, (len(directories) * 75) - elapsed)
-        self.logger.info(f"Discovered agents in {elapsed:.1f}ms (parallel scan)")
+        self.logger.debug(f"Discovered agents in {elapsed:.1f}ms (parallel scan)")
 
         return discovered
 

claude_mpm/services/agents/deployment/interface_adapter.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 from typing import Any, Dict, List, Tuple
 
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.core.interfaces import AgentDeploymentInterface
 from claude_mpm.core.logger import get_logger
 
@@ -195,7 +196,7 @@ class AgentDeploymentInterfaceAdapter(AgentDeploymentInterface):
             # Ensure the result is a dictionary
             if not isinstance(status, dict):
                 return {
-                    "status": "unknown",
+                    "status": OperationResult.UNKNOWN,
                     "error": "Invalid status format from deployment service",
                     "interface_version": "1.0.0",
                     "adapter_used": True,
@@ -210,7 +211,7 @@ class AgentDeploymentInterfaceAdapter(AgentDeploymentInterface):
         except Exception as e:
             self.logger.error(f"Failed to get deployment status: {e}", exc_info=True)
             return {
-                "status": "error",
+                "status": OperationResult.ERROR,
                 "error": str(e),
                 "interface_version": "1.0.0",
                 "adapter_used": True,

claude_mpm/services/agents/deployment/local_template_deployment.py

@@ -90,7 +90,7 @@ class LocalTemplateDeploymentService:
                 logger.error(f"Failed to deploy local template {agent_id}: {e}")
                 results["errors"].append(f"{agent_id}: {e}")
 
-        logger.info(
+        logger.debug(
             f"Local template deployment: deployed={len(results['deployed'])}, "
             f"updated={len(results['updated'])}, skipped={len(results['skipped'])}, "
             f"errors={len(results['errors'])}"

claude_mpm/services/agents/deployment/pipeline/steps/agent_processing_step.py

@@ -3,13 +3,14 @@
 import time
 from pathlib import Path
 
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.services.agents.deployment.processors import (
     AgentDeploymentContext,
     AgentDeploymentResult,
     AgentProcessor,
 )
 
-from .base_step import BaseDeploymentStep, StepResult, StepStatus
+from .base_step import BaseDeploymentStep, StepResult
 
 
 class AgentProcessingStep(BaseDeploymentStep):
@@ -37,7 +38,7 @@ class AgentProcessingStep(BaseDeploymentStep):
             if not context.template_files:
                 self.logger.warning("No template files to process")
                 return StepResult(
-                    status=StepStatus.SKIPPED,
+                    status=OperationResult.SKIPPED,
                     message="No template files found to process",
                     execution_time=time.time() - start_time,
                 )
@@ -103,13 +104,13 @@ class AgentProcessingStep(BaseDeploymentStep):
 
             # Determine step status
             if failed_count == 0:
-                status = StepStatus.SUCCESS
+                status = OperationResult.SUCCESS
                 message = f"Successfully processed {processed_count} agents in {execution_time:.3f}s"
             elif processed_count > 0:
-                status = StepStatus.WARNING
+                status = OperationResult.WARNING
                 message = f"Processed {processed_count} agents with {failed_count} failures in {execution_time:.3f}s"
             else:
-                status = StepStatus.FAILURE
+                status = OperationResult.FAILED
                 message = f"Failed to process any agents ({failed_count} failures) in {execution_time:.3f}s"
 
             self.logger.info(message)
@@ -127,7 +128,7 @@ class AgentProcessingStep(BaseDeploymentStep):
             context.add_error(error_msg)
 
             return StepResult(
-                status=StepStatus.FAILURE,
+                status=OperationResult.FAILED,
                 message=error_msg,
                 error=e,
                 execution_time=execution_time,

claude_mpm/services/agents/deployment/pipeline/steps/base_step.py

@@ -2,26 +2,17 @@
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from enum import Enum
 from typing import Optional
 
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.core.logger import get_logger
 
 
-class StepStatus(Enum):
-    """Status of a pipeline step execution."""
-
-    SUCCESS = "success"
-    FAILURE = "failure"
-    SKIPPED = "skipped"
-    WARNING = "warning"
-
-
 @dataclass
 class StepResult:
     """Result of executing a pipeline step."""
 
-    status: StepStatus
+    status: OperationResult
     message: Optional[str] = None
     error: Optional[Exception] = None
     execution_time: Optional[float] = None
@@ -29,22 +20,22 @@ class StepResult:
     @property
     def is_success(self) -> bool:
         """Check if the step was successful."""
-        return self.status == StepStatus.SUCCESS
+        return self.status == OperationResult.SUCCESS
 
     @property
     def is_failure(self) -> bool:
         """Check if the step failed."""
-        return self.status == StepStatus.FAILURE
+        return self.status == OperationResult.FAILED
 
     @property
     def is_skipped(self) -> bool:
         """Check if the step was skipped."""
-        return self.status == StepStatus.SKIPPED
+        return self.status == OperationResult.SKIPPED
 
     @property
     def is_warning(self) -> bool:
         """Check if the step completed with warnings."""
-        return self.status == StepStatus.WARNING
+        return self.status == OperationResult.WARNING
 
 
 class BaseDeploymentStep(ABC):
@@ -67,7 +58,7 @@ class BaseDeploymentStep(ABC):
         self.logger = get_logger(f"{__name__}.{self.__class__.__name__}")
 
     @abstractmethod
-    def execute(self, context) -> StepResult:
+    def execute(self, context) -> "StepResult":
         """Execute this deployment step.
 
         Args:

claude_mpm/services/agents/deployment/pipeline/steps/configuration_step.py

@@ -3,8 +3,9 @@
 import time
 
 from claude_mpm.core.config import Config
+from claude_mpm.core.enums import OperationResult
 
-from .base_step import BaseDeploymentStep, StepResult, StepStatus
+from .base_step import BaseDeploymentStep, StepResult
 
 
 class ConfigurationLoadStep(BaseDeploymentStep):
@@ -54,7 +55,7 @@ class ConfigurationLoadStep(BaseDeploymentStep):
             context.step_timings[self.name] = execution_time
 
             return StepResult(
-                status=StepStatus.SUCCESS,
+                status=OperationResult.SUCCESS,
                 message=f"Configuration loaded successfully in {execution_time:.3f}s",
                 execution_time=execution_time,
             )
@@ -68,7 +69,7 @@ class ConfigurationLoadStep(BaseDeploymentStep):
             context.add_error(error_msg)
 
             return StepResult(
-                status=StepStatus.FAILURE,
+                status=OperationResult.FAILED,
                 message=error_msg,
                 error=e,
                 execution_time=execution_time,