code-puppy 0.0.374__py3-none-any.whl → 0.0.376__py3-none-any.whl

code_puppy/plugins/ralph/loop_controller.py

@@ -0,0 +1,289 @@
+"""Ralph Loop Controller - Manages the autonomous iteration loop.
+
+This is the "outer loop" that spawns fresh agent instances per iteration,
+just like the original ralph.sh bash script does.
+"""
+
+import asyncio
+import logging
+from typing import Awaitable, Callable, Optional
+
+from code_puppy.messaging import emit_error, emit_info, emit_success, emit_warning
+
+from .state_manager import get_state_manager
+
+logger = logging.getLogger(__name__)
+
+
+class RalphLoopController:
+    """Controls the Ralph autonomous loop.
+
+    Each iteration:
+    1. Checks if there's work to do
+    2. Invokes the ralph-orchestrator agent with a FRESH session
+    3. Waits for completion
+    4. Checks if all stories are done or if we should continue
+    """
+
+    def __init__(self, max_iterations: int = 10):
+        self.max_iterations = max_iterations
+        self.current_iteration = 0
+        self.is_complete = False
+        self.is_running = False
+        self._stop_requested = False
+
+    def request_stop(self) -> None:
+        """Request the loop to stop after current iteration."""
+        self._stop_requested = True
+        emit_warning("🛑 Stop requested - will halt after current iteration")
+
+    async def run(
+        self,
+        invoke_func: Callable[[str, str, Optional[str]], Awaitable[dict]],
+    ) -> dict:
+        """Run the Ralph loop until completion or max iterations.
+
+        Args:
+            invoke_func: Async function to invoke an agent.
+                        Signature: (agent_name, prompt, session_id) -> result_dict
+                        The result_dict should have 'response' and 'error' keys.
+
+        Returns:
+            dict with 'success', 'iterations', 'message' keys
+        """
+        self.is_running = True
+        self.is_complete = False
+        self._stop_requested = False
+
+        manager = get_state_manager()
+
+        # Pre-flight checks
+        if not manager.prd_exists():
+            self.is_running = False
+            return {
+                "success": False,
+                "iterations": 0,
+                "message": "No prd.json found. Create one with /ralph prd first.",
+            }
+
+        if manager.all_stories_complete():
+            self.is_running = False
+            return {
+                "success": True,
+                "iterations": 0,
+                "message": "All stories already complete!",
+            }
+
+        prd = manager.read_prd()
+        emit_info("🐺 Starting Ralph Loop")
+        emit_info(f"📋 Project: {prd.project if prd else 'Unknown'}")
+        emit_info(f"📊 Progress: {prd.get_progress_summary() if prd else 'Unknown'}")
+        emit_info(f"🔄 Max iterations: {self.max_iterations}")
+        emit_info("─" * 50)
+
+        try:
+            for iteration in range(1, self.max_iterations + 1):
+                self.current_iteration = iteration
+
+                # Check for stop request
+                if self._stop_requested:
+                    emit_warning(f"🛑 Stopped at iteration {iteration}")
+                    break
+
+                # Check if already complete
+                if manager.all_stories_complete():
+                    self.is_complete = True
+                    emit_success("🎉 All stories complete!")
+                    break
+
+                # Get current story for logging
+                story = manager.get_next_story()
+                if story is None:
+                    self.is_complete = True
+                    emit_success("🎉 All stories complete!")
+                    break
+
+                emit_info(f"\n{'=' * 60}")
+                emit_info(f"🐺 RALPH ITERATION {iteration} of {self.max_iterations}")
+                emit_info(f"📌 Working on: [{story.id}] {story.title}")
+                emit_info(f"{'=' * 60}\n")
+
+                # Build the prompt for this iteration
+                iteration_prompt = self._build_iteration_prompt(story)
+
+                # Invoke orchestrator with FRESH session (unique per iteration)
+                session_id = f"ralph-iter-{iteration}"
+
+                try:
+                    result = await invoke_func(
+                        "ralph-orchestrator",
+                        iteration_prompt,
+                        session_id,
+                    )
+
+                    response = result.get("response", "")
+                    error = result.get("error")
+
+                    if error:
+                        emit_error(f"Iteration {iteration} error: {error}")
+                        # Continue to next iteration despite error
+                        continue
+
+                    # Check for completion signal in response
+                    if response and "<promise>COMPLETE</promise>" in response:
+                        self.is_complete = True
+                        emit_success("🎉 Ralph signaled COMPLETE - all stories done!")
+                        break
+
+                except asyncio.CancelledError:
+                    emit_warning(f"🛑 Iteration {iteration} cancelled")
+                    break
+                except Exception as e:
+                    emit_error(f"Iteration {iteration} failed: {e}")
+                    logger.exception(f"Ralph iteration {iteration} failed")
+                    # Continue to next iteration
+                    continue
+
+                # Brief pause between iterations
+                await asyncio.sleep(1)
+
+            else:
+                # Loop completed without break (max iterations reached)
+                emit_warning(f"⚠️ Reached max iterations ({self.max_iterations})")
+
+        finally:
+            self.is_running = False
+
+        # Final status
+        prd = manager.read_prd()
+        final_progress = prd.get_progress_summary() if prd else "Unknown"
+
+        return {
+            "success": self.is_complete,
+            "iterations": self.current_iteration,
+            "message": f"Completed {self.current_iteration} iterations. {final_progress}",
+            "all_complete": self.is_complete,
+        }
+
+    def _build_iteration_prompt(self, story) -> str:
+        """Build the prompt for a single iteration."""
+        # Find VERIFY criteria
+        verify_criteria = [
+            c for c in story.acceptance_criteria if c.startswith("VERIFY:")
+        ]
+        other_criteria = [
+            c for c in story.acceptance_criteria if not c.startswith("VERIFY:")
+        ]
+
+        verify_section = ""
+        if verify_criteria:
+            verify_section = f"""
+## MANDATORY VERIFICATION COMMANDS
+You MUST run these commands and they MUST succeed before marking complete:
+{chr(10).join(f"  {c}" for c in verify_criteria)}
+
+If ANY verification fails, fix the code and re-run until it passes!
+"""
+
+        return f"""Execute ONE iteration of the Ralph loop.
+
+## Current Story
+- **ID:** {story.id}
+- **Title:** {story.title}
+- **Description:** {story.description}
+
+## Acceptance Criteria (implement ALL of these):
+{chr(10).join(f"  - {c}" for c in other_criteria)}
+{verify_section}
+## Requires UI Verification: {story.has_ui_verification()}
+{"If yes, invoke qa-kitten to verify UI changes work correctly." if story.has_ui_verification() else ""}
+
+## Your Task
+
+1. Call `ralph_read_patterns()` to get context from previous iterations
+2. Implement this ONE story completely
+3. **RUN ALL VERIFY COMMANDS** - they must pass!
+4. If checks pass, commit with: `git commit -m "feat: {story.id} - {story.title}"`
+5. Call `ralph_mark_story_complete("{story.id}", "Verified: <what you tested>")`
+6. Call `ralph_log_progress(...)` with what you learned
+7. Call `ralph_check_all_complete()` to see if we're done
+
+If ALL stories are complete, output: <promise>COMPLETE</promise>
+
+⚠️ DO NOT mark complete until verification passes! Actually run the VERIFY commands!
+"""
+
+
+# Global controller instance
+_controller: Optional[RalphLoopController] = None
+
+
+def get_loop_controller(max_iterations: int = 10) -> RalphLoopController:
+    """Get or create the loop controller."""
+    global _controller
+    if _controller is None or not _controller.is_running:
+        _controller = RalphLoopController(max_iterations)
+    return _controller
+
+
+async def run_ralph_loop(
+    max_iterations: int = 10,
+    invoke_func: Optional[Callable] = None,
+) -> dict:
+    """Convenience function to run the Ralph loop.
+
+    Args:
+        max_iterations: Maximum number of iterations
+        invoke_func: Function to invoke agents. If None, uses default.
+
+    Returns:
+        Result dict from the controller
+    """
+    if invoke_func is None:
+        # Use the default agent invocation mechanism
+        invoke_func = _default_invoke_agent
+
+    controller = get_loop_controller(max_iterations)
+    return await controller.run(invoke_func)
+
+
+async def _default_invoke_agent(
+    agent_name: str,
+    prompt: str,
+    session_id: Optional[str] = None,
+) -> dict:
+    """Default agent invocation using code_puppy's agent system."""
+    try:
+        from code_puppy.agents import get_current_agent, load_agent, set_current_agent
+
+        # Save current agent to restore later
+        original_agent = get_current_agent()
+
+        try:
+            # Load the target agent
+            target_agent = load_agent(agent_name)
+            if target_agent is None:
+                return {"response": None, "error": f"Agent '{agent_name}' not found"}
+
+            # Run the agent with the prompt
+            # Note: This creates a fresh run with no message history
+            result = await target_agent.run_with_mcp(prompt)
+
+            # Extract response text
+            response_text = ""
+            if result is not None:
+                if hasattr(result, "data"):
+                    response_text = str(result.data) if result.data else ""
+                else:
+                    response_text = str(result)
+
+            return {"response": response_text, "error": None}
+
+        finally:
+            # Restore original agent
+            if original_agent:
+                set_current_agent(original_agent.name)
+
+    except Exception as e:
+        logger.exception(f"Failed to invoke agent {agent_name}")
+        return {"response": None, "error": str(e)}

