emdash-core 0.1.7__py3-none-any.whl → 0.1.25__py3-none-any.whl

emdash_core/agent/tools/modes.py

@@ -1,7 +1,7 @@
 """Agent mode management tools.
 
-Provides tools for switching between different agent modes
-(exploration, planning, coding, etc).
+Provides tools for entering and exiting modes, following
+Claude Code's approach of explicit mode transitions.
 """
 
 from dataclasses import dataclass
@@ -13,27 +13,23 @@ from .base import BaseTool, ToolResult, ToolCategory
 
 class AgentMode(Enum):
     """Available agent modes."""
+    PLAN = "plan"
+    CODE = "code"
 
-    EXPLORATION = "exploration"
-    PLANNING = "planning"
-    CODING = "coding"
-    REVIEW = "review"
-    DEBUG = "debug"
+
+# Modes that can be entered via enter_mode tool
+SUPPORTED_MODES = ["plan"]  # Extensible list
 
 
 @dataclass
 class ModeState:
     """Singleton state for agent mode."""
 
-    current_mode: AgentMode = AgentMode.EXPLORATION
-    mode_context: dict = None
+    current_mode: AgentMode = AgentMode.CODE
+    plan_content: Optional[str] = None  # Stores the current plan
 
     _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."""
@@ -47,18 +43,16 @@ class ModeState:
         cls._instance = None
 
 
-class SwitchModeTool(BaseTool):
-    """Tool for switching between agent modes."""
+class EnterModeTool(BaseTool):
+    """Tool for entering a different mode from code mode."""
 
-    name = "switch_mode"
-    description = """Switch the agent to a different operating mode.
+    name = "enter_mode"
+    description = """Enter 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"""
+Currently supported modes:
+- plan: Enter plan mode to explore the codebase and design an implementation plan.
+        In plan mode you can ONLY use read-only tools (no file modifications).
+        Use exit_plan when your plan is ready for user approval."""
     category = ToolCategory.PLANNING
 
     def __init__(self, connection=None):
@@ -68,40 +62,49 @@ Modes:
     def execute(
         self,
         mode: str,
-        context: Optional[str] = None,
+        reason: str = "",
+        **kwargs,
     ) -> ToolResult:
-        """Switch to a new mode.
+        """Enter a new mode.
 
         Args:
-            mode: Target mode name
-            context: Optional context for the new mode
+            mode: Mode to enter (currently only "plan" supported)
+            reason: Why you're entering this mode (helps context)
 
         Returns:
-            ToolResult indicating success
+            ToolResult indicating mode switch
         """
-        try:
-            new_mode = AgentMode(mode.lower())
-        except ValueError:
-            valid_modes = [m.value for m in AgentMode]
+        mode_lower = mode.lower()
+
+        if mode_lower not in SUPPORTED_MODES:
             return ToolResult.error_result(
-                f"Invalid mode: {mode}",
-                suggestions=[f"Valid modes: {', '.join(valid_modes)}"],
+                f"Unsupported mode: {mode}",
+                suggestions=[f"Supported modes: {', '.join(SUPPORTED_MODES)}"],
             )
 
         state = ModeState.get_instance()
-        old_mode = state.current_mode
-        state.current_mode = new_mode
 
-        if context:
-            state.mode_context[new_mode.value] = context
+        if mode_lower == "plan":
+            if state.current_mode == AgentMode.PLAN:
+                return ToolResult.error_result(
+                    "Already in plan mode",
+                    suggestions=["Use exit_plan to submit your plan for approval"],
+                )
+
+            state.current_mode = AgentMode.PLAN
+            state.plan_content = None  # Reset plan content
+
+            return ToolResult.success_result(
+                data={
+                    "status": "entered_plan_mode",
+                    "mode": "plan",
+                    "reason": reason,
+                    "message": "You are now in plan mode. Explore the codebase and design your plan. Use exit_plan when ready.",
+                },
+            )
 
-        return ToolResult.success_result(
-            data={
-                "previous_mode": old_mode.value,
-                "current_mode": new_mode.value,
-                "context": context,
-            },
-        )
+        # Placeholder for future modes
+        return ToolResult.error_result(f"Mode '{mode}' not yet implemented")
 
     def get_schema(self) -> dict:
         """Get OpenAI function schema."""
@@ -109,30 +112,171 @@ Modes:
             properties={
                 "mode": {
                     "type": "string",
-                    "enum": [m.value for m in AgentMode],
-                    "description": "Target mode to switch to",
+                    "enum": SUPPORTED_MODES,
+                    "description": "Mode to enter",
                 },
-                "context": {
+                "reason": {
                     "type": "string",
-                    "description": "Optional context for the new mode",
+                    "description": "Brief reason for entering this mode",
                 },
             },
             required=["mode"],
         )
 
 
