emdash-core 0.1.7__py3-none-any.whl

emdash_core/agent/tools/modes.py

@@ -0,0 +1,153 @@
+"""Agent mode management tools.
+
+Provides tools for switching between different agent modes
+(exploration, planning, coding, etc).
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+from .base import BaseTool, ToolResult, ToolCategory
+
+
+class AgentMode(Enum):
+    """Available agent modes."""
+
+    EXPLORATION = "exploration"
+    PLANNING = "planning"
+    CODING = "coding"
+    REVIEW = "review"
+    DEBUG = "debug"
+
+
+@dataclass
+class ModeState:
+    """Singleton state for agent mode."""
+
+    current_mode: AgentMode = AgentMode.EXPLORATION
+    mode_context: dict = None
+
+    _instance: Optional["ModeState"] = None
+
+    def __post_init__(self):
+        if self.mode_context is None:
+            self.mode_context = {}
+
+    @classmethod
+    def get_instance(cls) -> "ModeState":
+        """Get the singleton instance."""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance."""
+        cls._instance = None
+
+
+class SwitchModeTool(BaseTool):
+    """Tool for switching between agent modes."""
+
+    name = "switch_mode"
+    description = """Switch the agent to a different operating mode.
+
+Modes:
+- exploration: General codebase exploration and understanding
+- planning: Feature planning and specification writing
+- coding: Active code editing and implementation
+- review: Code review and feedback
+- debug: Debugging and issue investigation"""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(
+        self,
+        mode: str,
+        context: Optional[str] = None,
+    ) -> ToolResult:
+        """Switch to a new mode.
+
+        Args:
+            mode: Target mode name
+            context: Optional context for the new mode
+
+        Returns:
+            ToolResult indicating success
+        """
+        try:
+            new_mode = AgentMode(mode.lower())
+        except ValueError:
+            valid_modes = [m.value for m in AgentMode]
+            return ToolResult.error_result(
+                f"Invalid mode: {mode}",
+                suggestions=[f"Valid modes: {', '.join(valid_modes)}"],
+            )
+
+        state = ModeState.get_instance()
+        old_mode = state.current_mode
+        state.current_mode = new_mode
+
+        if context:
+            state.mode_context[new_mode.value] = context
+
+        return ToolResult.success_result(
+            data={
+                "previous_mode": old_mode.value,
+                "current_mode": new_mode.value,
+                "context": context,
+            },
+        )
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(
+            properties={
+                "mode": {
+                    "type": "string",
+                    "enum": [m.value for m in AgentMode],
+                    "description": "Target mode to switch to",
+                },
+                "context": {
+                    "type": "string",
+                    "description": "Optional context for the new mode",
+                },
+            },
+            required=["mode"],
+        )
+
+
+class GetModeTool(BaseTool):
+    """Tool for getting current agent mode."""
+
+    name = "get_mode"
+    description = "Get the current agent operating mode and its context."
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(self) -> ToolResult:
+        """Get current mode.
+
+        Returns:
+            ToolResult with current mode info
+        """
+        state = ModeState.get_instance()
+
+        return ToolResult.success_result(
+            data={
+                "current_mode": state.current_mode.value,
+                "context": state.mode_context.get(state.current_mode.value),
+                "available_modes": [m.value for m in AgentMode],
+            },
+        )
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(properties={}, required=[])

emdash_core/agent/tools/plan.py