code_puppy/plugins/ralph/models.py

@@ -0,0 +1,125 @@
+"""Data models for the Ralph plugin."""
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import List, Optional
+
+
+@dataclass
+class UserStory:
+    """A single user story in the PRD."""
+
+    id: str
+    title: str
+    description: str
+    acceptance_criteria: List[str]
+    priority: int
+    passes: bool = False
+    notes: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "description": self.description,
+            "acceptanceCriteria": self.acceptance_criteria,
+            "priority": self.priority,
+            "passes": self.passes,
+            "notes": self.notes,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "UserStory":
+        return cls(
+            id=data.get("id", ""),
+            title=data.get("title", ""),
+            description=data.get("description", ""),
+            acceptance_criteria=data.get("acceptanceCriteria", []),
+            priority=data.get("priority", 0),
+            passes=data.get("passes", False),
+            notes=data.get("notes", ""),
+        )
+
+    def has_ui_verification(self) -> bool:
+        """Check if this story requires browser/UI verification."""
+        ui_keywords = ["browser", "ui", "verify in browser", "qa-kitten", "visual"]
+        criteria_text = " ".join(self.acceptance_criteria).lower()
+        return any(kw in criteria_text for kw in ui_keywords)
+
+
+@dataclass
+class PRDConfig:
+    """Configuration for a PRD project."""
+
+    project: str
+    branch_name: str
+    description: str
+    user_stories: List[UserStory] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "project": self.project,
+            "branchName": self.branch_name,
+            "description": self.description,
+            "userStories": [s.to_dict() for s in self.user_stories],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PRDConfig":
+        return cls(
+            project=data.get("project", ""),
+            branch_name=data.get("branchName", ""),
+            description=data.get("description", ""),
+            user_stories=[UserStory.from_dict(s) for s in data.get("userStories", [])],
+        )
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "PRDConfig":
+        return cls.from_dict(json.loads(json_str))
+
+    def get_next_story(self) -> Optional[UserStory]:
+        """Get the highest priority story that hasn't passed yet."""
+        pending = [s for s in self.user_stories if not s.passes]
+        if not pending:
+            return None
+        return min(pending, key=lambda s: s.priority)
+
+    def all_complete(self) -> bool:
+        """Check if all stories have passed."""
+        return all(s.passes for s in self.user_stories)
+
+    def get_progress_summary(self) -> str:
+        """Get a summary of progress."""
+        total = len(self.user_stories)
+        done = sum(1 for s in self.user_stories if s.passes)
+        return f"{done}/{total} stories complete"
+
+
+@dataclass
+class ProgressEntry:
+    """An entry in the progress log."""
+
+    timestamp: datetime
+    story_id: str
+    summary: str
+    files_changed: List[str] = field(default_factory=list)
+    learnings: List[str] = field(default_factory=list)
+
+    def to_markdown(self) -> str:
+        """Convert to markdown format for progress.txt."""
+        lines = [
+            f"## {self.timestamp.strftime('%Y-%m-%d %H:%M')} - {self.story_id}",
+            f"- {self.summary}",
+        ]
+        if self.files_changed:
+            lines.append(f"- Files changed: {', '.join(self.files_changed)}")
+        if self.learnings:
+            lines.append("- **Learnings for future iterations:**")
+            for learning in self.learnings:
+                lines.append(f"  - {learning}")
+        lines.append("---")
+        return "\n".join(lines)