+class ExitPlanModeTool(BaseTool):
+    """Tool for exiting plan mode and submitting plan for approval."""
+
+    name = "exit_plan"
+    description = """Exit plan mode and submit your plan for user approval.
+
+Scale detail based on task complexity:
+- Simple task: title, summary, files_to_modify (steps optional)
+- Complex task: all fields including phases, risks, open questions
+
+Required fields:
+- title: Clear, concise plan title
+- summary: What will be implemented and why
+- files_to_modify: List of file changes with paths, line numbers, and descriptions
+
+Optional fields (include only if needed - each must "earn its place"):
+- implementation_steps: For complex tasks needing ordered steps
+- risks: Non-trivial risks only
+- testing_strategy: Beyond obvious test cases
+
+The user will either:
+- Approve: You'll return to code mode to implement the plan
+- Reject: You'll receive feedback and can revise in plan mode"""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(
+        self,
+        title: str,
+        summary: str,
+        files_to_modify: list[dict] = None,
+        implementation_steps: list[str] = None,
+        risks: list[str] = None,
+        testing_strategy: str = None,
+        **kwargs,
+    ) -> ToolResult:
+        """Exit plan mode and submit plan for approval.
+
+        Args:
+            title: Title of the plan
+            summary: Summary of what will be implemented and why
+            files_to_modify: List of file changes, each with:
+                - path: File path (e.g., "src/auth.py")
+                - lines: Line range (e.g., "45-60" or "new file")
+                - changes: Description of what changes
+            implementation_steps: Ordered list of detailed implementation steps
+            risks: List of potential risks or considerations
+            testing_strategy: Description of how changes will be tested
+
+        Returns:
+            ToolResult triggering user approval flow
+        """
+        state = ModeState.get_instance()
+
+        if state.current_mode != AgentMode.PLAN:
+            return ToolResult.error_result(
+                "Not in plan mode",
+                suggestions=["Use enter_mode with mode='plan' to enter plan mode first"],
+            )
+
+        if not title or not title.strip():
+            return ToolResult.error_result("Title is required")
+        if not summary or not summary.strip():
+            return ToolResult.error_result("Summary is required")
+        if not files_to_modify:
+            return ToolResult.error_result(
+                "files_to_modify is required",
+                suggestions=["Include at least one file with path, lines, and changes"],
+            )
+        # implementation_steps optional for simple tasks where files_to_modify is self-explanatory
+
+        # Store plan content for reference
+        state.plan_content = summary
+
+        return ToolResult.success_result({
+            "status": "plan_submitted",
+            "title": title.strip(),
+            "summary": summary.strip(),
+            "files_to_modify": files_to_modify,
+            "implementation_steps": implementation_steps or [],
+            "risks": risks or [],
+            "testing_strategy": testing_strategy or "",
+            "message": "Plan submitted for user approval. Waiting for user response.",
+        })
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(
+            properties={
+                "title": {
+                    "type": "string",
+                    "description": "Clear, concise title of the plan",
+                },
+                "summary": {
+                    "type": "string",
+                    "description": "Detailed summary of what will be implemented and why",
+                },
+                "files_to_modify": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "path": {
+                                "type": "string",
+                                "description": "File path (e.g., 'src/auth.py')",
+                            },
+                            "lines": {
+                                "type": "string",
+                                "description": "Line range (e.g., '45-60') or 'new file'",
+                            },
+                            "changes": {
+                                "type": "string",
+                                "description": "Description of what changes in this file",
+                            },
+                        },
+                        "required": ["path", "changes"],
+                    },
+                    "description": "List of files to modify with line numbers and change descriptions",
+                },
+                "implementation_steps": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Detailed ordered list of implementation steps with sub-tasks",
+                },
+                "risks": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Potential risks, breaking changes, or considerations",
+                },
+                "testing_strategy": {
+                    "type": "string",
+                    "description": "How the changes will be tested (unit tests, integration tests, etc.)",
+                },
+            },
+            required=["title", "summary", "files_to_modify"],
+        )
+
+
 class GetModeTool(BaseTool):
     """Tool for getting current agent mode."""
 
     name = "get_mode"
-    description = "Get the current agent operating mode and its context."
+    description = "Get the current agent operating mode (plan or code)."
     category = ToolCategory.PLANNING
 
     def __init__(self, connection=None):
         """Initialize without requiring connection."""
         self.connection = connection
 
-    def execute(self) -> ToolResult:
+    def execute(self, **kwargs) -> ToolResult:
         """Get current mode.
 
         Returns:
@@ -143,8 +287,8 @@ class GetModeTool(BaseTool):
         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],
+                "has_plan": state.plan_content is not None,
+                "available_modes": SUPPORTED_MODES,
             },
         )
 

emdash_core/agent/tools/search.py

@@ -22,6 +22,7 @@ Useful for finding code related to concepts like "authentication", "database que
         entity_types: Optional[list[str]] = None,
         limit: int = 10,
         min_score: float = 0.5,
+        **kwargs,  # Ignore unexpected params from LLM
     ) -> ToolResult:
         """Execute semantic search.
 
@@ -121,6 +122,7 @@ More precise than semantic search when you know part of the name."""
         query: str,
         entity_types: Optional[list[str]] = None,
         limit: int = 10,
+        **kwargs,  # Ignore unexpected params from LLM
     ) -> ToolResult:
         """Execute text search.
 
@@ -215,6 +217,7 @@ Useful for finding code patterns, string literals, or specific implementations."
         file_pattern: Optional[str] = None,
         max_results: int = 50,
         context_lines: int = 2,
