codeframe-ai 0.9.0__py3-none-any.whl

codeframe/core/executor.py

@@ -0,0 +1,1005 @@
+"""Code execution engine for CodeFRAME v2.
+
+Executes implementation plan steps by generating and applying code changes.
+Handles file operations, shell commands, and tracks changes for rollback.
+
+This module is headless - no FastAPI or HTTP dependencies.
+"""
+
+import asyncio
+import re
+import shlex
+import subprocess
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING
+
+from codeframe.core.planner import PlanStep, StepType, ImplementationPlan
+from codeframe.core.context import TaskContext
+from codeframe.adapters.llm import LLMProvider, Purpose
+
+if TYPE_CHECKING:
+    from codeframe.core.streaming import EventPublisher
+
+
+# Module-level dangerous command patterns (importable by other modules like tools.py)
+DANGEROUS_PATTERNS: list[tuple[str, str]] = [
+    # Recursive delete of root or home
+    (r"\brm\s+(-[rf]+\s+)*[/~]", "recursive deletion of root or home"),
+    (r"\brm\s+--no-preserve-root", "rm with --no-preserve-root"),
+    # Writing to /dev/ devices
+    (r">\s*/dev/", "redirect to /dev device"),
+    (r"\bdd\s+.*of=/dev/", "dd writing to device"),
+    # Filesystem destruction
+    (r"\bmkfs\b", "filesystem format command"),
+    (r"\bfdisk\b", "disk partition command"),
+    # Fork bombs
+    (r":\s*\(\s*\)\s*\{", "potential fork bomb"),
+    (r"\bfork\s*while\s*true", "potential fork bomb"),
+    # Dangerous dd operations
+    (r"\bdd\s+if=/dev/", "dd reading from device"),
+    # Dangerous chmod
+    (r"\bchmod\s+(-[Rr]\s+)?777\s+/", "chmod 777 on root"),
+    # Wget/curl piped to shell (potential malware download)
+    (r"\b(wget|curl)\s+.*\|\s*(ba)?sh", "download piped to shell"),
+    # Overwriting important system files
+    (r">\s*/(etc|bin|usr|lib|sbin)/", "overwriting system directory"),
+]
+
+
+def is_dangerous_command(command: str) -> tuple[bool, str]:
+    """Check if a command matches dangerous patterns.
+
+    Uses regex-based patterns that are harder to bypass than substring matching.
+    Normalizes whitespace and handles common shell escapes.
+
+    Args:
+        command: The shell command to check
+
+    Returns:
+        Tuple of (is_dangerous, description) where description explains the match
+    """
+    # Normalize the command for comparison
+    try:
+        # Use shlex to handle escapes, then rejoin
+        tokens = shlex.split(command)
+        normalized = " ".join(tokens)
+    except ValueError:
+        # If shlex fails, use the original with normalized whitespace
+        normalized = " ".join(command.split())
+
+    for pattern, description in DANGEROUS_PATTERNS:
+        if re.search(pattern, normalized, re.IGNORECASE):
+            return (True, description)
+        # Also check original command in case normalization removed something
+        if re.search(pattern, command, re.IGNORECASE):
+            return (True, description)
+
+    return (False, "")
+
+
+class ExecutionStatus(str, Enum):
+    """Status of a step execution."""
+
+    SUCCESS = "success"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class FileChange:
+    """Record of a file change for rollback.
+
+    Attributes:
+        path: Path to the file
+        operation: Type of operation (create, edit, delete)
+        original_content: Original content (None for new files)
+        new_content: New content after change
+        timestamp: When the change was made
+    """
+
+    path: str
+    operation: str
+    original_content: Optional[str]
+    new_content: Optional[str]
+    timestamp: datetime
+
+
+@dataclass
+class StepResult:
+    """Result of executing a single step.
+
+    Attributes:
+        step: The step that was executed
+        status: Execution status
+        output: Output or result message
+        error: Error message if failed
+        file_changes: Files modified by this step
+        duration_ms: Execution time in milliseconds
+    """
+
+    step: PlanStep
+    status: ExecutionStatus
+    output: str = ""
+    error: str = ""
+    file_changes: list[FileChange] = field(default_factory=list)
+    duration_ms: int = 0
+
+
+@dataclass
+class ExecutionResult:
+    """Result of executing an entire plan.
+
+    Attributes:
+        plan: The plan that was executed
+        step_results: Results for each step
+        success: Whether all steps succeeded
+        total_duration_ms: Total execution time
+    """
+
+    plan: ImplementationPlan
+    step_results: list[StepResult]
+    success: bool = True
+    total_duration_ms: int = 0
+
+    @property
+    def failed_steps(self) -> list[StepResult]:
+        """Get steps that failed."""
+        return [r for r in self.step_results if r.status == ExecutionStatus.FAILED]
+
+    @property
+    def file_changes(self) -> list[FileChange]:
+        """Get all file changes across all steps."""
+        changes = []
+        for result in self.step_results:
+            changes.extend(result.file_changes)
+        return changes
+
+
+# System prompt for code generation
+CODE_GENERATION_PROMPT = """You are an expert code generator. Generate clean, well-structured code based on the requirements.
+
+## Decision-Making Autonomy
+
+When you encounter a decision point:
+1. Check project preferences (if provided in context) first
+2. If no preference, use industry best practices
+3. If truly ambiguous, pick the simpler approach
+4. NEVER stop or ask for trivial tactical decisions
+
+You MUST make decisions autonomously about:
+- Import organization and ordering
+- Variable and function naming (following existing patterns)
+- Error handling strategies
+- Code organization within files
+- Choice between equivalent implementations
+
+## Code Guidelines
+
+1. Follow the existing code style in the project
+2. Include appropriate error handling
+3. Add brief comments for complex logic only
+4. Use type hints for Python code
+5. Keep code focused and minimal - don't over-engineer
+6. If a file exists, build on existing patterns
+7. Use existing imports and utilities where appropriate
+
+Return ONLY the code, no explanations or markdown formatting."""
+
+EDIT_GENERATION_PROMPT = """You are an expert code editor. Given the current file content and requested changes, generate the updated file content.
+
+## Decision-Making Autonomy
+
+When you encounter a decision point:
+1. Check project preferences (if provided in context) first
+2. If no preference, follow existing patterns in the file
+3. If truly ambiguous, pick the approach that minimizes changes
+4. NEVER stop or ask for trivial tactical decisions
+
+You MUST make decisions autonomously about:
+- Where to insert new code
+- How to integrate changes with existing code
+- Import organization
+- Minor refactoring needed for integration
+
+## Edit Guidelines
+
+1. Preserve the existing code style and formatting
+2. Make minimal changes to achieve the goal
+3. Don't change unrelated code
+4. Maintain all imports and dependencies
+5. If adding new functionality, integrate naturally with existing code
+6. Fix any linting issues in the modified sections
+
+Return ONLY the complete updated file content, no explanations or markdown formatting."""
+
+
+class Executor:
+    """Executes implementation plan steps.
+
+    Handles file operations, shell commands, and LLM-driven code generation.
+    Tracks all changes for potential rollback.
+    """
+
+    def __init__(
+        self,
+        llm_provider: LLMProvider,
+        repo_path: Path,
+        dry_run: bool = False,
+        command_timeout: int = 60,
+        event_publisher: Optional["EventPublisher"] = None,
+    ):
+        """Initialize the executor.
+
+        Args:
+            llm_provider: LLM provider for code generation
+            repo_path: Root path of the repository
+            dry_run: If True, don't actually make changes
+            command_timeout: Timeout for shell commands in seconds
+            event_publisher: Optional EventPublisher for streaming execution events
+        """
+        self.llm = llm_provider
+        self.repo_path = Path(repo_path)
+        self.dry_run = dry_run
+        self.command_timeout = command_timeout
+        self.changes: list[FileChange] = []
+        self.event_publisher = event_publisher
+
+    def execute_plan(
+        self,
+        plan: ImplementationPlan,
+        context: TaskContext,
+    ) -> ExecutionResult:
+        """Execute all steps in a plan.
+
+        Args:
+            plan: Plan to execute
+            context: Task context for code generation
+
+        Returns:
+            ExecutionResult with all step results
+        """
+        results = []
+        success = True
+        start_time = datetime.now(timezone.utc)
+
+        for step in plan.steps:
+            # Check dependencies
+            if not self._dependencies_satisfied(step, results):
+                results.append(StepResult(
+                    step=step,
+                    status=ExecutionStatus.SKIPPED,
+                    output="Dependencies not satisfied",
+                ))
+                continue
+
+            # Execute the step
+            result = self.execute_step(step, context)
+            results.append(result)
+
+            if result.status == ExecutionStatus.FAILED:
+                success = False
+                break  # Stop on first failure
+
+        end_time = datetime.now(timezone.utc)
+        duration = int((end_time - start_time).total_seconds() * 1000)
+
+        return ExecutionResult(
+            plan=plan,
+            step_results=results,
+            success=success,
+            total_duration_ms=duration,
+        )
+
+    def execute_step(
+        self,
+        step: PlanStep,
+        context: TaskContext,
+    ) -> StepResult:
+        """Execute a single plan step.
+
+        Args:
+            step: Step to execute
+            context: Task context for code generation
+
+        Returns:
+            StepResult with execution outcome
+        """
+        start_time = datetime.now(timezone.utc)
+
+        try:
+            if step.type == StepType.FILE_CREATE:
+                result = self._execute_file_create(step, context)
+            elif step.type == StepType.FILE_EDIT:
+                result = self._execute_file_edit(step, context)
+            elif step.type == StepType.FILE_DELETE:
+                result = self._execute_file_delete(step)
+            elif step.type == StepType.SHELL_COMMAND:
+                result = self._execute_shell_command(step)
+            elif step.type == StepType.VERIFICATION:
+                result = self._execute_verification(step)
+            else:
+                result = StepResult(
+                    step=step,
+                    status=ExecutionStatus.FAILED,
+                    error=f"Unknown step type: {step.type}",
+                )
+        except Exception as e:
+            result = StepResult(
+                step=step,
+                status=ExecutionStatus.FAILED,
+                error=str(e),
+            )
+
+        end_time = datetime.now(timezone.utc)
+        result.duration_ms = int((end_time - start_time).total_seconds() * 1000)
+
+        return result
+
+    def _execute_file_create(
+        self,
+        step: PlanStep,
+        context: TaskContext,
+    ) -> StepResult:
+        """Create a new file with generated content.
+
+        If the file already exists, falls back gracefully:
+        - Identical content: returns SUCCESS (no-op)
+        - Different content: falls back to edit behavior
+        """
+        file_path = self.repo_path / step.target
+
+        # Check if file already exists -- fall back gracefully
+        if file_path.exists():
+            existing_content = file_path.read_text(encoding="utf-8")
+
+            # Generate content using edit prompt so LLM sees existing content
+            new_content = self._generate_edit_content(step, context, existing_content)
+
+            # If content is identical, no-op success
+            if existing_content.strip() == new_content.strip():
+                return StepResult(
+                    step=step,
+                    status=ExecutionStatus.SUCCESS,
+                    output=f"File already exists with correct content: {step.target}",
+                )
+
+            # Content differs -- fall back to edit behavior
+            if self.dry_run:
+                return StepResult(
+                    step=step,
+                    status=ExecutionStatus.SUCCESS,
+                    output=f"[DRY RUN] Would edit existing file: {step.target}",
+                )
+
+            file_path.write_text(new_content, encoding="utf-8")
+
+            change = FileChange(
+                path=step.target,
+                operation="edit",
+                original_content=existing_content,
+                new_content=new_content,
+                timestamp=datetime.now(timezone.utc),
+            )
+            self.changes.append(change)
+
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.SUCCESS,
+                output=f"Updated existing file: {step.target}",
+                file_changes=[change],
+            )
+
+        # Generate file content using LLM
+        content = self._generate_file_content(step, context)
+
+        if self.dry_run:
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.SUCCESS,
+                output=f"[DRY RUN] Would create: {step.target}",
+            )
+
+        # Create parent directories
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write the file
+        file_path.write_text(content, encoding="utf-8")
+
+        # Record the change
+        change = FileChange(
+            path=step.target,
+            operation="create",
+            original_content=None,
+            new_content=content,
+            timestamp=datetime.now(timezone.utc),
+        )
+        self.changes.append(change)
+
+        return StepResult(
+            step=step,
+            status=ExecutionStatus.SUCCESS,
+            output=f"Created: {step.target}",
+            file_changes=[change],
+        )
+
+    def _execute_file_edit(
+        self,
+        step: PlanStep,
+        context: TaskContext,
+    ) -> StepResult:
+        """Edit an existing file."""
+        file_path = self.repo_path / step.target
+
+        # Check if file exists
+        if not file_path.exists():
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.FAILED,
+                error=f"File not found: {step.target}",
+            )
+
+        # Read current content
+        original_content = file_path.read_text(encoding="utf-8")
+
+        # Generate edited content using LLM
+        new_content = self._generate_edit_content(step, context, original_content)
+
+        if self.dry_run:
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.SUCCESS,
+                output=f"[DRY RUN] Would edit: {step.target}",
+            )
+
+        # Write the updated content
+        file_path.write_text(new_content, encoding="utf-8")
+
+        # Record the change
+        change = FileChange(
+            path=step.target,
+            operation="edit",
+            original_content=original_content,
+            new_content=new_content,
+            timestamp=datetime.now(timezone.utc),
+        )
+        self.changes.append(change)
+
+        return StepResult(
+            step=step,
+            status=ExecutionStatus.SUCCESS,
+            output=f"Edited: {step.target}",
+            file_changes=[change],
+        )
+
+    def _execute_file_delete(self, step: PlanStep) -> StepResult:
+        """Delete a file."""
+        file_path = self.repo_path / step.target
+
+        if not file_path.exists():
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.SUCCESS,
+                output=f"File already deleted: {step.target}",
+            )
+
+        original_content = file_path.read_text(encoding="utf-8")
+
+        if self.dry_run:
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.SUCCESS,
+                output=f"[DRY RUN] Would delete: {step.target}",
+            )
+
+        # Delete the file
+        file_path.unlink()
+
+        # Record the change
+        change = FileChange(
+            path=step.target,
+            operation="delete",
+            original_content=original_content,
+            new_content=None,
+            timestamp=datetime.now(timezone.utc),
+        )
+        self.changes.append(change)
+
+        return StepResult(
+            step=step,
+            status=ExecutionStatus.SUCCESS,
+            output=f"Deleted: {step.target}",
+            file_changes=[change],
+        )
+
+    def _is_dangerous_command(self, command: str) -> tuple[bool, str]:
+        """Check if a command matches dangerous patterns.
+
+        Delegates to the module-level is_dangerous_command() function.
+        """
+        return is_dangerous_command(command)
+
+    def _execute_shell_command(self, step: PlanStep) -> StepResult:
+        """Execute a shell command."""
+        command = step.target
+
+        # Check for dangerous command patterns using regex
+        is_dangerous, description = self._is_dangerous_command(command)
+        if is_dangerous:
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.FAILED,
+                error=f"Blocked dangerous command: {description}",
+            )
+
+        if self.dry_run:
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.SUCCESS,
+                output=f"[DRY RUN] Would run: {command}",
+            )
+
+        # Detect shell operators to determine execution mode
+        shell_operators = ['|', '&&', '||', '>', '<', '>>', '<<', ';', '`', '$(']
+        requires_shell = any(op in command for op in shell_operators)
+
+        try:
+            if requires_shell:
+                # Command contains shell operators, must use shell=True
+                result = subprocess.run(
+                    command,
+                    shell=True,
+                    cwd=self.repo_path,
+                    capture_output=True,
+                    text=True,
+                    timeout=self.command_timeout,
+                )
+            else:
+                # Safe to use shell=False with parsed arguments
+                try:
+                    argv = shlex.split(command)
+                    result = subprocess.run(
+                        argv,
+                        shell=False,
+                        cwd=self.repo_path,
+                        capture_output=True,
+                        text=True,
+                        timeout=self.command_timeout,
+                    )
+                except ValueError:
+                    # shlex.split failed (malformed command), fall back to shell=True
+                    result = subprocess.run(
+                        command,
+                        shell=True,
+                        cwd=self.repo_path,
+                        capture_output=True,
+                        text=True,
+                        timeout=self.command_timeout,
+                    )
+
+            if result.returncode == 0:
+                return StepResult(
+                    step=step,
+                    status=ExecutionStatus.SUCCESS,
+                    output=result.stdout[:2000] if result.stdout else "Command completed",
+                )
+            else:
+                return StepResult(
+                    step=step,
+                    status=ExecutionStatus.FAILED,
+                    output=result.stdout[:1000] if result.stdout else "",
+                    error=result.stderr[:1000] if result.stderr else f"Exit code: {result.returncode}",
+                )
+
+        except subprocess.TimeoutExpired:
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.FAILED,
+                error=f"Command timed out after {self.command_timeout}s",
+            )
+
+    def _execute_verification(self, step: PlanStep) -> StepResult:
+        """Execute a verification step (tests, linting, file checks).
+
+        Handles different verification scenarios:
+        - If target is a .py file: verify it exists and has valid syntax
+        - If target looks like a command: run it as shell command
+        - Otherwise: check if target file/path exists
+        """
+        target = step.target
+
+        # Check for common planner mistakes - these are step types, not valid targets
+        invalid_targets = ("shell_command", "file_edit", "file_create", "verification")
+        if target in invalid_targets:
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.FAILED,
+                error=(
+                    f"Invalid verification target '{target}'. "
+                    f"The target should be a command to run (e.g., 'python script.py --help') "
+                    f"or a file path to verify, not the step type name."
+                ),
+            )
+
+        # If target is a Python file, verify it exists and check syntax
+        if target.endswith(".py"):
+            file_path = self.repo_path / target
+            if not file_path.exists():
+                return StepResult(
+                    step=step,
+                    status=ExecutionStatus.FAILED,
+                    error=f"File not found: {target}",
+                )
+
+            # Verify Python syntax
+            try:
+                import ast
+                content = file_path.read_text()
+                ast.parse(content)
+                return StepResult(
+                    step=step,
+                    status=ExecutionStatus.SUCCESS,
+                    output=f"Verified: {target} exists and has valid Python syntax",
+                )
+            except SyntaxError as e:
+                return StepResult(
+                    step=step,
+                    status=ExecutionStatus.FAILED,
+                    error=f"Syntax error in {target}: {e}",
+                )
+
+        # If target looks like a command (contains spaces or starts with known commands)
+        command_prefixes = ("python", "pytest", "ruff", "npm", "make", "bash", "sh")
+        if " " in target or target.split()[0] in command_prefixes:
+            return self._execute_shell_command(step)
+
+        # Otherwise just check if the path exists
+        target_path = self.repo_path / target
+        if target_path.exists():
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.SUCCESS,
+                output=f"Verified: {target} exists",
+            )
+        else:
+            return StepResult(
+                step=step,
+                status=ExecutionStatus.FAILED,
+                error=f"Path not found: {target}",
+            )
+
+    def _generate_file_content(
+        self,
+        step: PlanStep,
+        context: TaskContext,
+    ) -> str:
+        """Generate content for a new file using LLM."""
+        prompt = self._build_generation_prompt(step, context)
+
+        response = self.llm.complete(
+            messages=[{"role": "user", "content": prompt}],
+            purpose=Purpose.EXECUTION,
+            system=CODE_GENERATION_PROMPT,
+            max_tokens=4096,
+            temperature=0.0,
+        )
+
+        # Clean up response - remove markdown code blocks if present
+        content = response.content.strip()
+        if content.startswith("```"):
+            lines = content.split("\n")
+            # Remove first and last lines (``` markers)
+            if lines[0].startswith("```"):
+                lines = lines[1:]
+            if lines and lines[-1].strip() == "```":
+                lines = lines[:-1]
+            content = "\n".join(lines)
+
+        return content
+
+    def _generate_edit_content(
+        self,
+        step: PlanStep,
+        context: TaskContext,
+        original_content: str,
+    ) -> str:
+        """Generate edited file content using LLM."""
+        prompt = self._build_edit_prompt(step, context, original_content)
+
+        response = self.llm.complete(
+            messages=[{"role": "user", "content": prompt}],
+            purpose=Purpose.EXECUTION,
+            system=EDIT_GENERATION_PROMPT,
+            max_tokens=8192,
+            temperature=0.0,
+        )
+
+        # Clean up response
+        content = response.content.strip()
+        if content.startswith("```"):
+            lines = content.split("\n")
+            if lines[0].startswith("```"):
+                lines = lines[1:]
+            if lines and lines[-1].strip() == "```":
+                lines = lines[:-1]
+            content = "\n".join(lines)
+
+        return content
+
+    def _build_generation_prompt(
+        self,
+        step: PlanStep,
+        context: TaskContext,
+    ) -> str:
+        """Build prompt for file generation."""
+        sections = [
+            f"## Task: {context.task.title}",
+            f"## File to Create: {step.target}",
+            f"## Purpose: {step.description}",
+        ]
+
+        if step.details:
+            sections.append(f"## Details: {step.details}")
+
+        if context.prd:
+            sections.append(f"## Requirements:\n{context.prd.content[:2000]}")
+
+        # Include relevant existing files for context
+        if context.loaded_files:
+            sections.append("## Related Files:")
+            for f in context.loaded_files[:3]:
+                sections.append(f"### {f.path}")
+                sections.append(f"```\n{f.content[:1500]}\n```")
+
+        sections.append("\nGenerate the file content:")
+
+        return "\n\n".join(sections)
+
+    def _build_edit_prompt(
+        self,
+        step: PlanStep,
+        context: TaskContext,
+        original_content: str,
+    ) -> str:
+        """Build prompt for file editing."""
+        sections = [
+            f"## Task: {context.task.title}",
+            f"## File to Edit: {step.target}",
+            f"## Change Required: {step.description}",
+        ]
+
+        if step.details:
+            sections.append(f"## Details: {step.details}")
+
+        sections.append(f"## Current File Content:\n```\n{original_content[:6000]}\n```")
+
+        sections.append("\nGenerate the complete updated file content:")
+
+        return "\n\n".join(sections)
+
+    def _dependencies_satisfied(
+        self,
+        step: PlanStep,
+        previous_results: list[StepResult],
+    ) -> bool:
+        """Check if a step's dependencies are satisfied."""
+        if not step.depends_on:
+            return True
+
+        for dep_index in step.depends_on:
+            # Find the result for this dependency
+            dep_result = None
+            for result in previous_results:
+                if result.step.index == dep_index:
+                    dep_result = result
+                    break
+
+            if dep_result is None:
+                return False  # Dependency not executed yet
+
+            if dep_result.status != ExecutionStatus.SUCCESS:
+                return False  # Dependency failed
+
+        return True
+
+    def rollback(self) -> list[str]:
+        """Rollback all changes made by this executor.
+
+        Returns:
+            List of files that were rolled back
+        """
+        rolled_back = []
+
+        # Process changes in reverse order
+        for change in reversed(self.changes):
+            file_path = self.repo_path / change.path
+
+            try:
+                if change.operation == "create":
+                    # Delete the created file
+                    if file_path.exists():
+                        file_path.unlink()
+                        rolled_back.append(f"Deleted: {change.path}")
+
+                elif change.operation == "edit":
+                    # Restore original content
+                    if change.original_content is not None:
+                        file_path.write_text(change.original_content, encoding="utf-8")
+                        rolled_back.append(f"Restored: {change.path}")
+
+                elif change.operation == "delete":
+                    # Recreate the deleted file
+                    if change.original_content is not None:
+                        file_path.parent.mkdir(parents=True, exist_ok=True)
+                        file_path.write_text(change.original_content, encoding="utf-8")
+                        rolled_back.append(f"Recreated: {change.path}")
+
+            except Exception as e:
+                rolled_back.append(f"Failed to rollback {change.path}: {e}")
+
+        self.changes.clear()
+        return rolled_back
+
+    # ========================================================================
+    # Async Methods with Event Publishing
+    # ========================================================================
+
+    async def _publish_event(self, task_id: str, event) -> None:
+        """Publish an event if publisher is configured.
+
+        Args:
+            task_id: Task ID for the event
+            event: Event to publish
+        """
+        if self.event_publisher is not None:
+            await self.event_publisher.publish(task_id, event)
+
+    async def execute_step_async(
+        self,
+        step: PlanStep,
+        context: TaskContext,
+        task_id: str,
+    ) -> StepResult:
+        """Execute a single plan step asynchronously with event publishing.
+
+        Args:
+            step: Step to execute
+            context: Task context for code generation
+            task_id: Task ID for event publishing
+
+        Returns:
+            StepResult with execution outcome
+        """
+        from codeframe.core.models import OutputEvent, ErrorEvent
+
+        # Note: ProgressEvent is emitted by execute_plan_async() before calling this method,
+        # so we don't emit one here to avoid duplicates with incorrect total_steps
+
+        # Execute the step (sync operation, run in thread pool)
+        loop = asyncio.get_running_loop()
+        result = await loop.run_in_executor(
+            None,
+            lambda: self.execute_step(step, context),
+        )
+
+        # Publish output event for successful commands
+        if result.status == ExecutionStatus.SUCCESS and result.output:
+            from codeframe.core.streaming import SSE_OUTPUT_MAX_CHARS
+
+            output = result.output
+            truncated = len(output) > SSE_OUTPUT_MAX_CHARS
+            if truncated:
+                output = output[:SSE_OUTPUT_MAX_CHARS] + f"\n... (truncated, {len(result.output)} total chars)"
+
+            await self._publish_event(
+                task_id,
+                OutputEvent(
+                    task_id=task_id,
+                    stream="stdout",
+                    line=output,
+                ),
+            )
+
+        # Publish error event for failures
+        if result.status == ExecutionStatus.FAILED:
+            await self._publish_event(
+                task_id,
+                ErrorEvent(
+                    task_id=task_id,
+                    error_type="step_failed",
+                    error=result.error or f"Step {step.index} execution failed",
+                ),
+            )
+
+        return result
+
+    async def execute_plan_async(
+        self,
+        plan: ImplementationPlan,
+        context: TaskContext,
+    ) -> ExecutionResult:
+        """Execute all steps in a plan asynchronously with event publishing.
+
+        Args:
+            plan: Plan to execute
+            context: Task context for code generation
+
+        Returns:
+            ExecutionResult with all step results
+        """
+        from codeframe.core.models import ProgressEvent, CompletionEvent, ErrorEvent
+
+        task_id = plan.task_id
+        results = []
+        success = True
+        start_time = datetime.now(timezone.utc)
+        total_steps = len(plan.steps)
+
+        for i, step in enumerate(plan.steps, 1):
+            # Publish progress for each step
+            await self._publish_event(
+                task_id,
+                ProgressEvent(
+                    task_id=task_id,
+                    phase="execution",
+                    step=i,
+                    total_steps=total_steps,
+                    message=f"Step {i}/{total_steps}: {step.description}",
+                ),
+            )
+
+            # Check dependencies
+            if not self._dependencies_satisfied(step, results):
+                results.append(StepResult(
+                    step=step,
+                    status=ExecutionStatus.SKIPPED,
+                    output="Dependencies not satisfied",
+                ))
+                continue
+
+            # Execute the step
+            result = await self.execute_step_async(step, context, task_id)
+            results.append(result)
+
+            if result.status == ExecutionStatus.FAILED:
+                success = False
+                break  # Stop on first failure
+
+        end_time = datetime.now(timezone.utc)
+        duration_seconds = (end_time - start_time).total_seconds()
+        duration_ms = int(duration_seconds * 1000)
+
+        # Publish completion event
+        files_modified = [c.path for c in self.changes]
+        if success:
+            await self._publish_event(
+                task_id,
+                CompletionEvent(
+                    task_id=task_id,
+                    status="completed",
+                    duration_seconds=duration_seconds,
+                    files_modified=files_modified,
+                ),
+            )
+        else:
+            failed_step = results[-1] if results else None
+            error_msg = failed_step.error if failed_step else "Plan execution failed"
+            if failed_step:
+                error_msg = f"Step {failed_step.step.index} failed: {error_msg}"
+            await self._publish_event(
+                task_id,
+                ErrorEvent(
+                    task_id=task_id,
+                    error_type="plan_failed",
+                    error=error_msg,
+                ),
+            )
+
+        return ExecutionResult(
+            plan=plan,
+            step_results=results,
+            success=success,
+            total_duration_ms=duration_ms,
+        )