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

emdash_core/agent/skills.py

@@ -6,6 +6,10 @@ when relevant or explicitly invoked via /skill_name.
 
 Similar to Claude Code's skills system:
 https://docs.anthropic.com/en/docs/claude-code/skills
+
+Skills are loaded from two locations:
+1. Built-in skills bundled with emdash_core (always available)
+2. User repo skills in .emdash/skills/ (can override built-in)
 """
 
 from dataclasses import dataclass, field
@@ -15,6 +19,11 @@ from typing import Optional
 from ..utils.logger import log
 
 
+def _get_builtin_skills_dir() -> Path:
+    """Get the directory containing built-in skills bundled with emdash_core."""
+    return Path(__file__).parent.parent / "skills"
+
+
 @dataclass
 class Skill:
     """A skill configuration loaded from SKILL.md.
@@ -26,6 +35,7 @@ class Skill:
         tools: List of tools this skill needs access to
         user_invocable: Whether skill can be invoked with /name
         file_path: Source file path
+        _builtin: Whether this is a built-in skill bundled with emdash_core
     """
 
     name: str
@@ -34,6 +44,7 @@ class Skill:
     tools: list[str] = field(default_factory=list)
     user_invocable: bool = False
     file_path: Optional[Path] = None
+    _builtin: bool = False
 
 
 class SkillRegistry:
@@ -67,7 +78,11 @@ class SkillRegistry:
             cls._instance._skills_dir = None
 
     def load_skills(self, skills_dir: Optional[Path] = None) -> dict[str, Skill]:
-        """Load skills from .emdash/skills/ directory.
+        """Load skills from built-in and user repo directories.
+
+        Skills are loaded from two locations (in order):
+        1. Built-in skills bundled with emdash_core (always available)
+        2. User repo skills in .emdash/skills/ (can override built-in)
 
         Each skill is a directory containing a SKILL.md file:
 
@@ -94,7 +109,7 @@ class SkillRegistry:
         ```
 
         Args:
-            skills_dir: Directory containing skill subdirectories.
+            skills_dir: Directory containing user skill subdirectories.
                        Defaults to .emdash/skills/ in cwd.
 
         Returns:
@@ -105,9 +120,34 @@ class SkillRegistry:
 
         self._skills_dir = skills_dir
 
-        if not skills_dir.exists():
-            return {}
+        skills = {}
+
+        # First, load built-in skills bundled with emdash_core
+        builtin_dir = _get_builtin_skills_dir()
+        if builtin_dir.exists():
+            builtin_skills = self._load_skills_from_dir(builtin_dir, is_builtin=True)
+            skills.update(builtin_skills)
+
+        # Then, load user repo skills (can override built-in)
+        if skills_dir.exists():
+            user_skills = self._load_skills_from_dir(skills_dir, is_builtin=False)
+            skills.update(user_skills)
 
+        if skills:
+            log.info(f"Loaded {len(skills)} skills ({len([s for s in self._skills.values() if getattr(s, '_builtin', False)])} built-in)")
+
+        return skills
+
+    def _load_skills_from_dir(self, skills_dir: Path, is_builtin: bool = False) -> dict[str, Skill]:
+        """Load skills from a specific directory.
+
+        Args:
+            skills_dir: Directory containing skill subdirectories
+            is_builtin: Whether these are built-in skills
+
+        Returns:
+            Dict mapping skill name to Skill
+        """
         skills = {}
 
         # Look for SKILL.md in subdirectories
@@ -125,15 +165,14 @@ class SkillRegistry:
             try:
                 skill = _parse_skill_file(skill_file, skill_dir.name)
                 if skill:
+                    skill._builtin = is_builtin  # Mark as built-in or user-defined
                     skills[skill.name] = skill
                     self._skills[skill.name] = skill
-                    log.debug(f"Loaded skill: {skill.name}")
+                    source = "built-in" if is_builtin else "user"
+                    log.debug(f"Loaded {source} skill: {skill.name}")
             except Exception as e:
                 log.warning(f"Failed to load skill from {skill_file}: {e}")
 
-        if skills:
-            log.info(f"Loaded {len(skills)} skills")
-
         return skills
 
     def get_skill(self, name: str) -> Optional[Skill]:

emdash_core/agent/toolkit.py

@@ -41,6 +41,7 @@ class AgentToolkit:
         repo_root: Optional[Path] = None,
         plan_mode: bool = False,
         save_spec_path: Optional[Path] = None,
+        plan_file_path: Optional[str] = None,
     ):
         """Initialize the agent toolkit.
 