+        **kwargs,  # Ignore unexpected params from LLM
     ) -> ToolResult:
         """Execute grep search.
 
@@ -324,6 +327,7 @@ Common patterns:
         self,
         pattern: str,
         max_results: int = 100,
+        **kwargs,  # Ignore unexpected params from LLM
     ) -> ToolResult:
         """Execute glob search for files.
 

emdash_core/agent/tools/skill.py

@@ -0,0 +1,193 @@
+"""Skill invocation tool.
+
+Allows the agent to activate and invoke skills during task execution.
+Skills provide specialized instructions for repeatable tasks.
+"""
+
+from typing import Optional
+
+from .base import BaseTool, ToolResult, ToolCategory
+from ..skills import SkillRegistry, Skill
+
+
+class SkillTool(BaseTool):
+    """Tool for invoking skills.
+
+    Skills are markdown-based instruction files that teach the agent
+    how to perform specific, repeatable tasks. This tool allows
+    explicit skill invocation.
+    """
+
+    name = "skill"
+    description = """Invoke a skill for specialized task execution.
+
+Skills provide focused instructions for common tasks like:
+- commit: Generate commit messages following conventions
+- review-pr: Review PRs with code standards
+- security-review: Security-focused code review
+
+When you invoke a skill, you receive its instructions which you should follow.
+Use list_skills to see available skills."""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(
+        self,
+        skill: str,
+        args: str = "",
+        **kwargs,
+    ) -> ToolResult:
+        """Invoke a skill.
+
+        Args:
+            skill: Name of the skill to invoke
+            args: Optional arguments to pass to the skill
+
+        Returns:
+            ToolResult with skill instructions
+        """
+        registry = SkillRegistry.get_instance()
+        skill_obj = registry.get_skill(skill)
+
+        if skill_obj is None:
+            available = registry.list_skills()
+            if available:
+                return ToolResult.error_result(
+                    f"Skill '{skill}' not found",
+                    suggestions=[f"Available skills: {', '.join(available)}"],
+                )
+            else:
+                return ToolResult.error_result(
+                    f"Skill '{skill}' not found. No skills are currently loaded.",
+                    suggestions=[
+                        "Create skills in .emdash/skills/<skill-name>/SKILL.md",
+                        "Skills are loaded from the .emdash/skills/ directory",
+                    ],
+                )
+
+        # Build the skill activation response
+        response_parts = [
+            f"# Skill Activated: {skill_obj.name}",
+            "",
+            f"**Description**: {skill_obj.description}",
+            "",
+        ]
+
+        if args:
+            response_parts.extend([
+                f"**Arguments**: {args}",
+                "",
+            ])
+
+        if skill_obj.tools:
+            response_parts.extend([
+                f"**Required tools**: {', '.join(skill_obj.tools)}",
+                "",
+            ])
+
+        response_parts.extend([
+            "---",
+            "",
+            skill_obj.instructions,
+        ])
+
+        return ToolResult.success_result(
+            data={
+                "skill_name": skill_obj.name,
+                "description": skill_obj.description,
+                "instructions": skill_obj.instructions,
+                "tools": skill_obj.tools,
+                "args": args,
+                "message": "\n".join(response_parts),
+            },
+        )
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        registry = SkillRegistry.get_instance()
+        available_skills = registry.list_skills()
+
+        description = self.description
+        if available_skills:
+            description += f"\n\nCurrently available skills: {', '.join(available_skills)}"
+
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": description,
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "skill": {
+                            "type": "string",
+                            "description": "Name of the skill to invoke",
+                        },
+                        "args": {
+                            "type": "string",
+                            "description": "Optional arguments for the skill (e.g., PR number, file path)",
+                        },
+                    },
+                    "required": ["skill"],
+                },
+            },
+        }
+
+
+class ListSkillsTool(BaseTool):
+    """Tool for listing available skills."""
+
+    name = "list_skills"
+    description = "List all available skills and their descriptions."
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(self, **kwargs) -> ToolResult:
+        """List available skills.
+
+        Returns:
+            ToolResult with list of skills
+        """
+        registry = SkillRegistry.get_instance()
+        skills = registry.get_all_skills()
+
+        if not skills:
+            return ToolResult.success_result(
+                data={
+                    "skills": [],
+                    "message": "No skills loaded. Create skills in .emdash/skills/<skill-name>/SKILL.md",
+                },
+            )
+
+        skills_list = []
+        for skill in skills.values():
+            skills_list.append({
+                "name": skill.name,
+                "description": skill.description,
+                "user_invocable": skill.user_invocable,
+                "tools": skill.tools,
+            })
+
+        # Build human-readable message
+        lines = ["# Available Skills", ""]
+        for s in skills_list:
+            invocable = f" (invoke with /{s['name']})" if s["user_invocable"] else ""
+            lines.append(f"- **{s['name']}**: {s['description']}{invocable}")
+
+        return ToolResult.success_result(
+            data={
+                "skills": skills_list,
+                "count": len(skills_list),
+                "message": "\n".join(lines),
+            },
+        )
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(properties={}, required=[])