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

code_puppy/agents/base_agent.py

@@ -47,7 +47,10 @@ from pydantic_ai.messages import (
 from rich.text import Text
 
 from code_puppy.agents.event_stream_handler import event_stream_handler
-from code_puppy.callbacks import on_agent_response_complete
+from code_puppy.callbacks import (
+    on_agent_run_end,
+    on_agent_run_start,
+)
 
 # Consolidated relative imports
 from code_puppy.config import (
@@ -404,35 +407,27 @@ class BaseAgent(ABC):
         total_tokens = 0
 
         # 1. Estimate tokens for system prompt / instructions
-        # For Claude Code models, the full system prompt is prepended to the first
-        # user message (already in message history), so we only count the short
-        # fixed instructions. For other models, count the full system prompt.
+        # Use prepare_prompt_for_model() to get the correct instructions for token counting.
+        # For models that prepend system prompt to user message (claude-code, antigravity),
+        # this returns the short fixed instructions. For other models, returns full prompt.
         try:
-            from code_puppy.model_utils import (
-                get_antigravity_instructions,
-                get_claude_code_instructions,
-                is_antigravity_model,
-                is_claude_code_model,
-            )
+            from code_puppy.model_utils import prepare_prompt_for_model
 
             model_name = (
                 self.get_model_name() if hasattr(self, "get_model_name") else ""
             )
-            if is_claude_code_model(model_name):
-                # For Claude Code models, only count the short fixed instructions
-                # The full system prompt is already in the message history
-                instructions = get_claude_code_instructions()
-                total_tokens += self.estimate_token_count(instructions)
-            elif is_antigravity_model(model_name):
-                # For Antigravity models, only count the short fixed instructions
-                # The full system prompt is already in the message history
-                instructions = get_antigravity_instructions()
-                total_tokens += self.estimate_token_count(instructions)
-            else:
-                # For other models, count the full system prompt
-                system_prompt = self.get_full_system_prompt()
-                if system_prompt:
-                    total_tokens += self.estimate_token_count(system_prompt)
+            system_prompt = self.get_full_system_prompt()
+
+            # Get the instructions that will be used (handles model-specific logic via hooks)
+            prepared = prepare_prompt_for_model(
+                model_name=model_name,
+                system_prompt=system_prompt,
+                user_prompt="",  # Empty - we just need the instructions
+                prepend_system_to_user=False,  # Don't modify prompt, just get instructions
+            )
+
+            if prepared.instructions:
+                total_tokens += self.estimate_token_count(prepared.instructions)
         except Exception:
             pass  # If we can't get system prompt, skip it
 
@@ -1590,21 +1585,25 @@ class BaseAgent(ABC):
         if output_type is not None:
             pydantic_agent = self._create_agent_with_output_type(output_type)
 
-        # Handle claude-code, chatgpt-codex, and antigravity models: prepend system prompt to first user message
-        from code_puppy.model_utils import (
-            is_antigravity_model,
-            is_claude_code_model,
-        )
+        # Handle model-specific prompt transformations via prepare_prompt_for_model()
+        # This uses the get_model_system_prompt hook, so plugins can register their own handlers
+        from code_puppy.model_utils import prepare_prompt_for_model
 
-        if is_claude_code_model(self.get_model_name()) or is_antigravity_model(
-            self.get_model_name()
-        ):
-            if len(self.get_message_history()) == 0:
-                system_prompt = self.get_full_system_prompt()
-                puppy_rules = self.load_puppy_rules()
-                if puppy_rules:
-                    system_prompt += f"\n{puppy_rules}"
-                prompt = system_prompt + "\n\n" + prompt
+        # Only prepend system prompt on first message (empty history)
+        should_prepend = len(self.get_message_history()) == 0
+        if should_prepend:
+            system_prompt = self.get_full_system_prompt()
+            puppy_rules = self.load_puppy_rules()
+            if puppy_rules:
+                system_prompt += f"\n{puppy_rules}"
+
+            prepared = prepare_prompt_for_model(
+                model_name=self.get_model_name(),
+                system_prompt=system_prompt,
+                user_prompt=prompt,
+                prepend_system_to_user=True,
+            )
+            prompt = prepared.user_prompt
 
         # Build combined prompt payload when attachments are provided.
         attachment_parts: List[Any] = []
@@ -1751,6 +1750,17 @@ class BaseAgent(ABC):
         # Create the task FIRST
         agent_task = asyncio.create_task(run_agent_task())
 
+        # Fire agent_run_start hook - plugins can use this to start background tasks
+        # (e.g., token refresh heartbeats for OAuth models)
+        try:
+            await on_agent_run_start(
+                agent_name=self.name,
+                model_name=self.get_model_name(),
+                session_id=group_id,
+            )
+        except Exception:
+            pass  # Don't fail agent run if hook fails
+
         # Import shell process status helper
 
         loop = asyncio.get_running_loop()
@@ -1832,39 +1842,53 @@ class BaseAgent(ABC):
                 except Exception:
                     pass  # Don't fail the run if cache update fails
 
-            # Trigger agent_response_complete callback for workflow orchestration
-            try:
-                # Extract the response text from the result
-                response_text = ""
-                if result is not None:
-                    if hasattr(result, "data"):
-                        response_text = str(result.data) if result.data else ""
-                    elif hasattr(result, "output"):
-                        response_text = str(result.output) if result.output else ""
-                    else:
-                        response_text = str(result)
-
-                # Fire the callback - don't await to avoid blocking return
-                # Use asyncio.create_task to run it in background
-                asyncio.create_task(
-                    on_agent_response_complete(
-                        agent_name=self.name,
-                        response_text=response_text,
-                        session_id=group_id,
-                        metadata={"model": self.get_model_name()},
-                    )
-                )
-            except Exception:
-                pass  # Don't fail the run if callback fails
+            # Extract response text for the callback
+            _run_response_text = ""
+            if result is not None:
+                if hasattr(result, "data"):
+                    _run_response_text = str(result.data) if result.data else ""
+                elif hasattr(result, "output"):
+                    _run_response_text = str(result.output) if result.output else ""
+                else:
+                    _run_response_text = str(result)
 
+            _run_success = True
+            _run_error = None
             return result
         except asyncio.CancelledError:
+            _run_success = False
+            _run_error = None  # Cancellation is not an error
+            _run_response_text = ""
             agent_task.cancel()
         except KeyboardInterrupt:
-            # Handle direct keyboard interrupt during await
+            _run_success = False
+            _run_error = None  # User interrupt is not an error
+            _run_response_text = ""
             if not agent_task.done():
                 agent_task.cancel()
+        except Exception as e:
+            _run_success = False
+            _run_error = e
+            _run_response_text = ""
+            raise
         finally:
+            # Fire agent_run_end hook - plugins can use this for:
+            # - Stopping background tasks (token refresh heartbeats)
+            # - Workflow orchestration (Ralph's autonomous loop)
+            # - Logging/analytics
+            try:
+                await on_agent_run_end(
+                    agent_name=self.name,
+                    model_name=self.get_model_name(),
+                    session_id=group_id,
+                    success=_run_success,
+                    error=_run_error,
+                    response_text=_run_response_text,
+                    metadata={"model": self.get_model_name()},
+                )
+            except Exception:
+                pass  # Don't fail cleanup if hook fails
+
             # Stop keyboard listener if it was started
             if key_listener_stop_event is not None:
                 key_listener_stop_event.set()

code_puppy/callbacks.py

@@ -25,7 +25,8 @@ PhaseType = Literal[
     "register_agents",
     "register_model_type",
     "get_model_system_prompt",
-    "agent_response_complete",
+    "agent_run_start",
+    "agent_run_end",
 ]
 CallbackFunc = Callable[..., Any]
 
@@ -51,7 +52,8 @@ _callbacks: Dict[PhaseType, List[CallbackFunc]] = {
     "register_agents": [],
     "register_model_type": [],
     "get_model_system_prompt": [],
-    "agent_response_complete": [],
+    "agent_run_start": [],
+    "agent_run_end": [],
 }
 
 logger = logging.getLogger(__name__)
@@ -446,26 +448,72 @@ def on_get_model_system_prompt(
     )
 
 
-async def on_agent_response_complete(
+async def on_agent_run_start(
     agent_name: str,
-    response_text: str,
+    model_name: str,
     session_id: str | None = None,
+) -> List[Any]:
+    """Trigger callbacks when an agent run starts.
+
+    This fires at the beginning of run_with_mcp, before the agent task is created.
+    Useful for:
+    - Starting background tasks (like token refresh heartbeats)
+    - Logging/analytics
+    - Resource allocation
+
+    Args:
+        agent_name: Name of the agent starting
+        model_name: Name of the model being used
+        session_id: Optional session identifier
+
+    Returns:
+        List of results from registered callbacks.
+    """
+    return await _trigger_callbacks(
+        "agent_run_start", agent_name, model_name, session_id
+    )
+
+
+async def on_agent_run_end(
+    agent_name: str,
+    model_name: str,
+    session_id: str | None = None,
+    success: bool = True,
+    error: Exception | None = None,
+    response_text: str | None = None,
     metadata: dict | None = None,
 ) -> List[Any]:
-    """Trigger callbacks after an agent completes its full response.
+    """Trigger callbacks when an agent run ends.
+
+    This fires at the end of run_with_mcp, in the finally block.
+    Always fires regardless of success/failure/cancellation.
 
-    This fires after all tool calls are resolved and the agent has finished.
     Useful for:
+    - Stopping background tasks (like token refresh heartbeats)
     - Workflow orchestration (like Ralph's autonomous loop)
     - Logging/analytics
+    - Resource cleanup
     - Detecting completion signals in responses
 
     Args:
-        agent_name: Name of the agent that completed
-        response_text: The final text response from the agent
+        agent_name: Name of the agent that finished
+        model_name: Name of the model that was used
         session_id: Optional session identifier
+        success: Whether the run completed successfully
+        error: Exception if the run failed, None otherwise
+        response_text: The final text response from the agent (if successful)
         metadata: Optional dict with additional context (tokens used, etc.)
+
+    Returns:
+        List of results from registered callbacks.
     """
     return await _trigger_callbacks(
-        "agent_response_complete", agent_name, response_text, session_id, metadata
+        "agent_run_end",
+        agent_name,
+        model_name,
+        session_id,
+        success,
+        error,
+        response_text,
+        metadata,
     )

code_puppy/plugins/claude_code_oauth/__init__.py

@@ -3,4 +3,23 @@ Claude Code OAuth Plugin for Code Puppy
 
 This plugin provides OAuth authentication for Claude Code and automatically
 adds available models to the extra_models.json configuration.
+
+The plugin also includes a token refresh heartbeat for maintaining fresh
+tokens during long-running agentic operations.
 """
+
+from .token_refresh_heartbeat import (
+    TokenRefreshHeartbeat,
+    force_token_refresh,
+    get_current_heartbeat,
+    is_heartbeat_running,
+    token_refresh_heartbeat_context,
+)
+
+__all__ = [
+    "TokenRefreshHeartbeat",
+    "token_refresh_heartbeat_context",
+    "is_heartbeat_running",
+    "get_current_heartbeat",
+    "force_token_refresh",
+]

code_puppy/plugins/claude_code_oauth/register_callbacks.py

@@ -363,6 +363,78 @@ def _register_model_types() -> List[Dict[str, Any]]:
     return [{"type": "claude_code", "handler": _create_claude_code_model}]
 
 
+# Global storage for the token refresh heartbeat
+# Using a dict to allow multiple concurrent agent runs (keyed by session_id)
+_active_heartbeats: Dict[str, Any] = {}
+
+
+async def _on_agent_run_start(
+    agent_name: str,
+    model_name: str,
+    session_id: Optional[str] = None,
+) -> None:
+    """Start token refresh heartbeat for Claude Code OAuth models.
+
+    This callback is triggered when an agent run starts. If the model is a
+    Claude Code OAuth model, we start a background heartbeat to keep the
+    token fresh during long-running operations.
+    """
+    # Only start heartbeat for Claude Code models
+    if not model_name.startswith("claude-code"):
+        return
+
+    try:
+        from .token_refresh_heartbeat import TokenRefreshHeartbeat
+
+        heartbeat = TokenRefreshHeartbeat()
+        await heartbeat.start()
+
+        # Store heartbeat for cleanup, keyed by session_id
+        key = session_id or "default"
+        _active_heartbeats[key] = heartbeat
+        logger.debug(
+            "Started token refresh heartbeat for session %s (model: %s)",
+            key,
+            model_name,
+        )
+    except ImportError:
+        logger.debug("Token refresh heartbeat module not available")
+    except Exception as exc:
+        logger.debug("Failed to start token refresh heartbeat: %s", exc)
+
+
+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[str, Any]] = None,
+) -> None:
+    """Stop token refresh heartbeat when agent run ends.
+
+    This callback is triggered when an agent run completes (success or failure).
+    We stop any heartbeat that was started for this session.
+    """
+    # We don't use response_text or metadata, just cleanup the heartbeat
+    key = session_id or "default"
+    heartbeat = _active_heartbeats.pop(key, None)
+
+    if heartbeat is not None:
+        try:
+            await heartbeat.stop()
+            logger.debug(
+                "Stopped token refresh heartbeat for session %s (refreshed %d times)",
+                key,
+                heartbeat.refresh_count,
+            )
+        except Exception as exc:
+            logger.debug("Error stopping token refresh heartbeat: %s", exc)
+
+
 register_callback("custom_command_help", _custom_help)
 register_callback("custom_command", _handle_custom_command)
 register_callback("register_model_type", _register_model_types)
+register_callback("agent_run_start", _on_agent_run_start)
+register_callback("agent_run_end", _on_agent_run_end)

code_puppy/plugins/claude_code_oauth/token_refresh_heartbeat.py

@@ -0,0 +1,242 @@
+"""Token refresh heartbeat for long-running Claude Code OAuth sessions.
+
+This module provides a background task that periodically checks and refreshes
+Claude Code OAuth tokens during long-running agentic operations. This ensures
+that tokens don't expire during extended streaming responses or tool processing.
+
+Usage:
+    async with token_refresh_heartbeat_context():
+        # Long running agent operation
+        await agent.run(...)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from contextlib import asynccontextmanager
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Heartbeat interval in seconds - check token every 2 minutes
+# This is frequent enough to catch expiring tokens before they cause issues
+# but not so frequent as to spam the token endpoint
+HEARTBEAT_INTERVAL_SECONDS = 120
+
+# Minimum time between refresh attempts to avoid hammering the endpoint
+MIN_REFRESH_INTERVAL_SECONDS = 60
+
+# Global tracking of last refresh time to coordinate across heartbeats
+_last_refresh_time: float = 0.0
+_heartbeat_lock = asyncio.Lock()
+
+
+class TokenRefreshHeartbeat:
+    """Background task that periodically refreshes Claude Code OAuth tokens.
+
+    This runs as an asyncio task during agent operations and checks if the
+    token needs refreshing at regular intervals.
+    """
+
+    def __init__(
+        self,
+        interval: float = HEARTBEAT_INTERVAL_SECONDS,
+        min_refresh_interval: float = MIN_REFRESH_INTERVAL_SECONDS,
+    ):
+        self._interval = interval
+        self._min_refresh_interval = min_refresh_interval
+        self._task: Optional[asyncio.Task] = None
+        self._stop_event = asyncio.Event()
+        self._refresh_count = 0
+
+    async def start(self) -> None:
+        """Start the heartbeat background task."""
+        if self._task is not None:
+            logger.debug("Heartbeat already running")
+            return
+
+        self._stop_event.clear()
+        self._task = asyncio.create_task(self._heartbeat_loop())
+        logger.debug("Token refresh heartbeat started")
+
+    async def stop(self) -> None:
+        """Stop the heartbeat background task."""
+        if self._task is None:
+            return
+
+        self._stop_event.set()
+        self._task.cancel()
+
+        try:
+            await self._task
+        except asyncio.CancelledError:
+            pass
+
+        self._task = None
+        logger.debug(
+            "Token refresh heartbeat stopped (refreshed %d times)",
+            self._refresh_count,
+        )
+
+    async def _heartbeat_loop(self) -> None:
+        """Main heartbeat loop that periodically checks token status."""
+        global _last_refresh_time
+
+        while not self._stop_event.is_set():
+            try:
+                # Wait for the interval or until stopped
+                try:
+                    await asyncio.wait_for(
+                        self._stop_event.wait(), timeout=self._interval
+                    )
+                    # If we got here, stop event was set
+                    break
+                except asyncio.TimeoutError:
+                    # Normal timeout - time to check token
+                    pass
+
+                # Check if we should attempt refresh
+                async with _heartbeat_lock:
+                    now = time.time()
+                    if now - _last_refresh_time < self._min_refresh_interval:
+                        logger.debug(
+                            "Skipping refresh - last refresh was %.1f seconds ago",
+                            now - _last_refresh_time,
+                        )
+                        continue
+
+                    # Attempt the refresh
+                    refreshed = await self._attempt_refresh()
+                    if refreshed:
+                        _last_refresh_time = now
+                        self._refresh_count += 1
+
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:
+                logger.debug("Error in heartbeat loop: %s", exc)
+                # Continue running - don't let errors kill the heartbeat
+                await asyncio.sleep(5)  # Brief pause before retrying
+
+    async def _attempt_refresh(self) -> bool:
+        """Attempt to refresh the token if needed.
+
+        Returns:
+            True if a refresh was performed, False otherwise.
+        """
+        try:
+            # Import here to avoid circular imports
+            from .utils import (
+                is_token_expired,
+                load_stored_tokens,
+                refresh_access_token,
+            )
+
+            tokens = load_stored_tokens()
+            if not tokens:
+                logger.debug("No stored tokens found")
+                return False
+
+            if not is_token_expired(tokens):
+                logger.debug("Token not yet expired, skipping refresh")
+                return False
+
+            # Token is expiring soon, refresh it
+            logger.info("Heartbeat: Token expiring soon, refreshing proactively")
+            refreshed_token = refresh_access_token(force=False)
+
+            if refreshed_token:
+                logger.info("Heartbeat: Successfully refreshed token")
+                return True
+            else:
+                logger.warning("Heartbeat: Token refresh returned None")
+                return False
+
+        except Exception as exc:
+            logger.error("Heartbeat: Error during token refresh: %s", exc)
+            return False
+
+    @property
+    def refresh_count(self) -> int:
+        """Get the number of successful refreshes performed by this heartbeat."""
+        return self._refresh_count
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the heartbeat is currently running."""
+        return self._task is not None and not self._task.done()
+
+
+# Global heartbeat instance for the current session
+_current_heartbeat: Optional[TokenRefreshHeartbeat] = None
+
+
+@asynccontextmanager
+async def token_refresh_heartbeat_context(
+    interval: float = HEARTBEAT_INTERVAL_SECONDS,
+):
+    """Context manager that runs token refresh heartbeat during its scope.
+
+    Use this around long-running agent operations to ensure tokens stay fresh.
+
+    Args:
+        interval: Seconds between heartbeat checks. Default is 2 minutes.
+
+    Example:
+        async with token_refresh_heartbeat_context():
+            result = await agent.run(prompt)
+    """
+    global _current_heartbeat
+
+    heartbeat = TokenRefreshHeartbeat(interval=interval)
+
+    try:
+        await heartbeat.start()
+        _current_heartbeat = heartbeat
+        yield heartbeat
+    finally:
+        await heartbeat.stop()
+        _current_heartbeat = None
+
+
+def is_heartbeat_running() -> bool:
+    """Check if a token refresh heartbeat is currently active."""
+    return _current_heartbeat is not None and _current_heartbeat.is_running
+
+
+def get_current_heartbeat() -> Optional[TokenRefreshHeartbeat]:
+    """Get the currently running heartbeat instance, if any."""
+    return _current_heartbeat
+
+
+async def force_token_refresh() -> bool:
+    """Force an immediate token refresh.
+
+    This can be called from anywhere to trigger a token refresh,
+    regardless of whether a heartbeat is running.
+
+    Returns:
+        True if refresh was successful, False otherwise.
+    """
+    global _last_refresh_time
+
+    try:
+        from .utils import refresh_access_token
+
+        logger.info("Forcing token refresh")
+        refreshed_token = refresh_access_token(force=True)
+
+        if refreshed_token:
+            async with _heartbeat_lock:
+                _last_refresh_time = time.time()
+            logger.info("Force refresh successful")
+            return True
+        else:
+            logger.warning("Force refresh returned None")
+            return False
+
+    except Exception as exc:
+        logger.error("Force refresh error: %s", exc)
+        return False

code_puppy/plugins/ralph/loop_controller.py

@@ -17,46 +17,46 @@ 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. 
+            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
@@ -65,7 +65,7 @@ class RalphLoopController:
                 "iterations": 0,
                 "message": "No prd.json found. Create one with /ralph prd first.",
             }
-        
+
         if manager.all_stories_complete():
             self.is_running = False
             return {
@@ -73,68 +73,68 @@ class RalphLoopController:
                 "iterations": 0,
                 "message": "All stories already complete!",
             }
-        
+
         prd = manager.read_prd()
-        emit_info(f"🐺 Starting Ralph Loop")
+        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"\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")
-                
+                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
@@ -143,44 +143,48 @@ class RalphLoopController:
                     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_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)}
