emdash-core 0.1.7__py3-none-any.whl

emdash_core/agent/tools/spec.py

@@ -0,0 +1,341 @@
+"""Spec planning tools for feature specifications."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from .base import BaseTool, ToolResult, ToolCategory
+from ..spec_schema import Spec
+from ...utils.logger import log
+
+
+@dataclass
+class SpecState:
+    """Singleton state for spec management."""
+
+    current_spec: Optional[Spec] = None
+    save_path: Optional[Path] = None
+    history: list[Spec] = field(default_factory=list)
+
+    _instance: Optional["SpecState"] = None
+
+    @classmethod
+    def get_instance(cls) -> "SpecState":
+        """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
+
+    def configure(self, save_path: Optional[Path] = None) -> None:
+        """Configure the spec state.
+
+        Args:
+            save_path: Path to save specs to
+        """
+        self.save_path = save_path
+
+
+class SubmitSpecTool(BaseTool):
+    """Tool for submitting a new specification."""
+
+    name = "submit_spec"
+    description = """Submit a feature specification for review.
+Creates a structured spec document with requirements and acceptance criteria."""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(
+        self,
+        title: str,
+        summary: str,
+        requirements: list[str],
+        acceptance_criteria: list[str],
+        technical_notes: Optional[list[str]] = None,
+        dependencies: Optional[list[str]] = None,
+        open_questions: Optional[list[str]] = None,
+    ) -> ToolResult:
+        """Submit a specification.
+
+        Args:
+            title: Spec title
+            summary: Brief summary
+            requirements: List of requirements
+            acceptance_criteria: Acceptance criteria
+            technical_notes: Optional technical notes
+            dependencies: Optional dependencies
+            open_questions: Optional open questions
+
+        Returns:
+            ToolResult with spec info
+        """
+        try:
+            spec = Spec(
+                title=title,
+                summary=summary,
+                requirements=requirements,
+                acceptance_criteria=acceptance_criteria,
+                technical_notes=technical_notes or [],
+                dependencies=dependencies or [],
+                open_questions=open_questions or [],
+            )
+
+            # Validate
+            errors = spec.validate()
+            if errors:
+                return ToolResult.error_result(
+                    f"Spec validation failed: {', '.join(errors)}",
+                    suggestions=["Ensure all required fields are provided"],
+                )
+
+            # Store in state
+            state = SpecState.get_instance()
+            if state.current_spec:
+                state.history.append(state.current_spec)
+            state.current_spec = spec
+
+            # Save to file if configured
+            if state.save_path:
+                try:
+                    state.save_path.write_text(spec.to_markdown())
+                    log.info(f"Saved spec to {state.save_path}")
+                except Exception as e:
+                    log.warning(f"Failed to save spec: {e}")
+
+            return ToolResult.success_result(
+                data={
+                    "title": title,
+                    "requirements_count": len(requirements),
+                    "acceptance_criteria_count": len(acceptance_criteria),
+                    "markdown": spec.to_markdown(),
+                },
+            )
+
+        except Exception as e:
+            log.exception("Submit spec failed")
+            return ToolResult.error_result(f"Failed to submit spec: {str(e)}")
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(
+            properties={
+                "title": {
+                    "type": "string",
+                    "description": "Spec title",
+                },
+                "summary": {
+                    "type": "string",
+                    "description": "Brief summary of the feature",
+                },
+                "requirements": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "List of requirements",
+                },
+                "acceptance_criteria": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Acceptance criteria for completion",
+                },
+                "technical_notes": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Technical implementation notes",
+                },
+                "dependencies": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Dependencies on other features/specs",
+                },
+                "open_questions": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Open questions to resolve",
+                },
+            },
+            required=["title", "summary", "requirements", "acceptance_criteria"],
+        )
+
+
+class GetSpecTool(BaseTool):
+    """Tool for getting the current specification."""
+
+    name = "get_spec"
+    description = """Get the current feature specification.
+Returns the spec in markdown format."""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(self) -> ToolResult:
+        """Get the current spec.
+
+        Returns:
+            ToolResult with spec content
+        """
+        state = SpecState.get_instance()
+
+        if not state.current_spec:
+            return ToolResult.error_result(
+                "No spec has been submitted yet",
+                suggestions=["Use submit_spec to create a specification"],
+            )
+
+        spec = state.current_spec
+
+        return ToolResult.success_result(
+            data={
+                "title": spec.title,
+                "summary": spec.summary,
+                "requirements": spec.requirements,
+                "acceptance_criteria": spec.acceptance_criteria,
+                "technical_notes": spec.technical_notes,
+                "dependencies": spec.dependencies,
+                "open_questions": spec.open_questions,
+                "markdown": spec.to_markdown(),
+                "is_complete": spec.is_complete(),
+            },
+        )
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(properties={}, required=[])
+
+
+class UpdateSpecTool(BaseTool):
+    """Tool for updating the current specification."""
+
+    name = "update_spec"
+    description = """Update the current feature specification.
+Add or modify requirements, criteria, or other fields."""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(
+        self,
+        add_requirements: Optional[list[str]] = None,
+        add_acceptance_criteria: Optional[list[str]] = None,
+        add_technical_notes: Optional[list[str]] = None,
+        add_dependencies: Optional[list[str]] = None,
+        add_open_questions: Optional[list[str]] = None,
+        resolve_questions: Optional[list[str]] = None,
+        update_summary: Optional[str] = None,
+    ) -> ToolResult:
+        """Update the current spec.
+
+        Args:
+            add_requirements: Requirements to add
+            add_acceptance_criteria: Criteria to add
+            add_technical_notes: Notes to add
+            add_dependencies: Dependencies to add
+            add_open_questions: Questions to add
+            resolve_questions: Questions to mark as resolved
+            update_summary: New summary text
+
+        Returns:
+            ToolResult with updated spec
+        """
+        state = SpecState.get_instance()
+
+        if not state.current_spec:
+            return ToolResult.error_result(
+                "No spec to update",
+                suggestions=["Use submit_spec first"],
+            )
+
+        spec = state.current_spec
+
+        # Add new items
+        if add_requirements:
+            spec.requirements.extend(add_requirements)
+        if add_acceptance_criteria:
+            spec.acceptance_criteria.extend(add_acceptance_criteria)
+        if add_technical_notes:
+            spec.technical_notes.extend(add_technical_notes)
+        if add_dependencies:
+            spec.dependencies.extend(add_dependencies)
+        if add_open_questions:
+            spec.open_questions.extend(add_open_questions)
+
+        # Resolve questions
+        if resolve_questions:
+            spec.open_questions = [
+                q for q in spec.open_questions
+                if q not in resolve_questions
+            ]
+
+        # Update summary
+        if update_summary:
+            spec.summary = update_summary
+
+        # Save if configured
+        if state.save_path:
+            try:
+                state.save_path.write_text(spec.to_markdown())
+            except Exception as e:
+                log.warning(f"Failed to save spec: {e}")
+
+        return ToolResult.success_result(
+            data={
+                "title": spec.title,
+                "requirements_count": len(spec.requirements),
+                "acceptance_criteria_count": len(spec.acceptance_criteria),
+                "open_questions_count": len(spec.open_questions),
+                "is_complete": spec.is_complete(),
+                "markdown": spec.to_markdown(),
+            },
+        )
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(
+            properties={
+                "add_requirements": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Requirements to add",
+                },
+                "add_acceptance_criteria": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Acceptance criteria to add",
+                },
+                "add_technical_notes": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Technical notes to add",
+                },
+                "add_dependencies": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Dependencies to add",
+                },
+                "add_open_questions": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Open questions to add",
+                },
+                "resolve_questions": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Questions to mark as resolved",
+                },
+                "update_summary": {
+                    "type": "string",
+                    "description": "New summary text",
+                },
+            },
+            required=[],
+        )