@@ -0,0 +1,206 @@
+"""Planning tool for exploration strategy."""
+
+from typing import Optional
+
+from .base import BaseTool, ToolResult, ToolCategory
+from ...utils.logger import log
+
+
+# Exploration strategies
+STRATEGIES = {
+    "understand_feature": {
+        "description": "Understand how a feature works",
+        "steps": [
+            {"tool": "semantic_search", "purpose": "Find entry points"},
+            {"tool": "expand_node", "purpose": "Understand main components"},
+            {"tool": "get_callers", "purpose": "See usage patterns"},
+            {"tool": "get_file_dependencies", "purpose": "Map module structure"},
+        ],
+    },
+    "debug_issue": {
+        "description": "Debug a bug or issue",
+        "steps": [
+            {"tool": "grep", "purpose": "Find error messages or symptoms"},
+            {"tool": "semantic_search", "purpose": "Find related code"},
+            {"tool": "get_callees", "purpose": "Trace execution path"},
+            {"tool": "expand_node", "purpose": "Examine suspicious code"},
+        ],
+    },
+    "assess_change_impact": {
+        "description": "Assess impact of a proposed change",
+        "steps": [
+            {"tool": "get_callers", "purpose": "Find all usages"},
+            {"tool": "get_impact_analysis", "purpose": "Assess blast radius"},
+            {"tool": "get_file_dependencies", "purpose": "Find affected modules"},
+            {"tool": "get_class_hierarchy", "purpose": "Check inheritance impact"},
+        ],
+    },
+    "onboard_codebase": {
+        "description": "Get oriented in a new codebase",
+        "steps": [
+            {"tool": "get_communities", "purpose": "Understand major areas"},
+            {"tool": "get_top_pagerank", "purpose": "Find key components"},
+            {"tool": "get_area_importance", "purpose": "Map directory structure"},
+            {"tool": "semantic_search", "purpose": "Explore specific topics"},
+        ],
+    },
+    "find_similar_code": {
+        "description": "Find code similar to a reference",
+        "steps": [
+            {"tool": "expand_node", "purpose": "Understand the reference"},
+            {"tool": "semantic_search", "purpose": "Find similar patterns"},
+            {"tool": "get_neighbors", "purpose": "Explore related code"},
+        ],
+    },
+}
+
+
+class PlanExplorationTool(BaseTool):
+    """Create an exploration plan for a goal."""
+
+    name = "plan_exploration"
+    description = """Create a structured exploration plan for understanding code.
+
+Available strategies:
+- understand_feature: Learn how a feature works
+- debug_issue: Track down a bug
+- assess_change_impact: Evaluate change risk
+- onboard_codebase: Get oriented in new code
+- find_similar_code: Find similar patterns
+
+Or provide a custom goal and get a tailored plan."""
+    category = ToolCategory.PLANNING
+
+    def execute(
+        self,
+        goal: str,
+        strategy: Optional[str] = None,
+        context: Optional[str] = None,
+        constraints: Optional[list[str]] = None,
+        use_case: Optional[str] = None,
+    ) -> ToolResult:
+        """Create an exploration plan.
+
+        Args:
+            goal: What you want to understand or accomplish
+            strategy: Optional predefined strategy to use
+            context: Additional context about the goal
+            constraints: Constraints to consider
+            use_case: Optional use case hint (e.g., "spec", "debug", "review")
+
+        Returns:
+            ToolResult with exploration plan
+        """
+        # Map use_case to strategy if strategy not provided
+        if use_case and not strategy:
+            use_case_mapping = {
+                "spec": "understand_feature",
+                "debug": "debug_issue",
+                "review": "assess_change_impact",
+                "onboard": "onboard_codebase",
+            }
+            strategy = use_case_mapping.get(use_case)
+        try:
+            # Use predefined strategy if specified
+            if strategy and strategy in STRATEGIES:
+                strat = STRATEGIES[strategy]
+                return ToolResult.success_result(
+                    data={
+                        "goal": goal,
+                        "strategy": strategy,
+                        "description": strat["description"],
+                        "steps": strat["steps"],
+                        "context": context,
+                        "constraints": constraints,
+                    },
+                )
+
+            # Infer strategy from goal
+            inferred = self._infer_strategy(goal)
+
+            if inferred and inferred in STRATEGIES:
+                strat = STRATEGIES[inferred]
+                return ToolResult.success_result(
+                    data={
+                        "goal": goal,
+                        "strategy": inferred,
+                        "description": strat["description"],
+                        "steps": strat["steps"],
+                        "context": context,
+                        "constraints": constraints,
+                        "inferred": True,
+                    },
+                )
+
+            # Generic exploration plan
+            return ToolResult.success_result(
+                data={
+                    "goal": goal,
+                    "strategy": "custom",
+                    "description": "Custom exploration plan",
+                    "steps": [
+                        {"tool": "semantic_search", "purpose": f"Search for '{goal}'"},
+                        {"tool": "expand_node", "purpose": "Examine top results"},
+                        {"tool": "get_neighbors", "purpose": "Explore connections"},
+                    ],
+                    "context": context,
+                    "constraints": constraints,
+                    "available_strategies": list(STRATEGIES.keys()),
+                },
+            )
+
+        except Exception as e:
+            log.exception("Plan exploration failed")
+            return ToolResult.error_result(f"Planning failed: {str(e)}")
+
+    def _infer_strategy(self, goal: str) -> Optional[str]:
+        """Infer strategy from goal text."""
+        goal_lower = goal.lower()
+
+        if any(word in goal_lower for word in ["bug", "error", "issue", "fix", "debug"]):
+            return "debug_issue"
+
+        if any(word in goal_lower for word in ["how", "understand", "learn", "feature"]):
+            return "understand_feature"
+
+        if any(word in goal_lower for word in ["change", "modify", "refactor", "impact"]):
+            return "assess_change_impact"
+
+        if any(word in goal_lower for word in ["new", "onboard", "overview", "structure"]):
+            return "onboard_codebase"
+
+        if any(word in goal_lower for word in ["similar", "like", "pattern", "example"]):
+            return "find_similar_code"
+
+        return None
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(
+            properties={
+                "goal": {
+                    "type": "string",
+                    "description": "What you want to understand or accomplish",
+                },
+                "strategy": {
+                    "type": "string",
+                    "enum": list(STRATEGIES.keys()),
+                    "description": "Optional predefined strategy to use",
+                },
+                "context": {
+                    "type": "string",
+                    "description": "Additional context about the goal",
+                },
+                "constraints": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Constraints to consider",
+                },
+                "use_case": {
+                    "type": "string",
+                    "enum": ["spec", "debug", "review", "onboard"],
+                    "description": "Use case hint to guide strategy selection",
+                },
+            },
+            required=["goal"],
+        )