+{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
@@ -189,7 +193,7 @@ If ANY verification fails, fix the code and re-run until it passes!
 - **Description:** {story.description}
 
 ## Acceptance Criteria (implement ALL of these):
-{chr(10).join(f'  - {c}' for c in other_criteria)}
+{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 ""}
@@ -227,18 +231,18 @@ async def run_ralph_loop(
     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)
 
@@ -251,20 +255,20 @@ async def _default_invoke_agent(
     """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:
@@ -272,14 +276,14 @@ async def _default_invoke_agent(
                     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/register_callbacks.py

@@ -5,7 +5,7 @@ This module registers all Ralph callbacks:
 - register_agents: PRD Generator, Converter, and Orchestrator agents
 - custom_command: /ralph slash commands
 - custom_command_help: Help entries for Ralph commands
-- agent_response_complete: Detect completion signal for loop termination
+- agent_run_end: Detect completion signal for loop termination
 """
 
 import logging
@@ -83,13 +83,16 @@ def reset_ralph_completion() -> None:
     _ralph_last_session_id = None
 
 
-async def _on_agent_complete(
+async def _on_agent_run_end(
     agent_name: str,
-    response_text: 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 response completion.
+    """Handle agent run completion.
 
     This detects the <promise>COMPLETE</promise> signal from the
     Ralph Orchestrator and sets the completion flag.
@@ -100,10 +103,14 @@ async def _on_agent_complete(
     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 response_text and "<promise>COMPLETE</promise>" in response_text:
+    if "<promise>COMPLETE</promise>" in response_text:
         _ralph_completion_detected = True
         _ralph_last_session_id = session_id
 
@@ -127,7 +134,7 @@ register_callback("custom_command", _handle_command)
 register_callback("custom_command_help", _provide_command_help)
 
 # Completion detection
-register_callback("agent_response_complete", _on_agent_complete)
+register_callback("agent_run_end", _on_agent_run_end)
 
 
 logger.info("Ralph plugin: all callbacks registered successfully")

{code_puppy-0.0.375.dist-info → code_puppy-0.0.376.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-puppy
-Version: 0.0.375
+Version: 0.0.376
 Summary: Code generation agent
 Project-URL: repository, https://github.com/mpfaffenberger/code_puppy
 Project-URL: HomePage, https://github.com/mpfaffenberger/code_puppy

{code_puppy-0.0.375.dist-info → code_puppy-0.0.376.dist-info}/RECORD

@@ -1,6 +1,6 @@
 code_puppy/__init__.py,sha256=xMPewo9RNHb3yfFNIk5WCbv2cvSPtJOCgK2-GqLbNnU,373
 code_puppy/__main__.py,sha256=pDVssJOWP8A83iFkxMLY9YteHYat0EyWDQqMkKHpWp4,203
-code_puppy/callbacks.py,sha256=UyzEyuR0GPZFJ3td51m8JdzS8qLUYzigUsL4k3w6VnI,15466
+code_puppy/callbacks.py,sha256=A7aqykjNVB2HorewzerCEb3YYnqeDIdQG_2wNTt1paE,16745
 code_puppy/chatgpt_codex_client.py,sha256=upMuAfOhMB7SEpVw4CU4GjgaeZ8X65ri3yNM-dnlmYA,12308
 code_puppy/claude_cache_client.py,sha256=GtwYrxcTe0pE-JGtl1ysR2qskfeE73_x4w7q_u-kR1k,24026
 code_puppy/cli_runner.py,sha256=w5CLKgQYYaT7My3Cga2StXYol-u6DBxNzzUuhhsfhsA,34952
@@ -45,7 +45,7 @@ code_puppy/agents/agent_qa_kitten.py,sha256=qvry-1u_CiXi8eRueHTax4OtqsS_mQrtXHsb
 code_puppy/agents/agent_security_auditor.py,sha256=SpiYNA0XAsIwBj7S2_EQPRslRUmF_-b89pIJyW7DYtY,12022
 code_puppy/agents/agent_terminal_qa.py,sha256=U-iyP7OBWdAmchW_oUU8k6asH2aignTMmgqqYDyf-ms,10343
 code_puppy/agents/agent_typescript_reviewer.py,sha256=vsnpp98xg6cIoFAEJrRTUM_i4wLEWGm5nJxs6fhHobM,10275
-code_puppy/agents/base_agent.py,sha256=dFmMtE2i0QLq2mwhjx4MHvz8h79U3pZLbY9regd379Y,75648
+code_puppy/agents/base_agent.py,sha256=gZvACpqH8L2Wp2xjn_v5D4Azlt6yvGnQO6UApN8HCEo,76272
 code_puppy/agents/event_stream_handler.py,sha256=JttLZJpNADE5HXiXY-GZ6tpwaBeFRODcy34KiquPOvU,14952
 code_puppy/agents/json_agent.py,sha256=FtbZxO8mo563kvXgpgRM4b-c9VA3G3cty7r-O0nBZQk,5690
 code_puppy/agents/prompt_reviewer.py,sha256=JJrJ0m5q0Puxl8vFsyhAbY9ftU9n6c6UxEVdNct1E-Q,5558
@@ -169,10 +169,11 @@ code_puppy/plugins/chatgpt_oauth/test_plugin.py,sha256=oHX7Eb_Hb4rgRpOWdhtFp8Jj6
 code_puppy/plugins/chatgpt_oauth/utils.py,sha256=fzpsCQOv0kqPWmG5vNEV_GLSUrMQh8cF7tdIjSOt1Dc,16504
 code_puppy/plugins/claude_code_oauth/README.md,sha256=fOSDDzCdm2JCKjU5J82IRHIAhxYxl8_UmHo7uH4AbFo,5469
 code_puppy/plugins/claude_code_oauth/SETUP.md,sha256=DCNLkSU9nf86S1rsrIg8HBe87NZrF8YND8P4ettWeEM,3289
-code_puppy/plugins/claude_code_oauth/__init__.py,sha256=mCcOU-wM7LNCDjr-w-WLPzom8nTF1UNt4nqxGE6Rt0k,187
+code_puppy/plugins/claude_code_oauth/__init__.py,sha256=DgYQ1zQy-Wf-tSphD4wYrvtztdr-Dubhf4AqsSi315I,659
 code_puppy/plugins/claude_code_oauth/config.py,sha256=DjGySCkvjSGZds6DYErLMAi3TItt8iSLGvyJN98nSEM,2013
-code_puppy/plugins/claude_code_oauth/register_callbacks.py,sha256=FIHPQFJdsICesZlxt-wg7IFr1SOeKP3G8J8GmvK6O64,12635
+code_puppy/plugins/claude_code_oauth/register_callbacks.py,sha256=uvNA2wpSifeCD_o2CTENCuXQiq2ntk0uzQw8iAhZYng,15080
 code_puppy/plugins/claude_code_oauth/test_plugin.py,sha256=yQy4EeZl4bjrcog1d8BjknoDTRK75mRXXvkSQJYSSEM,9286
+code_puppy/plugins/claude_code_oauth/token_refresh_heartbeat.py,sha256=ErkrquUUTaqHkrLuPxTZymLkMOcju-wr5zAuO4fyN-s,7865
 code_puppy/plugins/claude_code_oauth/utils.py,sha256=2ioGG-4FCh4WdHrN2MJvWKbPWA-YVg_WTEeddc1xv4U,18557
 code_puppy/plugins/customizable_commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 code_puppy/plugins/customizable_commands/register_callbacks.py,sha256=zVMfIzr--hVn0IOXxIicbmgj2s-HZUgtrOc0NCDOnDw,5183
@@ -186,9 +187,9 @@ code_puppy/plugins/frontend_emitter/register_callbacks.py,sha256=3j7Emn3VeWSJSN9
 code_puppy/plugins/ralph/__init__.py,sha256=drPRgJ2LGLh8v_8dk7TJIklv-51XHjqW7SMfNTzwiGI,448
 code_puppy/plugins/ralph/agents.py,sha256=EQ2pvb8tb8aFfYZYtBuo9rBIvVp18XCieeK5PRvH3K4,11914
 code_puppy/plugins/ralph/commands.py,sha256=J1sVNrm4SBj_ujkO51ILWzdH5L3px6NPR_mn0mXD_FQ,6736
-code_puppy/plugins/ralph/loop_controller.py,sha256=lebabWFyeGPUL_6G0gANbjHUF11ZNsry4IytgwhkSsg,10497
+code_puppy/plugins/ralph/loop_controller.py,sha256=uhEOKpmkxlfj5MK6_zVvSHH9D79JRx4RRkNtBkrBkNk,10107
 code_puppy/plugins/ralph/models.py,sha256=IrAJW85CgKA6yYSrWRn3VHx_65ukFkrasUhbVM1emF0,3983
-code_puppy/plugins/ralph/register_callbacks.py,sha256=ozhXyyb-GS-PQ3cRUMyDnLntwbZ1aVxjVwSExcHhgcE,4260
+code_puppy/plugins/ralph/register_callbacks.py,sha256=_q1SILAYc8BHyWpXZoA8MOVsLCFnOvQ3vU8PzjfzZxc,4429
 code_puppy/plugins/ralph/state_manager.py,sha256=jv7bnQBiy_XQTj7Kfl3zBIMLV3XN5U-IS_U-fIdpHe0,10215
 code_puppy/plugins/ralph/tools.py,sha256=p767ZdjkeRmfWTqUYdFmXnKEHC15ek1Ho3tkLcjWb20,14391
 code_puppy/plugins/shell_safety/__init__.py,sha256=B-RYLWKlvrws9XCHG1Z99mBMC3VC394HAlMOhhCoGGI,243
@@ -224,10 +225,10 @@ code_puppy/tools/browser/chromium_terminal_manager.py,sha256=w1thQ_ACb6oV45L93TS
 code_puppy/tools/browser/terminal_command_tools.py,sha256=9byOZku-dwvTtCl532xt7Lumed_jTn0sLvUe_X75XCQ,19068
 code_puppy/tools/browser/terminal_screenshot_tools.py,sha256=J_21YO_495NvYgNFu9KQP6VYg2K_f8CtSdZuF94Yhnw,18448
 code_puppy/tools/browser/terminal_tools.py,sha256=F5LjVH3udSCFHmqC3O1UJLoLozZFZsEdX42jOmkqkW0,17853
-code_puppy-0.0.375.data/data/code_puppy/models.json,sha256=jAHRsCl3trysP4vU_k_ltA8GcFU2APd4lxFl8-4Jnvc,3243
-code_puppy-0.0.375.data/data/code_puppy/models_dev_api.json,sha256=wHjkj-IM_fx1oHki6-GqtOoCrRMR0ScK0f-Iz0UEcy8,548187
-code_puppy-0.0.375.dist-info/METADATA,sha256=G1WxQE4CL8DRjJgD1MNtPCys-eN8KsL6A02CRLvvIzg,27604
-code_puppy-0.0.375.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-code_puppy-0.0.375.dist-info/entry_points.txt,sha256=Tp4eQC99WY3HOKd3sdvb22vZODRq0XkZVNpXOag_KdI,91
-code_puppy-0.0.375.dist-info/licenses/LICENSE,sha256=31u8x0SPgdOq3izJX41kgFazWsM43zPEF9eskzqbJMY,1075
-code_puppy-0.0.375.dist-info/RECORD,,
+code_puppy-0.0.376.data/data/code_puppy/models.json,sha256=jAHRsCl3trysP4vU_k_ltA8GcFU2APd4lxFl8-4Jnvc,3243
+code_puppy-0.0.376.data/data/code_puppy/models_dev_api.json,sha256=wHjkj-IM_fx1oHki6-GqtOoCrRMR0ScK0f-Iz0UEcy8,548187
+code_puppy-0.0.376.dist-info/METADATA,sha256=8zBZ-_vl5I-bVjco6ZxTH1Vsiz7NQQO1AqtYAiisweA,27604
+code_puppy-0.0.376.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+code_puppy-0.0.376.dist-info/entry_points.txt,sha256=Tp4eQC99WY3HOKd3sdvb22vZODRq0XkZVNpXOag_KdI,91
+code_puppy-0.0.376.dist-info/licenses/LICENSE,sha256=31u8x0SPgdOq3izJX41kgFazWsM43zPEF9eskzqbJMY,1075
+code_puppy-0.0.376.dist-info/RECORD,,