code_puppy/plugins/ralph/register_callbacks.py

@@ -0,0 +1,140 @@
+"""Ralph Plugin - Autonomous AI agent loop for completing PRDs.
+
+This module registers all Ralph callbacks:
+- register_tools: Ralph-specific tools for PRD management
+- register_agents: PRD Generator, Converter, and Orchestrator agents
+- custom_command: /ralph slash commands
+- custom_command_help: Help entries for Ralph commands
+- agent_run_end: Detect completion signal for loop termination
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+from code_puppy.callbacks import register_callback
+from code_puppy.messaging import emit_info, emit_success
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# TOOL REGISTRATION
+# ============================================================================
+
+
+def _provide_tools() -> List[Dict[str, Any]]:
+    """Provide Ralph tools via the register_tools callback."""
+    from .tools import get_ralph_tools
+
+    logger.debug("Ralph plugin: providing tools")
+    return get_ralph_tools()
+
+
+# ============================================================================
+# AGENT REGISTRATION
+# ============================================================================
+
+
+def _provide_agents() -> List[Dict[str, Any]]:
+    """Provide Ralph agents via the register_agents callback."""
+    from .agents import get_ralph_agents
+
+    logger.debug("Ralph plugin: providing agents")
+    return get_ralph_agents()
+
+
+# ============================================================================
+# COMMAND REGISTRATION
+# ============================================================================
+
+
+def _provide_command_help() -> List[Tuple[str, str]]:
+    """Provide help entries for Ralph commands."""
+    from .commands import get_ralph_help
+
+    return get_ralph_help()
+
+
+def _handle_command(command: str, name: str) -> Optional[Any]:
+    """Handle /ralph commands."""
+    from .commands import handle_ralph_command
+
+    return handle_ralph_command(command, name)
+
+
+# ============================================================================
+# COMPLETION DETECTION
+# ============================================================================
+
+# Track completion state for the loop controller
+_ralph_completion_detected = False
+_ralph_last_session_id: Optional[str] = None
+
+
+def is_ralph_complete() -> bool:
+    """Check if Ralph has signaled completion."""
+    return _ralph_completion_detected
+
+
+def reset_ralph_completion() -> None:
+    """Reset the completion flag for a new run."""
+    global _ralph_completion_detected, _ralph_last_session_id
+    _ralph_completion_detected = False
+    _ralph_last_session_id = None
+
+
+async def _on_agent_run_end(
+    agent_name: str,
+    model_name: str,
+    session_id: Optional[str] = None,
+    success: bool = True,
+    error: Optional[Exception] = None,
+    response_text: Optional[str] = None,
+    metadata: Optional[dict] = None,
+) -> None:
+    """Handle agent run completion.
+
+    This detects the <promise>COMPLETE</promise> signal from the
+    Ralph Orchestrator and sets the completion flag.
+    """
+    global _ralph_completion_detected, _ralph_last_session_id
+
+    # Only track ralph-orchestrator completions
+    if agent_name != "ralph-orchestrator":
+        return
+
+    # Only process successful runs with response text
+    if not success or not response_text:
+        return
+
+    logger.debug(f"Ralph plugin: orchestrator completed (session={session_id})")
+
+    # Check for completion signal
+    if "<promise>COMPLETE</promise>" in response_text:
+        _ralph_completion_detected = True
+        _ralph_last_session_id = session_id
+
+        emit_success("🎉 Ralph has completed all user stories!")
+        emit_info("All tasks in prd.json are now marked as passes: true")
+        logger.info("Ralph completion signal detected - all stories complete")
+
+
+# ============================================================================
+# REGISTER ALL CALLBACKS
+# ============================================================================
+
+# Tools
+register_callback("register_tools", _provide_tools)
+
+# Agents
+register_callback("register_agents", _provide_agents)
+
+# Commands
+register_callback("custom_command", _handle_command)
+register_callback("custom_command_help", _provide_command_help)
+
+# Completion detection
+register_callback("agent_run_end", _on_agent_run_end)
+
+
+logger.info("Ralph plugin: all callbacks registered successfully")