emdash_core/agent/tools/plan_write.py

@@ -0,0 +1,135 @@
+"""WritePlan tool for Plan sub-agents.
+
+Allows writing implementation plans to a restricted directory (.emdash/plans/).
+This is the only write operation available to Plan agents.
+"""
+
+from pathlib import Path
+import re
+
+from .base import BaseTool, ToolResult, ToolCategory
+from ...utils.logger import log
+
+
+class WritePlanTool(BaseTool):
+    """Write implementation plan to .emdash/plans/ directory only.
+
+    This tool is restricted to writing markdown files only to the
+    .emdash/plans/ directory. It cannot write to any other location.
+    """
+
+    name = "write_plan"
+    description = """Write or update an implementation plan markdown file.
+
+Plans are saved to .emdash/plans/<filename>.md in the repository.
+Use this to document implementation strategies, architectural decisions,
+and step-by-step plans.
+
+Example filenames: "auth-refactor.md", "api-redesign.md", "feature-plan.md"
+"""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, repo_root: Path, connection=None):
+        """Initialize with repo root.
+
+        Args:
+            repo_root: Root directory of the repository
+            connection: Optional connection (not used)
+        """
+        self.repo_root = repo_root.resolve()
+        self.plans_dir = self.repo_root / ".emdash" / "plans"
+        self.connection = connection
+
+    def execute(
+        self,
+        filename: str = "",
+        content: str = "",
+        **kwargs,
+    ) -> ToolResult:
+        """Write a plan file.
+
+        Args:
+            filename: Plan filename (e.g., "auth-refactor.md")
+            content: Markdown content for the plan
+
+        Returns:
+            ToolResult indicating success or error
+        """
+        # Validate filename
+        if not filename:
+            return ToolResult.error_result("Filename is required")
+
+        # Ensure .md extension
+        if not filename.endswith(".md"):
+            filename = f"{filename}.md"
+
+        # Sanitize filename - remove path components and invalid chars
+        safe_filename = Path(filename).name
+        safe_filename = re.sub(r'[<>:"/\\|?*]', '-', safe_filename)
+
+        if not safe_filename or safe_filename.startswith('.'):
+            return ToolResult.error_result(
+                f"Invalid filename: {filename}",
+                suggestions=["Use alphanumeric characters, hyphens, underscores"],
+            )
+
+        # Build full path
+        plan_path = self.plans_dir / safe_filename
+
+        # Validate path is within plans directory (prevent traversal)
+        try:
+            plan_path.resolve().relative_to(self.plans_dir.resolve())
+        except ValueError:
+            return ToolResult.error_result(
+                "Path traversal not allowed",
+                suggestions=["Provide a simple filename without directory paths"],
+            )
+
+        try:
+            # Create plans directory if needed
+            self.plans_dir.mkdir(parents=True, exist_ok=True)
+
+            # Check if updating existing file
+            is_update = plan_path.exists()
+
+            # Write the plan
+            plan_path.write_text(content)
+
+            log.info(
+                "Plan {} written: {}",
+                "updated" if is_update else "created",
+                plan_path,
+            )
+
+            return ToolResult.success_result(
+                data={
+                    "path": str(plan_path.relative_to(self.repo_root)),
+                    "filename": safe_filename,
+                    "bytes_written": len(content),
+                    "is_update": is_update,
+                },
+            )
+
+        except PermissionError:
+            return ToolResult.error_result(
+                f"Permission denied writing to {plan_path}",
+            )
+        except Exception as e:
+            log.exception("Failed to write plan")
+            return ToolResult.error_result(f"Failed to write plan: {e}")
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(
+            properties={
+                "filename": {
+                    "type": "string",
+                    "description": "Plan filename (e.g., 'auth-refactor.md', 'feature-plan')",
+                },
+                "content": {
+                    "type": "string",
+                    "description": "Markdown content for the implementation plan",
+                },
+            },
+            required=["filename", "content"],
+        )