@@ -53,6 +54,7 @@ class AgentToolkit:
                       If None, uses repo_root from config or current working directory.
             plan_mode: Whether to include spec planning tools and restrict to read-only.
             save_spec_path: If provided, specs will be saved to this path.
+            plan_file_path: Path to the plan file (only writable file in plan mode).
         """
         self.connection = connection or get_connection()
         self.session = AgentSession() if enable_session else None
@@ -61,6 +63,7 @@ class AgentToolkit:
         self._mcp_config_path = mcp_config_path
         self.plan_mode = plan_mode
         self.save_spec_path = save_spec_path
+        self.plan_file_path = plan_file_path
 
         # Get repo_root from config if not explicitly provided
         if repo_root is None:
@@ -70,8 +73,12 @@ class AgentToolkit:
                 repo_root = Path(config.repo_root)
         self._repo_root = repo_root or Path.cwd()
 
-        # Configure spec state if plan mode
+        # Configure mode state and spec state if plan mode
         if plan_mode:
+            from .tools.modes import ModeState, AgentMode
+            mode_state = ModeState.get_instance()
+            mode_state.current_mode = AgentMode.PLAN
+
             from .tools.spec import SpecState
             spec_state = SpecState.get_instance()
             spec_state.configure(save_path=save_spec_path)
@@ -110,8 +117,18 @@ class AgentToolkit:
         self.register_tool(ReadFileTool(self._repo_root, self.connection))
         self.register_tool(ListFilesTool(self._repo_root, self.connection))
 
-        # Register write tools (only in non-plan mode)
-        if not self.plan_mode:
+        # Register write tools
+        if self.plan_mode:
+            # In plan mode: only allow writing to the plan file
+            if self.plan_file_path:
+                from .tools.coding import WriteToFileTool
+                self.register_tool(WriteToFileTool(
+                    self._repo_root,
+                    self.connection,
+                    allowed_paths=[self.plan_file_path],
+                ))
+        else:
+            # In code mode: full write access
             from .tools.coding import (
                 WriteToFileTool,
                 ApplyDiffTool,
@@ -129,8 +146,12 @@ class AgentToolkit:
         # Register mode tools
         self._register_mode_tools()
 
-        # Register task management tools (not in plan mode)
-        if not self.plan_mode:
+        # Register task management tools
+        # In plan mode: only register ask_followup_question for clarifications
+        # In code mode: register all task tools
+        if self.plan_mode:
+            self._register_plan_mode_task_tools()
+        else:
             self._register_task_tools()
 
         # Register spec planning tools (only in plan mode)
@@ -162,21 +183,32 @@ class AgentToolkit:
     def _register_mode_tools(self) -> None:
         """Register mode switching tools.
 
