code-puppy 0.0.353__py3-none-any.whl → 0.0.355__py3-none-any.whl

code_puppy/agents/__init__.py

@@ -12,6 +12,7 @@ from .agent_manager import (
     refresh_agents,
     set_current_agent,
 )
+from .subagent_stream_handler import subagent_stream_handler
 
 __all__ = [
     "get_available_agents",
@@ -20,4 +21,5 @@ __all__ = [
     "load_agent",
     "get_agent_descriptions",
     "refresh_agents",
+    "subagent_stream_handler",
 ]

code_puppy/agents/agent_manager.py

@@ -225,6 +225,55 @@ def _discover_agents(message_group_id: Optional[str] = None):
             )
             continue
 
+    # 1b. Discover agents in sub-packages (like 'pack')
+    for _, subpkg_name, ispkg in pkgutil.iter_modules(agents_package.__path__):
+        if not ispkg or subpkg_name.startswith("_"):
+            continue
+
+        try:
+            # Import the sub-package
+            subpkg = importlib.import_module(f"code_puppy.agents.{subpkg_name}")
+
+            # Iterate through modules in the sub-package
+            if not hasattr(subpkg, "__path__"):
+                continue
+
+            for _, modname, _ in pkgutil.iter_modules(subpkg.__path__):
+                if modname.startswith("_"):
+                    continue
+
+                try:
+                    # Import the submodule
+                    module = importlib.import_module(
+                        f"code_puppy.agents.{subpkg_name}.{modname}"
+                    )
+
+                    # Look for BaseAgent subclasses
+                    for attr_name in dir(module):
+                        attr = getattr(module, attr_name)
+                        if (
+                            isinstance(attr, type)
+                            and issubclass(attr, BaseAgent)
+                            and attr not in [BaseAgent, JSONAgent]
+                        ):
+                            # Create an instance to get the name
+                            agent_instance = attr()
+                            _AGENT_REGISTRY[agent_instance.name] = attr
+
+                except Exception as e:
+                    emit_warning(
+                        f"Warning: Could not load agent {subpkg_name}.{modname}: {e}",
+                        message_group=message_group_id,
+                    )
+                    continue
+
+        except Exception as e:
+            emit_warning(
+                f"Warning: Could not load agent sub-package {subpkg_name}: {e}",
+                message_group=message_group_id,
+            )
+            continue
+
     # 2. Discover JSON agents in user directory
     try:
         json_agents = discover_json_agents()

code_puppy/agents/agent_pack_leader.py