emdash_core/agent/tools/task.py

@@ -0,0 +1,262 @@
+"""Task tool for spawning sub-agents.
+
+Follows Claude Code's Task tool pattern - spawns specialized sub-agents
+for focused tasks like exploration and planning.
+
+Uses in-process execution for better UX (real-time events) while
+maintaining isolated message histories per sub-agent.
+"""
+
+import uuid
+from pathlib import Path
+from typing import Optional
+
+from .base import BaseTool, ToolResult, ToolCategory
+from ..toolkits import list_agent_types
+from ..inprocess_subagent import run_subagent, run_subagent_async
+from ...utils.logger import log
+
+
+class TaskTool(BaseTool):
+    """Spawn a sub-agent to handle complex, multi-step tasks autonomously.
+
+    The Task tool launches specialized agents in-process with isolated
+    message histories. Each agent type has specific capabilities:
+
+    - **Explore**: Fast codebase exploration using read_file, glob, grep, semantic_search
+    - **Plan**: Design implementation plans, can write to .emdash/plans/*.md
+
+    Sub-agents run with their own context and tools, returning a summary when done.
+    Events are tagged with agent_id to prevent mixing in the UI.
+    """
+
+    name = "task"
+    description = """Launch a specialized sub-agent for focused tasks.
+
+Use this to spawn lightweight agents for:
+- Fast codebase exploration (Explore agent)
+- Implementation planning (Plan agent)
+
+Sub-agents run autonomously and return structured results.
+Multiple sub-agents can be launched in parallel."""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, repo_root: Path, connection=None, emitter=None):
+        """Initialize with repo root.
+
+        Args:
+            repo_root: Root directory of the repository
+            connection: Optional connection (not used)
+            emitter: Optional event emitter for progress events
+        """
+        self.repo_root = repo_root.resolve()
+        self.connection = connection
+        self.emitter = emitter
+
+    def execute(
+        self,
+        description: str = "",
+        prompt: str = "",
+        subagent_type: str = "Explore",
+        model_tier: str = "fast",
+        max_turns: int = 10,
+        run_in_background: bool = False,
+        resume: Optional[str] = None,
+        **kwargs,
+    ) -> ToolResult:
+        """Spawn a sub-agent to perform a task.
+
+        Args:
+            description: Short (3-5 word) description of the task
+            prompt: The task for the agent to perform
+            subagent_type: Type of agent (Explore, Plan)
+            model_tier: Model tier (fast, standard, powerful)
+            max_turns: Maximum API round-trips
+            run_in_background: Run asynchronously
+            resume: Agent ID to resume from
+
+        Returns:
+            ToolResult with agent results or background task info
+        """
+        # Validate inputs
+        if not prompt:
+            return ToolResult.error_result(
+                "Prompt is required",
+                suggestions=["Provide a clear task description in 'prompt'"],
+            )
+
+        available_types = list_agent_types()
+        if subagent_type not in available_types:
+            return ToolResult.error_result(
+                f"Unknown agent type: {subagent_type}",
+                suggestions=[f"Available types: {available_types}"],
+            )
+
+        log.info(
+            "Spawning sub-agent type={} model={} prompt={}",
+            subagent_type,
+            model_tier,
+            prompt[:50] + "..." if len(prompt) > 50 else prompt,
+        )
+
+        if run_in_background:
+            return self._run_background(subagent_type, prompt, max_turns)
+        else:
+            return self._run_sync(subagent_type, prompt, max_turns)
+
+    def _run_sync(
+        self,
+        subagent_type: str,
+        prompt: str,
+        max_turns: int,
+    ) -> ToolResult:
+        """Run sub-agent synchronously in the same process.
+
+        Args:
+            subagent_type: Agent type
+            prompt: Task prompt
+            max_turns: Maximum API round-trips
+
+        Returns:
+            ToolResult with agent results
+        """
+        try:
+            result = run_subagent(
+                subagent_type=subagent_type,
+                prompt=prompt,
+                repo_root=self.repo_root,
+                emitter=self.emitter,
+                max_turns=max_turns,
+            )
+
+            if result.success:
+                return ToolResult.success_result(
+                    data=result.to_dict(),
+                    suggestions=self._generate_suggestions(result.to_dict()),
+                )
+            else:
+                return ToolResult.error_result(
+                    f"Sub-agent failed: {result.error}",
+                    suggestions=["Check the prompt and try again"],
+                )
+
+        except Exception as e:
+            log.exception("Failed to run sub-agent")
+            return ToolResult.error_result(f"Failed to run sub-agent: {e}")
+
+    def _run_background(
+        self,
+        subagent_type: str,
+        prompt: str,
+        max_turns: int,
+    ) -> ToolResult:
+        """Run sub-agent in background using a thread.
+
+        Args:
+            subagent_type: Agent type
+            prompt: Task prompt
+            max_turns: Maximum API round-trips
+
+        Returns:
+            ToolResult with task info
+        """
+        agent_id = str(uuid.uuid4())[:8]
+
+        # Output file for results
+        output_dir = self.repo_root / ".emdash" / "agents"
+        output_dir.mkdir(parents=True, exist_ok=True)
+        output_file = output_dir / f"{agent_id}.output"
+
+        try:
+            # Start async execution
+            future = run_subagent_async(
+                subagent_type=subagent_type,
+                prompt=prompt,
+                repo_root=self.repo_root,
+                emitter=self.emitter,
+                max_turns=max_turns,
+            )
+
+            # Store future for later retrieval (attach to class for now)
+            if not hasattr(self, "_background_tasks"):
+                self._background_tasks = {}
+            self._background_tasks[agent_id] = {
+                "future": future,
+                "output_file": output_file,
+            }
+
+            log.info(f"Started background agent {agent_id}")
+
+            return ToolResult.success_result(
+                data={
+                    "agent_id": agent_id,
+                    "status": "running",
+                    "agent_type": subagent_type,
+                    "output_file": str(output_file),
+                },
+                suggestions=[
+                    f"Use task_output(agent_id='{agent_id}') to check results",
+                ],
+            )
+
+        except Exception as e:
+            log.exception("Failed to start background agent")
+            return ToolResult.error_result(f"Failed to start background agent: {e}")
+
+    def _generate_suggestions(self, data: dict) -> list[str]:
+        """Generate follow-up suggestions based on results."""
+        suggestions = []
+
+        files = data.get("files_explored", [])
+        if files:
+            suggestions.append(f"Found {len(files)} relevant files")
+
+        if data.get("agent_type") == "Plan":
+            suggestions.append("Review the plan in .emdash/plans/")
+
+        if data.get("agent_id"):
+            suggestions.append(f"Agent ID: {data['agent_id']} (can resume later)")
+
+        return suggestions
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(
+            properties={
+                "description": {
+                    "type": "string",
+                    "description": "Short (3-5 word) description of the task",
+                },
+                "prompt": {
+                    "type": "string",
+                    "description": "The task for the agent to perform",
+                },
+                "subagent_type": {
+                    "type": "string",
+                    "enum": ["Explore", "Plan"],
+                    "description": "Type of specialized agent",
+                    "default": "Explore",
+                },
+                "model_tier": {
+                    "type": "string",
+                    "enum": ["fast", "model"],
+                    "description": "Model tier (fast=cheap/quick, model=standard)",
+                    "default": "fast",
+                },
+                "max_turns": {
+                    "type": "integer",
+                    "description": "Maximum API round-trips",
+                    "default": 10,
+                },
+                "run_in_background": {
+                    "type": "boolean",
+                    "description": "Run agent asynchronously",
+                    "default": False,
+                },
+                "resume": {
+                    "type": "string",
+                    "description": "Agent ID to resume from previous execution",
+                },
+            },
+            required=["prompt"],
+        )