-        - enter_mode: Available in code mode to enter other modes (e.g., plan)
-        - exit_plan: Available in plan mode to submit plan and request approval
+        - enter_plan_mode: Available in code mode to request entering plan mode
+        - exit_plan: Available in both modes to submit plan for approval
         - get_mode: Always available to check current mode
         """
-        from .tools.modes import EnterModeTool, ExitPlanModeTool, GetModeTool
+        from .tools.modes import EnterPlanModeTool, ExitPlanModeTool, GetModeTool
 
         # get_mode is always available
         self.register_tool(GetModeTool())
 
-        if self.plan_mode:
-            # In plan mode: can exit with plan submission
-            self.register_tool(ExitPlanModeTool())
-        else:
-            # In code mode: can enter other modes
-            self.register_tool(EnterModeTool())
+        # exit_plan is available in both modes:
+        # - In plan mode: submit plan written to plan file
+        # - In code mode: submit plan received from Plan subagent
+        self.register_tool(ExitPlanModeTool())
+
+        if not self.plan_mode:
+            # In code mode: can also request to enter plan mode
+            self.register_tool(EnterPlanModeTool())
+
+    def _register_plan_mode_task_tools(self) -> None:
+        """Register subset of task tools for plan mode.
+
+        In plan mode, the agent can ask clarifying questions but
+        doesn't need completion/todo tools since exit_plan handles that.
+        """
+        from .tools.tasks import AskFollowupQuestionTool
+        self.register_tool(AskFollowupQuestionTool())
 
     def _register_task_tools(self) -> None:
         """Register task management tools.

emdash_core/agent/toolkits/__init__.py

@@ -2,10 +2,13 @@
 
 Provides specialized toolkits for different agent types.
 Each toolkit contains a curated set of tools appropriate for the agent's purpose.