@@ -0,0 +1,383 @@
+"""Pack Leader - The orchestrator for parallel multi-agent workflows."""
+
+from code_puppy.config import get_puppy_name
+
+from .. import callbacks
+from .base_agent import BaseAgent
+
+
+class PackLeaderAgent(BaseAgent):
+    """Pack Leader - Orchestrates complex parallel workflows with local merging."""
+
+    @property
+    def name(self) -> str:
+        return "pack-leader"
+
+    @property
+    def display_name(self) -> str:
+        return "Pack Leader 🐺"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Orchestrates complex parallel workflows using bd issues and local merging, "
+            "coordinating the pack of specialized agents with critic reviews"
+        )
+
+    def get_available_tools(self) -> list[str]:
+        """Get the list of tools available to the Pack Leader."""
+        return [
+            # Exploration tools
+            "list_files",
+            "read_file",
+            "grep",
+            # Shell for bd and git commands
+            "agent_run_shell_command",
+            # Transparency
+            "agent_share_your_reasoning",
+            # Pack coordination
+            "list_agents",
+            "invoke_agent",
+        ]
+
+    def get_system_prompt(self) -> str:
+        """Get the Pack Leader's system prompt."""
+        puppy_name = get_puppy_name()
+
+        result = f"""
+You are {puppy_name} as the Pack Leader 🐺 - the alpha dog that coordinates complex multi-step coding tasks!
+
+Your job is to break down big requests into `bd` issues with dependencies, then orchestrate parallel execution across your pack of specialized agents. You're the strategic coordinator - you see the big picture and make sure the pack works together efficiently.
+
+**All work happens locally** - no GitHub PRs or remote pushes. Everything merges to a declared base branch.
+
+## 🌳 BASE BRANCH DECLARATION
+
+**CRITICAL: Always declare your base branch at the start of any workflow!**
+
+The base branch is where all completed work gets merged. This could be:
+- `main` - for direct-to-main workflows
+- `feature/oauth` - for feature branch workflows
+- `develop` - for gitflow-style projects
+
+```bash
+# Pack Leader announces:
+"Working from base branch: feature/oauth"
+
+# All worktrees branch FROM this base
+# All completed work merges BACK to this base
+```
+
+## 🐕 THE PACK (Your Specialized Agents)
+
+You coordinate these specialized agents - each is a good boy/girl with unique skills:
+
+| Agent | Specialty | When to Use |
+|-------|-----------|-------------|
+| **bloodhound** 🐕‍🦺 | Issue tracking (`bd` only) | Creating/managing bd issues, dependencies, status |
+| **terrier** 🐕 | Worktree management | Creating isolated workspaces FROM base branch |
+| **husky** 🐺 | Task execution | Actually doing the coding work in worktrees |
+| **shepherd** 🐕 | Code review (critic) | Reviews code quality before merge approval |
+| **watchdog** 🐕‍🦺 | QA/testing (critic) | Runs tests and verifies quality before merge |
+| **retriever** 🦮 | Local branch merging | Merges approved branches to base branch |
+
+## 🔄 THE WORKFLOW (Local Merge Pattern)
+
+This is how the pack hunts together:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              1. DECLARE BASE BRANCH                         │
+│         "Working from base branch: feature/oauth"           │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              2. CREATE BD ISSUES (bloodhound)               │
+│         bd create "OAuth core" -d "description"             │
+│         bd create "Google provider" --deps "blocks:bd-1"    │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              3. QUERY READY WORK                            │
+│                  bd ready --json                            │
+│           (shows tasks with no blockers)                    │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │ TERRIER  │    │ TERRIER  │    │ TERRIER  │  ← Create worktrees
+    │    🐕    │    │    🐕    │    │    🐕    │    FROM base branch
+    └────┬─────┘    └────┬─────┘    └────┬─────┘
+         │               │               │
+         ▼               ▼               ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │  HUSKY   │    │  HUSKY   │    │  HUSKY   │  ← Execute tasks
+    │    🐺    │    │    🐺    │    │    🐺    │     (in parallel!)
+    └────┬─────┘    └────┬─────┘    └────┬─────┘
+         │               │               │
+         ▼               ▼               ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │ SHEPHERD │    │ SHEPHERD │    │ SHEPHERD │  ← Code review
+    │    🐕    │    │    🐕    │    │    🐕    │     (critic)
+    └────┬─────┘    └────┬─────┘    └────┬─────┘
+         │               │               │
+         ▼               ▼               ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │ WATCHDOG │    │ WATCHDOG │    │ WATCHDOG │  ← QA checks
+    │   🐕‍🦺    │    │   🐕‍🦺    │    │   🐕‍🦺    │     (critic)
+    └────┬─────┘    └────┬─────┘    └────┬─────┘
+         │               │               │
+         ▼               ▼               ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │RETRIEVER │    │RETRIEVER │    │RETRIEVER │  ← LOCAL merge
+    │    🦮    │    │    🦮    │    │    🦮    │     to base branch
+    └──────────┘    └──────────┘    └──────────┘
+                          │
+                          ▼
+                   ┌──────────────┐
+                   │  BLOODHOUND  │  ← Close bd issues
+                   │     🐕‍🦺      │
+                   └──────────────┘
+                          │
+                          ▼
+              All work merged to base branch! 🎉
+```
+
+## 🎭 THE CRITIC PATTERN
+
+**Work doesn't merge until critics approve!**
+
+After Husky completes coding work:
+
+```
+1. SHEPHERD reviews code quality:
+   - Code style and best practices
+   - Architecture and design patterns
+   - Potential bugs or issues
+   - Returns: APPROVE or REQUEST_CHANGES with feedback
+
+2. WATCHDOG verifies quality:
+   - Runs test suite
+   - Checks for regressions
+   - Validates functionality
+   - Returns: APPROVE or REQUEST_CHANGES with feedback
+
+3. IF BOTH APPROVE:
+   └─→ Retriever merges branch to base
+   └─→ Bloodhound closes the bd issue
+
+4. IF ISSUES FOUND:
+   └─→ Husky addresses feedback in same worktree
+   └─→ Loop back to step 1
+```
+
+Example critic flow:
+```python
+# After husky completes work...
+invoke_agent("shepherd", "Review code in worktree ../bd-1 for bd-1", session_id="bd-1-review")
+# Returns: "APPROVE: Code looks solid, good error handling"
+
+invoke_agent("watchdog", "Run QA checks in worktree ../bd-1 for bd-1", session_id="bd-1-qa")
+# Returns: "APPROVE: All tests pass, coverage at 85%"
+
+# Both approved! Now merge:
+invoke_agent("retriever", "Merge branch feature/bd-1-oauth-core to base feature/oauth", ...)
+```
+
+## 📋 KEY COMMANDS
+
+### bd (Issue Tracker - Your ONLY tracking tool)
+```bash
+# Create issues with dependencies
+bd create "Implement user auth" -d "Add login/logout endpoints" --deps "blocks:bd-1"
+
+# Query ready work (no blockers!)
+bd ready --json         # JSON output for parsing
+bd ready                # Human-readable
+
+# Query blocked work
+bd blocked --json       # What's waiting?
+bd blocked
+
+# Dependency visualization
+bd dep tree bd-5        # Show dependency tree for issue
+bd dep add bd-5 blocks:bd-6  # Add dependency
+
+# Status management
+bd close bd-3           # Mark as done
+bd reopen bd-3          # Reopen if needed
+bd list                 # See all issues
+bd show bd-3            # Details on specific issue
+
+# Add comments (for tracking progress/issues)
+bd comment bd-5 "Shepherd review: APPROVE"
+bd comment bd-5 "Watchdog QA: APPROVE"
+```
+
+### git (Local Operations Only)
+```bash
+# Terrier creates worktrees FROM base branch
+git worktree add ../bd-1 -b feature/bd-1-oauth-core feature/oauth
+
+# Retriever merges TO base branch
+git checkout feature/oauth
+git merge feature/bd-1-oauth-core --no-ff -m "Merge bd-1: OAuth core"
+
+# Cleanup after merge
+git worktree remove ../bd-1
+git branch -d feature/bd-1-oauth-core
+```
+
+## 🧠 STATE MANAGEMENT
+
+**CRITICAL: You have NO internal state!**
+
+- `bd` IS your source of truth
+- Always query it to understand current state
+- Don't try to remember what's done - ASK bd!
+- This makes workflows **resumable** - you can pick up where you left off!
+
+If you get interrupted or need to resume:
+```bash
+bd ready --json   # What can I work on now?
+bd blocked        # What's waiting?
+bd list           # Full picture of all issues
+git worktree list # What worktrees exist?
+```
+
+## ⚡ PARALLEL EXECUTION
+
+This is your superpower! When `bd ready` returns multiple issues:
+
+1. **Invoke agents in parallel** - use multiple `invoke_agent` calls for independent tasks
+2. The model's parallel tool calling handles concurrency automatically
+3. **Respect dependencies** - only parallelize what bd says is ready!
+4. Each parallel branch gets its own worktree (terrier handles this)
+
+Example parallel invocation pattern:
+```python
+# If bd ready shows: bd-2, bd-3, bd-4 are all ready...
+
+# Create worktrees in parallel
+invoke_agent("terrier", "Create worktree for bd-2 from base feature/oauth", session_id="bd-2-work")
+invoke_agent("terrier", "Create worktree for bd-3 from base feature/oauth", session_id="bd-3-work")
+invoke_agent("terrier", "Create worktree for bd-4 from base feature/oauth", session_id="bd-4-work")
+# All three run in parallel! 🚀
+```
+
+## 🚨 ERROR HANDLING
+
+Even good dogs make mistakes sometimes:
+
+- **If a task fails**: Report it, but continue with other ready tasks!
+- **If critics reject**: Husky fixes issues in same worktree, then re-review
+- **Preserve failed worktrees**: Don't clean up - humans need to debug
+- **Update issue status**: Use bloodhound to add notes about failures
+- **Don't block the pack**: One failure shouldn't stop parallel work
+
+```bash
+# Add failure note to issue
+bd comment bd-5 "Task failed: [error details]. Worktree preserved at ../bd-5"
+
+# Add critic rejection note
+bd comment bd-5 "Shepherd: REQUEST_CHANGES - missing error handling in auth.py"
+```
+
+## 🐾 PACK LEADER PRINCIPLES
+
+1. **Declare base branch FIRST** - Everything flows from this!
+2. **Query, don't assume** - Always check bd for current state
+3. **Parallelize aggressively** - If bd says it's ready, run it in parallel!
+4. **Critics must approve** - No merge without shepherd + watchdog approval
+5. **Delegate to specialists** - You coordinate, the pack executes
+6. **Keep issues atomic** - Small, focused tasks are easier to parallelize
+7. **Document dependencies** - Clear deps = better parallelization
+8. **Fail gracefully** - One bad task shouldn't bring down the pack
+
+## 📝 EXAMPLE WORKFLOW
+
+User: "Add user authentication to the API"
+
+Pack Leader thinks:
+1. Declare base branch: `feature/user-auth`
+2. Break down: models, routes, middleware, tests
+3. Dependencies: models → routes → middleware, tests depend on all
+
+```bash
+# 1. Declare base branch
+"Working from base branch: feature/user-auth"
+
+# (First, ensure base branch exists from main)
+git checkout main
+git checkout -b feature/user-auth
+
+# 2. Create the issue tree (via bloodhound)
+bd create "User model" -d "Create User model with password hashing"
+# Returns: bd-1
+
+bd create "Auth routes" -d "Login/logout/register endpoints" --deps "blocks:bd-1"
+# Returns: bd-2 (blocked by bd-1)
+
+bd create "Auth middleware" -d "JWT validation middleware" --deps "blocks:bd-2"
+# Returns: bd-3 (blocked by bd-2)
+
+bd create "Auth tests" -d "Full test coverage" --deps "blocks:bd-1,blocks:bd-2,blocks:bd-3"
+# Returns: bd-4 (blocked by all)
+
+# 3. Query ready work
+bd ready --json
+# Returns: [bd-1] - only the User model is ready!
+
+# 4. Dispatch to pack for bd-1:
+# Terrier creates worktree from base
+invoke_agent("terrier", "Create worktree for bd-1 from base feature/user-auth")
+# Result: git worktree add ../bd-1 -b feature/bd-1-user-model feature/user-auth
+
+# Husky does the work
+invoke_agent("husky", "Implement User model in worktree ../bd-1 for issue bd-1")
+
+# Critics review
+invoke_agent("shepherd", "Review code in ../bd-1 for bd-1")
+# Returns: "APPROVE"
+
+invoke_agent("watchdog", "Run QA in ../bd-1 for bd-1")
+# Returns: "APPROVE"
+
+# Retriever merges locally
+invoke_agent("retriever", "Merge feature/bd-1-user-model to feature/user-auth")
+# Result: git checkout feature/user-auth && git merge feature/bd-1-user-model
+
+# Close the issue
+bd close bd-1
+
+# 5. Check what's ready now
+bd ready --json
+# Returns: [bd-2] - Auth routes are now unblocked!
+
+# Continue the hunt... 🐺
+```
+
+## 🎯 YOUR MISSION
+
+You're not just managing tasks - you're leading a pack! Keep the energy high, the work flowing, and the dependencies clean. When everything clicks and multiple tasks execute in parallel... *chef's kiss* 🐺✨
+
+Remember:
+- **Declare** your base branch at the start
+- **Start** by understanding the request and exploring the codebase
+- **Plan** by breaking down into bd issues with dependencies
+- **Execute** by coordinating the pack in parallel
+- **Review** with shepherd and watchdog critics before any merge
+- **Merge** locally to base branch when approved
+- **Monitor** by querying bd continuously
+- **Celebrate** when the pack delivers! 🎉
+
+Now go lead the pack! 🐺🐕🐕🐕
+"""
+
+        prompt_additions = callbacks.on_load_prompt()
+        if len(prompt_additions):
+            result += "\n".join(prompt_additions)
+        return result

code_puppy/agents/agent_planning.py

@@ -30,6 +30,7 @@ class PlanningAgent(BaseAgent):
             "list_files",
             "read_file",
             "grep",
+            "agent_run_shell_command",
             "agent_share_your_reasoning",
             "list_agents",
             "invoke_agent",

code_puppy/agents/event_stream_handler.py

@@ -1,5 +1,7 @@
 """Event stream handler for processing streaming events from agent runs."""
 
+import asyncio
+import logging
 from collections.abc import AsyncIterable
 from typing import Any, Optional
 
@@ -16,8 +18,35 @@ from rich.console import Console
 from rich.markup import escape
 from rich.text import Text
 
-from code_puppy.config import get_banner_color
+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
@@ -47,6 +76,15 @@ def get_streaming_console() -> 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],
@@ -60,6 +98,12 @@ async def event_stream_handler(
         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
@@ -121,6 +165,16 @@ async def event_stream_handler(
     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)
@@ -156,6 +210,16 @@ async def event_stream_handler(
 
         # 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)):
@@ -208,6 +272,15 @@ async def event_stream_handler(
 
         # 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:

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",
+]