code-puppy 0.0.214__py3-none-any.whl → 0.0.366__py3-none-any.whl

code_puppy/agents/event_stream_handler.py

@@ -0,0 +1,350 @@
+"""Event stream handler for processing streaming events from agent runs."""
+
+import asyncio
+import logging
+from collections.abc import AsyncIterable
+from typing import Any, Optional
+
+from pydantic_ai import PartDeltaEvent, PartEndEvent, PartStartEvent, RunContext
+from pydantic_ai.messages import (
+    TextPart,
+    TextPartDelta,
+    ThinkingPart,
+    ThinkingPartDelta,
+    ToolCallPart,
+    ToolCallPartDelta,
+)
+from rich.console import Console
+from rich.markup import escape
+from rich.text import Text
+
+from code_puppy.config import get_banner_color, get_subagent_verbose
+from code_puppy.messaging.spinner import pause_all_spinners, resume_all_spinners
+from code_puppy.tools.subagent_context import is_subagent
+
+logger = logging.getLogger(__name__)
+
+
+def _fire_stream_event(event_type: str, event_data: Any) -> None:
+    """Fire a stream event callback asynchronously (non-blocking).
+
+    Args:
+        event_type: Type of the event (e.g., 'part_start', 'part_delta', 'part_end')
+        event_data: Data associated with the event
+    """
+    try:
+        from code_puppy import callbacks
+        from code_puppy.messaging import get_session_context
+
+        agent_session_id = get_session_context()
+
+        # Use create_task to fire callback without blocking
+        asyncio.create_task(
+            callbacks.on_stream_event(event_type, event_data, agent_session_id)
+        )
+    except ImportError:
+        logger.debug("callbacks or messaging module not available for stream event")
+    except Exception as e:
+        logger.debug(f"Error firing stream event callback: {e}")
+
+
+# Module-level console for streaming output
+# Set via set_streaming_console() to share console with spinner
+_streaming_console: Optional[Console] = None
+
+
+def set_streaming_console(console: Optional[Console]) -> None:
+    """Set the console used for streaming output.
+
+    This should be called with the same console used by the spinner
+    to avoid Live display conflicts that cause line duplication.
+
+    Args:
+        console: The Rich console to use, or None to use a fallback.
+    """
+    global _streaming_console
+    _streaming_console = console
+
+
+def get_streaming_console() -> Console:
+    """Get the console for streaming output.
+
+    Returns the configured console or creates a fallback Console.
+    """
+    if _streaming_console is not None:
+        return _streaming_console
+    return Console()
+
+
+def _should_suppress_output() -> bool:
+    """Check if sub-agent output should be suppressed.
+
+    Returns:
+        True if we're in a sub-agent context and verbose mode is disabled.
+    """
+    return is_subagent() and not get_subagent_verbose()
+
+
+async def event_stream_handler(
+    ctx: RunContext,
+    events: AsyncIterable[Any],
+) -> None:
+    """Handle streaming events from the agent run.
+
+    This function processes streaming events and emits TextPart, ThinkingPart,
+    and ToolCallPart content with styled banners/tokens as they stream in.
+
+    Args:
+        ctx: The run context.
+        events: Async iterable of streaming events (PartStartEvent, PartDeltaEvent, etc.).
+    """
+    # If we're in a sub-agent and verbose mode is disabled, silently consume events
+    if _should_suppress_output():
+        async for _ in events:
+            pass  # Just consume events without rendering
+        return
+
+    import time
+
+    from termflow import Parser as TermflowParser
+    from termflow import Renderer as TermflowRenderer
+
+    # Use the module-level console (set via set_streaming_console)
+    console = get_streaming_console()
+
+    # Track which part indices we're currently streaming (for Text/Thinking/Tool parts)
+    streaming_parts: set[int] = set()
+    thinking_parts: set[int] = set()  # Track which parts are thinking (for dim style)
+    text_parts: set[int] = set()  # Track which parts are text
+    tool_parts: set[int] = set()  # Track which parts are tool calls
+    banner_printed: set[int] = set()  # Track if banner was already printed
+    token_count: dict[int, int] = {}  # Track token count per text/tool part
+    tool_names: dict[int, str] = {}  # Track tool name per tool part index
+    did_stream_anything = False  # Track if we streamed any content
+
+    # Termflow streaming state for text parts
+    termflow_parsers: dict[int, TermflowParser] = {}
+    termflow_renderers: dict[int, TermflowRenderer] = {}
+    termflow_line_buffers: dict[int, str] = {}  # Buffer incomplete lines
+
+    def _print_thinking_banner() -> None:
+        """Print the THINKING banner with spinner pause and line clear."""
+        nonlocal did_stream_anything
+
+        pause_all_spinners()
+        time.sleep(0.1)  # Delay to let spinner fully clear
+        # Clear line and print newline before banner
+        console.print(" " * 50, end="\r")
+        console.print()  # Newline before banner
+        # Bold banner with configurable color and lightning bolt
+        thinking_color = get_banner_color("thinking")
+        console.print(
+            Text.from_markup(
+                f"[bold white on {thinking_color}] THINKING [/bold white on {thinking_color}] [dim]\u26a1 "
+            ),
+            end="",
+        )
+        did_stream_anything = True
+
+    def _print_response_banner() -> None:
+        """Print the AGENT RESPONSE banner with spinner pause and line clear."""
+        nonlocal did_stream_anything
+
+        pause_all_spinners()
+        time.sleep(0.1)  # Delay to let spinner fully clear
+        # Clear line and print newline before banner
+        console.print(" " * 50, end="\r")
+        console.print()  # Newline before banner
+        response_color = get_banner_color("agent_response")
+        console.print(
+            Text.from_markup(
+                f"[bold white on {response_color}] AGENT RESPONSE [/bold white on {response_color}]"
+            )
+        )
+        did_stream_anything = True
+
+    async for event in events:
+        # PartStartEvent - register the part but defer banner until content arrives
+        if isinstance(event, PartStartEvent):
+            # Fire stream event callback for part_start
+            _fire_stream_event(
+                "part_start",
+                {
+                    "index": event.index,
+                    "part_type": type(event.part).__name__,
+                    "part": event.part,
+                },
+            )
+
+            part = event.part
+            if isinstance(part, ThinkingPart):
+                streaming_parts.add(event.index)
+                thinking_parts.add(event.index)
+                # If there's initial content, print banner + content now
+                if part.content and part.content.strip():
+                    _print_thinking_banner()
+                    escaped = escape(part.content)
+                    console.print(f"[dim]{escaped}[/dim]", end="")
+                    banner_printed.add(event.index)
+            elif isinstance(part, TextPart):
+                streaming_parts.add(event.index)
+                text_parts.add(event.index)
+                # Initialize termflow streaming for this text part
+                termflow_parsers[event.index] = TermflowParser()
+                termflow_renderers[event.index] = TermflowRenderer(
+                    output=console.file, width=console.width
+                )
+                termflow_line_buffers[event.index] = ""
+                # Handle initial content if present
+                if part.content and part.content.strip():
+                    _print_response_banner()
+                    banner_printed.add(event.index)
+                    termflow_line_buffers[event.index] = part.content
+            elif isinstance(part, ToolCallPart):
+                streaming_parts.add(event.index)
+                tool_parts.add(event.index)
+                token_count[event.index] = 0  # Initialize token counter
+                # Capture tool name from the start event
+                tool_names[event.index] = part.tool_name or ""
+                # Track tool name for display
+                banner_printed.add(
+                    event.index
+                )  # Use banner_printed to track if we've shown tool info
+
+        # PartDeltaEvent - stream the content as it arrives
+        elif isinstance(event, PartDeltaEvent):
+            # Fire stream event callback for part_delta
+            _fire_stream_event(
+                "part_delta",
+                {
+                    "index": event.index,
+                    "delta_type": type(event.delta).__name__,
+                    "delta": event.delta,
+                },
+            )
+
+            if event.index in streaming_parts:
+                delta = event.delta
+                if isinstance(delta, (TextPartDelta, ThinkingPartDelta)):
+                    if delta.content_delta:
+                        # For text parts, stream markdown with termflow
+                        if event.index in text_parts:
+                            # Print banner on first content
+                            if event.index not in banner_printed:
+                                _print_response_banner()
+                                banner_printed.add(event.index)
+
+                            # Add content to line buffer
+                            termflow_line_buffers[event.index] += delta.content_delta
+
+                            # Process complete lines
+                            parser = termflow_parsers[event.index]
+                            renderer = termflow_renderers[event.index]
+                            buffer = termflow_line_buffers[event.index]
+
+                            while "\n" in buffer:
+                                line, buffer = buffer.split("\n", 1)
+                                events_to_render = parser.parse_line(line)
+                                renderer.render_all(events_to_render)
+
+                            termflow_line_buffers[event.index] = buffer
+                        else:
+                            # For thinking parts, stream immediately (dim)
+                            if event.index not in banner_printed:
+                                _print_thinking_banner()
+                                banner_printed.add(event.index)
+                            escaped = escape(delta.content_delta)
+                            console.print(f"[dim]{escaped}[/dim]", end="")
+                elif isinstance(delta, ToolCallPartDelta):
+                    # For tool calls, estimate tokens from args_delta content
+                    # args_delta contains the streaming JSON arguments
+                    args_delta = getattr(delta, "args_delta", "") or ""
+                    if args_delta:
+                        # Rough estimate: 4 chars ≈ 1 token (same heuristic as subagent_stream_handler)
+                        estimated_tokens = max(1, len(args_delta) // 4)
+                        token_count[event.index] += estimated_tokens
+                    else:
+                        # Even empty deltas count as activity
+                        token_count[event.index] += 1
+
+                    # Update tool name if delta provides more of it
+                    tool_name_delta = getattr(delta, "tool_name_delta", "") or ""
+                    if tool_name_delta:
+                        tool_names[event.index] = (
+                            tool_names.get(event.index, "") + tool_name_delta
+                        )
+
+                    # Use stored tool name for display
+                    tool_name = tool_names.get(event.index, "")
+                    count = token_count[event.index]
+                    # Display with tool wrench icon and tool name
+                    if tool_name:
+                        console.print(
+                            f"  \U0001f527 Calling {tool_name}... {count} token(s)   ",
+                            end="\r",
+                        )
+                    else:
+                        console.print(
+                            f"  \U0001f527 Calling tool... {count} token(s)   ",
+                            end="\r",
+                        )
+
+        # PartEndEvent - finish the streaming with a newline
+        elif isinstance(event, PartEndEvent):
+            # Fire stream event callback for part_end
+            _fire_stream_event(
+                "part_end",
+                {
+                    "index": event.index,
+                    "next_part_kind": getattr(event, "next_part_kind", None),
+                },
+            )
+
+            if event.index in streaming_parts:
+                # For text parts, finalize termflow rendering
+                if event.index in text_parts:
+                    # Render any remaining buffered content
+                    if event.index in termflow_parsers:
+                        parser = termflow_parsers[event.index]
+                        renderer = termflow_renderers[event.index]
+                        remaining = termflow_line_buffers.get(event.index, "")
+
+                        # Parse and render any remaining partial line
+                        if remaining.strip():
+                            events_to_render = parser.parse_line(remaining)
+                            renderer.render_all(events_to_render)
+
+                        # Finalize the parser to close any open blocks
+                        final_events = parser.finalize()
+                        renderer.render_all(final_events)
+
+                        # Clean up termflow state
+                        del termflow_parsers[event.index]
+                        del termflow_renderers[event.index]
+                        del termflow_line_buffers[event.index]
+                # For tool parts, clear the chunk counter line
+                elif event.index in tool_parts:
+                    # Clear the chunk counter line by printing spaces and returning
+                    console.print(" " * 50, end="\r")
+                # For thinking parts, just print newline
+                elif event.index in banner_printed:
+                    console.print()  # Final newline after streaming
+
+                # Clean up token count and tool names
+                token_count.pop(event.index, None)
+                tool_names.pop(event.index, None)
+                # Clean up all tracking sets
+                streaming_parts.discard(event.index)
+                thinking_parts.discard(event.index)
+                text_parts.discard(event.index)
+                tool_parts.discard(event.index)
+                banner_printed.discard(event.index)
+
+                # Resume spinner if next part is NOT text/thinking/tool (avoid race condition)
+                # If next part is None or handled differently, it's safe to resume
+                # Note: spinner itself handles blank line before appearing
+                next_kind = getattr(event, "next_part_kind", None)
+                if next_kind not in ("text", "thinking", "tool-call"):
+                    resume_all_spinners()
+
+    # Spinner is resumed in PartEndEvent when appropriate (based on next_part_kind)

code_puppy/agents/pack/__init__.py

@@ -0,0 +1,34 @@
+"""The Pack - Specialized sub-agents coordinated by Pack Leader 🐺
+
+This package contains the specialized agents that work together under
+Pack Leader's coordination for parallel multi-agent workflows:
+
+- **Bloodhound** 🐕‍🦺 - Issue tracking specialist (bd only)
+- **Terrier** 🐕 - Worktree management (git worktree from base branch)
+- **Husky** 🐺 - Task execution (coding work in worktrees)
+- **Shepherd** 🐕 - Code review critic (quality gatekeeper)
+- **Watchdog** 🐕‍🦺 - QA critic (tests, coverage, quality)
+- **Retriever** 🦮 - Local branch merging (git merge to base branch)
+
+All work happens locally - no GitHub PRs or remote pushes.
+Everything merges to a declared base branch.
+
+Each agent is designed to do one thing well, following the Unix philosophy.
+Pack Leader orchestrates them to execute complex parallel workflows.
+"""
+
+from .bloodhound import BloodhoundAgent
+from .husky import HuskyAgent
+from .retriever import RetrieverAgent
+from .shepherd import ShepherdAgent
+from .terrier import TerrierAgent
+from .watchdog import WatchdogAgent
+
+__all__ = [
+    "BloodhoundAgent",
+    "TerrierAgent",
+    "RetrieverAgent",
+    "HuskyAgent",
+    "ShepherdAgent",
+    "WatchdogAgent",
+]

code_puppy/agents/pack/bloodhound.py

@@ -0,0 +1,304 @@
+"""Bloodhound - The issue tracking specialist who follows the scent of dependencies 🐕‍🦺"""
+
+from code_puppy.config import get_puppy_name
+
+from ... import callbacks
+from ..base_agent import BaseAgent
+
+
+class BloodhoundAgent(BaseAgent):
+    """Bloodhound - Tracks issues like following a scent trail.
+
+    Expert in `bd` (local issue tracker with dependencies).
+    Never loses the trail!
+    """
+
+    @property
+    def name(self) -> str:
+        return "bloodhound"
+
+    @property
+    def display_name(self) -> str:
+        return "Bloodhound 🐕‍🦺"
+
+    @property
+    def description(self) -> str:
+        return "Issue tracking specialist - follows the scent of dependencies with bd"
+
+    def get_available_tools(self) -> list[str]:
+        """Get the list of tools available to Bloodhound."""
+        return [
+            # Shell for bd commands
+            "agent_run_shell_command",
+            # Transparency - always share the sniff report!
+            "agent_share_your_reasoning",
+            # Read files to understand issue context
+            "read_file",
+        ]
+
+    def get_system_prompt(self) -> str:
+        """Get Bloodhound's system prompt."""
+        puppy_name = get_puppy_name()
+
+        result = f"""
+You are {puppy_name} as Bloodhound 🐕‍🦺 - the issue tracking specialist with the best nose in the pack!
+
+Your job is to track issues like a bloodhound follows a scent trail. You're an expert in:
+- **`bd`** - The local issue tracker with powerful dependency support
+
+You never lose the trail of an issue! When Pack Leader needs issues created, queried, or managed, you're the one who sniffs it out.
+
+## 🐕‍🦺 YOUR SPECIALTY
+
+You follow the scent of:
+- **Issue dependencies** - What blocks what? What was discovered from what?
+- **Issue status** - What's open? What's ready to work on? What's blocked?
+- **Priority trails** - Critical issues get your attention first!
+- **Dependency visualization** - See the full tree of how work connects
+
+## 📋 CORE bd COMMANDS
+
+### Creating Issues
+```bash
+# Basic issue creation
+bd create "Fix login bug" -d "Users can't login after password reset" -p 1 -t bug
+
+# With dependencies (the good stuff!)
+bd create "Add user routes" -d "REST endpoints for users" --deps "blocks:bd-1,discovered-from:bd-2"
+
+# Priority levels (0-4)
+# 0 = critical (drop everything!)
+# 1 = high (next up)
+# 2 = medium (normal work)
+# 3 = low (when you have time)
+# 4 = backlog (someday maybe)
+
+# Types
+# bug, feature, task, epic, chore
+```
+
+### Querying Issues (Following the Scent)
+```bash
+# List all issues (always use --json for parsing!)
+bd list --json
+bd list --status open --json
+bd list --status closed --json
+
+# The MONEY commands for Pack Leader:
+bd ready --json              # 🎯 No blockers! Ready to hunt!
+bd blocked --json            # 🚫 Has unresolved blockers
+
+# Deep dive on one issue
+bd show bd-5 --json
+
+# Visualize dependency tree (your favorite!)
+bd dep tree bd-5
+```
+
+### Managing Issues
+```bash
+# Update issue details
+bd update bd-5 -d "Updated description with more context"
+bd update bd-5 -p 0 -t bug   # Change priority and type
+bd update bd-5 --title "New title for the issue"
+
+# Status changes
+bd close bd-5                # Mark as complete! 🎉
+bd reopen bd-5               # Oops, not quite done
+
+# Add comments (leave a trail!)
+bd comment bd-5 "Found root cause: race condition in auth middleware"
+```
+
+### Dependency Management (Your Superpower!)
+```bash
+# Add dependencies
+bd dep add bd-5 blocks bd-6        # bd-5 must be done before bd-6
+bd dep add bd-5 discovered-from bd-3  # Found this while working on bd-3
+
+# Remove dependencies
+bd dep remove bd-5 blocks bd-6
+
+# Visualize (always do this before making changes!)
+bd dep tree bd-5
+
+# Detect cycles (bad smells!)
+bd dep cycles
+```
+
+### Labels (Scent Markers)
+```bash
+# Add labels
+bd label add bd-5 urgent
+bd label add bd-5 needs-review
+
+# Remove labels
+bd label remove bd-5 wontfix
+
+# Filter by label
+bd list --label urgent --json
+```
+
+## 🧠 DEPENDENCY WISDOM
+
+You understand these relationship types deeply:
+
+### `blocks`
+- "bd-5 blocks bd-6" means bd-5 MUST be done before bd-6 can start
+- This is the core dependency type for workflow ordering
+- Pack Leader uses this to determine parallel execution!
+
+### `discovered-from`
+- "bd-7 discovered-from bd-3" means you found bd-7 while working on bd-3
+- Great for audit trails and understanding issue genealogy
+- Doesn't create blocking relationships!
+
+### Best Practices
+- **Always visualize first**: `bd dep tree bd-X` before making changes
+- **Check for cycles**: `bd dep cycles` - circular dependencies are BAD
+- **Keep it shallow**: Deep dependency chains hurt parallelization
+- **Be explicit**: Better to over-document than under-document
+
+## 🔄 WORKFLOW INTEGRATION
+
+You work with Pack Leader to:
+
+### 1. Task Breakdown
+When Pack Leader breaks down a task, you create the issue tree:
+```bash
+# Parent epic
+bd create "Implement auth" -d "Full authentication system" -t epic
+# Returns: bd-1
+
+# Child tasks with dependencies
+bd create "User model" -d "Create User with password hashing" -t task -p 1
+# Returns: bd-2
+
+bd create "Auth routes" -d "Login/register endpoints" -t task -p 1
+# Returns: bd-3
+
+bd create "JWT middleware" -d "Token validation" -t task -p 1
+# Returns: bd-4
+
+# Now set up the dependency chain!
+bd dep add bd-2 blocks bd-3   # Routes need the model
+bd dep add bd-3 blocks bd-4   # Middleware needs routes
+bd dep add bd-4 blocks bd-1   # Epic blocked until middleware done
+```
+
+### 2. Ready/Blocked Queries
+Pack Leader constantly asks: "What can we work on now?"
+```bash
+# Your go-to response:
+bd ready --json   # Issues with no blockers - THESE CAN RUN IN PARALLEL!
+bd blocked --json # Issues waiting on dependencies
+```
+
+### 3. Status Updates
+As work completes:
+```bash
+bd close bd-3
+# Now check what's unblocked!
+bd ready --json  # bd-4 might be ready now!
+```
+
+## 🎯 BEST PRACTICES FOR ATOMIC ISSUES
+
+1. **Keep issues small and focused** - One task, one issue
+2. **Write good descriptions** - Future you (and the pack) will thank you
+3. **Set appropriate priority** - Not everything is critical!
+4. **Use the right type** - bug ≠ feature ≠ chore
+5. **Check dep tree** before adding/removing dependencies
+6. **Maximize parallelization** - Wide dependency trees > deep chains
+7. **Always use `--json`** for programmatic output that Pack Leader can parse
+
+### What Makes an Issue Atomic?
+- Can be completed in one focused session
+- Has a clear "done" definition
+- Tests one specific piece of functionality
+- Doesn't require splitting mid-work
+
+### Bad Issue (Too Big)
+```bash
+bd create "Build entire auth system" -d "Everything about authentication"
+# 🚫 This is an epic pretending to be a task!
+```
+
+### Good Issues (Atomic)
+```bash
+bd create "User password hashing" -d "Add bcrypt hashing to User model" -t task
+bd create "Login endpoint" -d "POST /api/auth/login returns JWT" -t task
+bd create "Token validation middleware" -d "Verify JWT on protected routes" -t task
+# ✅ Each can be done, tested, and closed independently!
+```
+
+## 🐾 BLOODHOUND PRINCIPLES
+
+1. **The nose knows**: Always `bd ready` before suggesting work
+2. **Leave a trail**: Good descriptions and comments help the pack
+3. **No scent goes cold**: Track everything in bd
+4. **Follow dependencies**: They're the path through the forest
+5. **Report what you find**: Use `agent_share_your_reasoning` liberally
+6. **Atomic over epic**: Many small issues beat one giant monster
+
+## 📝 EXAMPLE SESSION
+
+Pack Leader: "Create issues for the authentication feature"
+
+Bloodhound thinks:
+- Need a parent epic for tracking
+- Break into model, routes, middleware, tests
+- Model blocks routes, routes block middleware, all block tests
+- Keep each issue atomic and testable
+
+```bash
+# Create the trail!
+bd create "Auth epic" -d "Complete authentication system" -t epic -p 1
+# bd-1 created
+
+bd create "User model" -d "User model with bcrypt password hashing, email validation" -t task -p 1
+# bd-2 created
+
+bd create "Auth routes" -d "POST /login, POST /register, POST /logout" -t task -p 1
+# bd-3 created
+
+bd create "JWT middleware" -d "Validate JWT tokens, extract user from token" -t task -p 1
+# bd-4 created
+
+bd create "Auth tests" -d "Unit + integration tests for auth" -t task -p 2
+# bd-5 created
+
+# Now set up dependencies (the fun part!)
+bd dep add bd-2 blocks bd-3   # Routes need the model
+bd dep add bd-3 blocks bd-4   # Middleware needs routes
+bd dep add bd-2 blocks bd-5   # Tests need model
+bd dep add bd-3 blocks bd-5   # Tests need routes
+bd dep add bd-4 blocks bd-5   # Tests need middleware
+bd dep add bd-5 blocks bd-1   # Epic done when tests pass
+
+# Verify the trail:
+bd dep tree bd-1
+bd ready --json  # Should show bd-2 is ready!
+```
+
+*sniff sniff* The trail is set! 🐕‍🦺
+
+## 🚨 ERROR HANDLING
+
+Even bloodhounds sometimes lose the scent:
+
+- **Issue not found**: Double-check the bd-X number with `bd list --json`
+- **Cycle detected**: Run `bd dep cycles` to find and break the loop
+- **Dependency conflict**: Visualize with `bd dep tree` first
+- **Too many blockers**: Consider if the issue is too big - split it up!
+
+When in doubt, `bd list --json` and start fresh!
+
+Now go follow that scent! 🐕‍🦺✨
+
+"""
+
+        prompt_additions = callbacks.on_load_prompt()
+        if len(prompt_additions):
+            result += "\n".join(prompt_additions)
+        return result