+
+Custom agents from .emdash/agents/*.md are also supported and use the Explore toolkit
+by default (unless they specify different tools in their frontmatter).
 """
 
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, Type
+from typing import TYPE_CHECKING, Dict, Type, Optional
 
 if TYPE_CHECKING:
     from .base import BaseToolkit
@@ -20,45 +23,141 @@ TOOLKIT_REGISTRY: Dict[str, str] = {
 }
 
 
+def _get_custom_agents(repo_root: Optional[Path] = None) -> dict:
+    """Load custom agents from .emdash/agents/ directory.
+
+    Args:
+        repo_root: Repository root (defaults to cwd)
+
+    Returns:
+        Dict mapping agent name to CustomAgent
+    """
+    from ..agents import load_agents
+    from ...utils.logger import log
+
+    agents_dir = (repo_root or Path.cwd()) / ".emdash" / "agents"
+    log.debug(f"Loading custom agents from: {agents_dir} (exists={agents_dir.exists()})")
+    agents = load_agents(agents_dir)
+    log.debug(f"Loaded custom agents: {list(agents.keys())}")
+    return agents
+
+
 def get_toolkit(subagent_type: str, repo_root: Path) -> "BaseToolkit":
     """Get toolkit for agent type.
 
     Args:
-        subagent_type: Type of agent (e.g., "Explore", "Plan")
+        subagent_type: Type of agent (e.g., "Explore", "Plan", or custom agent name)
         repo_root: Root directory of the repository
 
     Returns:
         Toolkit instance
 
     Raises:
-        ValueError: If agent type is not registered
+        ValueError: If agent type is not registered or found
+    """
+    # Check built-in agents first
+    if subagent_type in TOOLKIT_REGISTRY:
+        import importlib
+        module_path, class_name = TOOLKIT_REGISTRY[subagent_type].rsplit(":", 1)
+        module = importlib.import_module(module_path)
+        toolkit_class = getattr(module, class_name)
+        return toolkit_class(repo_root)
+
+    # Check custom agents
+    custom_agents = _get_custom_agents(repo_root)
+    if subagent_type in custom_agents:
+        # Custom agents use Explore toolkit by default (read-only, safe)
+        # This gives them: glob, grep, read_file, list_files, semantic_search
+        # Plus any MCP servers defined in the agent's frontmatter
+        import importlib
+        from ...utils.logger import log
+
+        custom_agent = custom_agents[subagent_type]
+        module_path, class_name = TOOLKIT_REGISTRY["Explore"].rsplit(":", 1)
+        module = importlib.import_module(module_path)
+        toolkit_class = getattr(module, class_name)
+
+        # Pass MCP servers if defined
+        mcp_servers = custom_agent.mcp_servers if custom_agent.mcp_servers else None
+        if mcp_servers:
+            log.info(f"Custom agent '{subagent_type}' has {len(mcp_servers)} MCP servers")
+
+        return toolkit_class(repo_root, mcp_servers=mcp_servers)
+
+    # Not found
+    available = list_agent_types(repo_root)
+    raise ValueError(
+        f"Unknown agent type: {subagent_type}. Available: {available}"
+    )
+
+
+def list_agent_types(repo_root: Optional[Path] = None) -> list[str]:
+    """List all available agent types (built-in + custom).
+
+    Args:
+        repo_root: Repository root for finding custom agents
+
+    Returns:
+        List of agent type names
     """
-    if subagent_type not in TOOLKIT_REGISTRY:
-        available = list(TOOLKIT_REGISTRY.keys())
-        raise ValueError(
-            f"Unknown agent type: {subagent_type}. Available: {available}"
-        )
+    # Start with built-in agents
+    types = list(TOOLKIT_REGISTRY.keys())
 
-    # Import lazily to avoid circular imports
-    import importlib
+    # Add custom agents
+    custom_agents = _get_custom_agents(repo_root)
+    for name in custom_agents.keys():
+        if name not in types:
+            types.append(name)
 
-    module_path, class_name = TOOLKIT_REGISTRY[subagent_type].rsplit(":", 1)
-    module = importlib.import_module(module_path)
-    toolkit_class = getattr(module, class_name)
-    return toolkit_class(repo_root)
+    return types
 
 
-def list_agent_types() -> list[str]:
-    """List all available agent types.
+def get_agents_with_descriptions(repo_root: Optional[Path] = None) -> list[dict]:
+    """Get all agents with their names and descriptions.
+
+    Args:
+        repo_root: Repository root for finding custom agents
 
     Returns:
-        List of agent type names
+        List of dicts with 'name' and 'description' keys
+    """
+    from ..prompts.subagents import BUILTIN_AGENTS
+
+    agents = []
+
+    # Built-in agents
+    for name, description in BUILTIN_AGENTS.items():
+        agents.append({"name": name, "description": description})
+
+    # Custom agents
+    custom_agents = _get_custom_agents(repo_root)
+    for name, agent in custom_agents.items():
+        agents.append({
+            "name": name,
+            "description": agent.description or "Custom agent"
+        })
+
+    return agents
+
+
+def get_custom_agent(name: str, repo_root: Optional[Path] = None):
+    """Get a specific custom agent by name.
+
+    Args:
+        name: Agent name
+        repo_root: Repository root
+
+    Returns:
+        CustomAgent or None
     """
-    return list(TOOLKIT_REGISTRY.keys())
+    custom_agents = _get_custom_agents(repo_root)
+    return custom_agents.get(name)
 
 
 __all__ = [
     "get_toolkit",
     "list_agent_types",
+    "get_agents_with_descriptions",
+    "get_custom_agent",
     "TOOLKIT_REGISTRY",
 ]

emdash_core/agent/toolkits/base.py

@@ -2,10 +2,14 @@
 
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
 
 from ..tools.base import BaseTool, ToolResult
 
+if TYPE_CHECKING:
+    from ..agents import AgentMCPServerConfig
+    from ..mcp.manager import MCPServerManager
+
 
 class BaseToolkit(ABC):
     """Abstract base class for sub-agent toolkits.
@@ -15,20 +19,30 @@ class BaseToolkit(ABC):
     - Registering appropriate tools
     - Providing OpenAI function schemas
     - Executing tools by name
+    - Managing per-agent MCP servers (optional)
     """
 
     # List of tool names this toolkit provides (for documentation)
     TOOLS: list[str] = []
 
-    def __init__(self, repo_root: Path):
+    def __init__(
+        self,
+        repo_root: Path,
+        mcp_servers: Optional[list["AgentMCPServerConfig"]] = None,
+    ):
         """Initialize the toolkit.
 
         Args:
             repo_root: Root directory of the repository
+            mcp_servers: Optional list of MCP server configurations for this agent
         """
         self.repo_root = repo_root.resolve()
         self._tools: dict[str, BaseTool] = {}
+        self._mcp_manager: Optional["MCPServerManager"] = None
+        self._mcp_servers_config = mcp_servers or []
+
         self._register_tools()
+        self._init_mcp_servers()
 
     @abstractmethod
     def _register_tools(self) -> None:
@@ -38,6 +52,77 @@ class BaseToolkit(ABC):
         """
         pass
 
+    def _init_mcp_servers(self) -> None:
+        """Initialize MCP servers for this agent if configured.
+
+        Creates an MCPServerManager with the agent's MCP server configs
+        and registers the tools from those servers. Only enabled servers
+        are started.
+        """
+        if not self._mcp_servers_config:
+            return
+
+        # Filter to only enabled servers
+        enabled_servers = [s for s in self._mcp_servers_config if s.enabled]
+        if not enabled_servers:
+            return
+
+        from ..mcp.config import MCPServerConfig, MCPConfigFile
+        from ..mcp.manager import MCPServerManager
+        from ..mcp.tool_factory import create_tools_from_mcp
+        from ...utils.logger import log
+
+        log.info(f"Initializing {len(enabled_servers)} MCP servers for agent")
+
+        # Create a temporary config file object with our servers
+        config = MCPConfigFile()
+        for server_cfg in enabled_servers:
+            mcp_config = MCPServerConfig(
+                name=server_cfg.name,
+                command=server_cfg.command,
+                args=server_cfg.args,
+                env=server_cfg.env,
+                enabled=True,
+                timeout=server_cfg.timeout,
+            )
+            config.add_server(mcp_config)
+
+        # Create manager with in-memory config (not from file)
+        self._mcp_manager = MCPServerManager(repo_root=self.repo_root)
+        self._mcp_manager._config = config  # Inject our config directly
+
+        # Start all servers and register tools
+        try:
+            started = self._mcp_manager.start_all_enabled()
+            log.info(f"Started MCP servers for agent: {started}")
+
+            # Create tool wrappers and register them
+            mcp_tools = create_tools_from_mcp(self._mcp_manager)
+            for tool in mcp_tools:
+                self.register_tool(tool)
+                log.debug(f"Registered MCP tool: {tool.name}")
+
+        except Exception as e:
+            log.warning(f"Failed to initialize MCP servers for agent: {e}")
+
+    def shutdown(self) -> None:
+        """Shutdown the toolkit and cleanup resources.
+
+        Stops any running MCP servers.
+        """
+        if self._mcp_manager:
+            from ...utils.logger import log
+            log.info("Shutting down agent MCP servers")
+            self._mcp_manager.shutdown_all()
+            self._mcp_manager = None
+
+    def __del__(self):
+        """Cleanup on garbage collection."""
+        try:
+            self.shutdown()
+        except Exception:
+            pass
+
     def register_tool(self, tool: BaseTool) -> None:
         """Register a tool.
 

emdash_core/agent/toolkits/explore.py

@@ -1,12 +1,16 @@
 """Explorer toolkit - read-only tools for fast codebase exploration."""
 
 from pathlib import Path
+from typing import TYPE_CHECKING, Optional
 
 from .base import BaseToolkit
 from ..tools.coding import ReadFileTool, ListFilesTool
 from ..tools.search import SemanticSearchTool, GrepTool, GlobTool
 from ...utils.logger import log
 
+if TYPE_CHECKING:
+    from ..agents import AgentMCPServerConfig
+
 
 class ExploreToolkit(BaseToolkit):
     """Read-only toolkit for fast codebase exploration.
@@ -16,6 +20,7 @@ class ExploreToolkit(BaseToolkit):
     - Listing directory contents
     - Searching with patterns (grep, glob)
     - Semantic code search
+    - MCP server tools (if configured)
 
     All tools are read-only - no file modifications allowed.
     """
@@ -28,6 +33,19 @@ class ExploreToolkit(BaseToolkit):
         "semantic_search",
     ]
 
+    def __init__(
+        self,
+        repo_root: Path,
+        mcp_servers: Optional[list["AgentMCPServerConfig"]] = None,
+    ):
+        """Initialize the explore toolkit.
+
+        Args:
+            repo_root: Root directory of the repository
+            mcp_servers: Optional MCP server configurations for this agent
+        """
+        super().__init__(repo_root, mcp_servers=mcp_servers)
+
     def _register_tools(self) -> None:
         """Register read-only exploration tools."""
         # File reading

emdash_core/agent/toolkits/plan.py

@@ -1,19 +1,26 @@
-"""Plan toolkit - exploration tools plus plan writing capability."""
+"""Plan toolkit - read-only exploration tools for planning.
+
+The Plan subagent explores the codebase and returns a plan as text.
+The main agent (in plan mode) writes the plan to .emdash/<feature>.md.
+"""
 
 from pathlib import Path
+from typing import TYPE_CHECKING, Optional
 
 from .base import BaseToolkit
 from ..tools.coding import ReadFileTool, ListFilesTool
 from ..tools.search import SemanticSearchTool, GrepTool, GlobTool
-from ..tools.plan_write import WritePlanTool
 from ...utils.logger import log
 
+if TYPE_CHECKING:
+    from ..agents import AgentMCPServerConfig
+
 
 class PlanToolkit(BaseToolkit):
-    """Toolkit for planning with limited write access (plan files only).
+    """Read-only toolkit for Plan subagent.
 
-    Provides all read-only exploration tools plus the ability to write
-    implementation plans to .emdash/plans/*.md.
+    The Plan subagent explores the codebase and returns a structured plan.
+    It does NOT write files - the main agent handles that.
 
     Tools available:
     - read_file: Read file contents
@@ -21,7 +28,7 @@ class PlanToolkit(BaseToolkit):
     - glob: Find files by pattern
     - grep: Search file contents
     - semantic_search: AI-powered code search
-    - write_plan: Write implementation plans (restricted to .emdash/plans/)
+    - MCP server tools (if configured)
     """
 
     TOOLS = [
@@ -30,11 +37,23 @@ class PlanToolkit(BaseToolkit):
         "glob",
         "grep",
         "semantic_search",
-        "write_plan",
     ]
 
+    def __init__(
+        self,
+        repo_root: Path,
+        mcp_servers: Optional[list["AgentMCPServerConfig"]] = None,
+    ):
+        """Initialize the plan toolkit.
+
+        Args:
+            repo_root: Root directory of the repository
+            mcp_servers: Optional MCP server configurations for this agent
+        """
+        super().__init__(repo_root, mcp_servers=mcp_servers)
+
     def _register_tools(self) -> None:
-        """Register exploration and plan writing tools."""
+        """Register read-only exploration tools."""
         # All read-only exploration tools
         self.register_tool(ReadFileTool(repo_root=self.repo_root))
         self.register_tool(ListFilesTool(repo_root=self.repo_root))
@@ -49,7 +68,4 @@ class PlanToolkit(BaseToolkit):
         except Exception as e:
             log.debug(f"Semantic search not available: {e}")
 
-        # Special: can only write to .emdash/plans/*.md
-        self.register_tool(WritePlanTool(repo_root=self.repo_root))
-
         log.debug(f"PlanToolkit registered {len(self._tools)} tools")

emdash_core/agent/tools/__init__.py

@@ -43,7 +43,7 @@ from .tasks import (
 from .plan import PlanExplorationTool
 
 # Mode tools
-from .modes import AgentMode, ModeState, EnterModeTool, ExitPlanModeTool, GetModeTool
+from .modes import AgentMode, ModeState, EnterPlanModeTool, ExitPlanModeTool, GetModeTool
 
 # Spec tools
 from .spec import SubmitSpecTool, GetSpecTool, UpdateSpecTool
@@ -111,7 +111,7 @@ __all__ = [
     # Mode
     "AgentMode",
     "ModeState",
-    "EnterModeTool",
+    "EnterPlanModeTool",
     "ExitPlanModeTool",
     "GetModeTool",
     # Spec