code-puppy 0.0.348__py3-none-any.whl → 0.0.361__py3-none-any.whl

code_puppy/agents/pack/watchdog.py

@@ -0,0 +1,367 @@
+"""Watchdog - The QA critic that guards code quality! 🐕‍🦺
+
+This vigilant guardian ensures tests exist, pass, and cover the right things.
+No untested code shall pass on Watchdog's watch!
+"""
+
+from code_puppy.config import get_puppy_name
+
+from ... import callbacks
+from ..base_agent import BaseAgent
+
+
+class WatchdogAgent(BaseAgent):
+    """Watchdog - Vigilant guardian of code quality.
+
+    Ensures tests exist, pass, and actually test the right things.
+    The QA critic in the pack workflow - no untested code escapes!
+    """
+
+    @property
+    def name(self) -> str:
+        return "watchdog"
+
+    @property
+    def display_name(self) -> str:
+        return "Watchdog 🐕‍🦺"
+
+    @property
+    def description(self) -> str:
+        return (
+            "QA critic - vigilant guardian that ensures tests pass and "
+            "quality standards are met"
+        )
+
+    def get_available_tools(self) -> list[str]:
+        """Get the list of tools available to Watchdog."""
+        return [
+            # Find test files and explore structure
+            "list_files",
+            # Review test code and coverage
+            "read_file",
+            # Find test patterns, untested code, TODO comments
+            "grep",
+            # Run the tests!
+            "agent_run_shell_command",
+            # Explain QA findings - very important!
+            "agent_share_your_reasoning",
+        ]
+
+    def get_system_prompt(self) -> str:
+        """Get Watchdog's system prompt."""
+        puppy_name = get_puppy_name()
+
+        result = f"""
+You are {puppy_name} as Watchdog 🐕‍🦺 - the vigilant QA critic who guards the codebase!
+
+*alert ears* 👂 I stand guard over code quality! My job is to ensure tests exist, pass, and actually test the right things. No untested code gets past me! I'm the final checkpoint before code can be merged.
+
+## 🐕‍🦺 MY MISSION
+
+I am the QA critic in the pack workflow. When Husky finishes coding, I inspect the work:
+- Are there tests for the new code?
+- Do the tests actually test the right things?
+- Are edge cases covered?
+- Do ALL tests pass (including existing ones)?
+- Does the change break anything else?
+
+## 🎯 QA FOCUS AREAS
+
+### 1. Test Existence
+- Every new function/method should have corresponding tests
+- New files should have corresponding test files
+- No "we'll add tests later" excuses!
+
+### 2. Test Quality
+- Tests should actually verify behavior, not just call code
+- Assertions should be meaningful (not just `assert True`)
+- Test names should describe what they test
+- Look for test smells: empty tests, commented-out assertions
+
+### 3. Test Coverage
+- Happy path covered? ✅
+- Error cases covered? ✅
+- Edge cases covered? ✅
+- Boundary conditions tested? ✅
+
+### 4. Test Passing
+- ALL tests must pass, not just new ones
+- No flaky tests allowed
+- No skipped tests without good reason
+
+### 5. Integration Concerns
+- Does the change break existing tests?
+- Are integration tests needed?
+- Does it play well with existing code?
+
+## 🔍 MY QA PROCESS
+
+### Step 1: Receive Context
+```
+Worktree: ../bd-42
+BD Issue: bd-42 - Implement OAuth Core
+Files Changed: oauth_core.py, token_manager.py
+```
+
+### Step 2: Find Test Files
+```bash
+# Look for related test files
+ls -la tests/
+find . -name "test_*.py" -o -name "*_test.py"
+find . -name "*.test.ts" -o -name "*.spec.ts"
+```
+
+### Step 3: Check Test Coverage
+```bash
+# Read the implementation to know what needs testing
+cat oauth_core.py  # What functions exist?
+cat tests/test_oauth_core.py  # Are they all tested?
+```
+
+### Step 4: Run the Tests!
+```bash
+# Python projects
+uv run pytest tests/ -v
+uv run pytest tests/test_oauth.py -v  # Specific file
+pytest --tb=short  # Shorter tracebacks
+
+# JavaScript/TypeScript projects (ALWAYS use --silent for full suite!)
+npm test -- --silent  # Full suite
+npm test -- tests/oauth.test.ts  # Single file (can be verbose)
+
+# Check for test configuration
+cat pyproject.toml | grep -A 20 "\\[tool.pytest"
+cat package.json | grep -A 10 "scripts"
+```
+
+### Step 5: Provide Structured Feedback
+
+## 📋 FEEDBACK FORMAT
+
+```markdown
+## QA Review: bd-42 (OAuth Core)
+
+### Verdict: APPROVE ✅ | CHANGES_REQUESTED ❌
+
+### Test Results:
+- Tests found: 12
+- Tests passed: 12 ✅
+- Tests failed: 0
+- Coverage: oauth_core.py fully covered
+
+### Issues (if any):
+1. [MUST FIX] Missing tests for error handling in `oauth_core.py:validate_token()`
+2. [MUST FIX] `test_oauth_flow.py` fails: AssertionError at line 45
+3. [SHOULD FIX] No edge case tests for empty token string
+4. [NICE TO HAVE] Consider adding integration test for full OAuth flow
+
+### Commands Run:
+- `uv run pytest tests/test_oauth.py -v` → PASSED (8/8)
+- `uv run pytest tests/ -k oauth` → 2 FAILED
+- `uv run pytest tests/test_integration.py` → PASSED (4/4)
+
+### Recommendations:
+- Add test for `validate_token()` with expired token
+- Fix assertion in `test_token_refresh` (expected vs actual swapped)
+```
+
+## 🐾 TEST PATTERNS TO CHECK
+
+### Python Test Patterns
+```bash
+# Find test files
+find . -name "test_*.py" -o -name "*_test.py"
+
+# Check for test functions
+grep -r "def test_" tests/
+grep -r "async def test_" tests/
+
+# Look for fixtures
+grep -r "@pytest.fixture" tests/
+
+# Find TODO/FIXME in tests (bad smell!)
+grep -rn "TODO\\|FIXME\\|skip\\|xfail" tests/
+```
+
+### JavaScript/TypeScript Test Patterns
+```bash
+# Find test files
+find . -name "*.test.ts" -o -name "*.test.js" -o -name "*.spec.ts"
+
+# Check for test functions
+grep -r "it(\\|test(\\|describe(" tests/
+grep -r "it.skip\\|test.skip\\|describe.skip" tests/  # Skipped tests!
+```
+
+### Coverage Verification
+```bash
+# For each new function, verify a test exists
+# Implementation:
+grep "def validate_token" oauth_core.py
+# Test:
+grep "test_validate_token\\|test.*validate.*token" tests/
+```
+
+## ⚠️ RED FLAGS I WATCH FOR
+
+### Instant CHANGES_REQUESTED:
+- **No tests at all** for new code
+- **Tests fail** (any of them!)
+- **Empty test functions** that don't assert anything
+- **Commented-out tests** without explanation
+- **`skip` or `xfail`** without documented reason
+
+### Yellow Flags (SHOULD FIX):
+- Missing edge case tests
+- No error handling tests
+- Weak assertions (`assert x is not None` but not checking value)
+- Test names don't describe what they test
+- Missing integration tests for features that touch multiple modules
+
+### Green Flags (Good to See!):
+- Comprehensive happy path tests
+- Error case coverage
+- Boundary condition tests
+- Clear test naming
+- Good use of fixtures/mocks
+- Both unit AND integration tests
+
+## 🔄 INTEGRATION WITH PACK
+
+### My Place in the Workflow:
+```
+1. Husky codes in worktree (../bd-42)
+2. Shepherd reviews the code (APPROVE)
+3. >>> WATCHDOG INSPECTS <<< (That's me! 🐕‍🦺)
+4. If APPROVE → Retriever creates PR
+5. If CHANGES_REQUESTED → Husky fixes, back to step 2
+```
+
+### What I Receive:
+- Worktree path (e.g., `../bd-42`)
+- BD issue context (what was supposed to be implemented)
+- List of changed files
+
+### What I Return:
+- **APPROVE**: Tests exist, pass, and cover the changes adequately
+- **CHANGES_REQUESTED**: Specific issues that must be fixed
+
+### Working with Husky:
+When I request changes, I'm specific:
+```markdown
+### Required Fixes:
+1. Add test for `oauth_core.py:refresh_token()` - currently 0 tests
+2. Fix `test_validate_token` - expects string, gets None on line 45
+3. Add edge case test for expired token (< current_time)
+```
+
+Husky can then address exactly what I found!
+
+## 🧪 RUNNING TESTS BY LANGUAGE
+
+### Python
+```bash
+# Full test suite
+uv run pytest
+uv run pytest -v  # Verbose
+uv run pytest -x  # Stop on first failure
+uv run pytest --tb=short  # Shorter tracebacks
+
+# Specific file
+uv run pytest tests/test_oauth.py -v
+
+# Specific test
+uv run pytest tests/test_oauth.py::test_validate_token -v
+
+# By keyword
+uv run pytest -k "oauth" -v
+uv run pytest -k "not slow" -v
+
+# With coverage (if configured)
+uv run pytest --cov=src --cov-report=term-missing
+```
+
+### JavaScript/TypeScript
+```bash
+# IMPORTANT: Use --silent for full suite to avoid output overload!
+npm test -- --silent
+npm run test -- --silent
+yarn test --silent
+
+# Single file (can be verbose)
+npm test -- tests/oauth.test.ts
+npm test -- --testPathPattern="oauth"
+
+# Watch mode (for development)
+npm test -- --watch
+
+# With coverage
+npm test -- --coverage --silent
+```
+
+### Go
+```bash
+go test ./...
+go test ./... -v  # Verbose
+go test ./... -cover  # With coverage
+go test -run TestOAuth ./...  # Specific test
+```
+
+### Rust
+```bash
+cargo test
+cargo test -- --nocapture  # See println! output
+cargo test oauth  # Tests matching "oauth"
+```
+
+## 🐕‍🦺 WATCHDOG PRINCIPLES
+
+1. **No untested code shall pass!** - My primary directive
+2. **Run tests, don't just read them** - Trust but verify
+3. **Be specific in feedback** - "Add test for X" not "needs more tests"
+4. **Check BOTH new and existing tests** - Changes can break things
+5. **Quality over quantity** - 5 good tests beat 20 bad ones
+6. **Edge cases matter** - Happy path alone isn't enough
+7. **Report everything** - Use `agent_share_your_reasoning` liberally
+
+## 📝 EXAMPLE SESSION
+
+```
+Pack Leader: "Review tests for bd-42 (OAuth Core) in ../bd-42"
+
+Watchdog thinks:
+- Need to find what files were changed
+- Find corresponding test files
+- Check test coverage for new code
+- Run all tests
+- Provide structured feedback
+```
+
+```bash
+# Navigate and explore
+cd ../bd-42
+git diff --name-only main  # See what changed
+
+# Find tests
+ls tests/
+grep -l "oauth" tests/
+
+# Check what needs testing
+grep "def " oauth_core.py  # Functions in implementation
+grep "def test_" tests/test_oauth_core.py  # Functions in tests
+
+# RUN THE TESTS!
+uv run pytest tests/ -v
+```
+
+*ears perk up* All tests pass? Code is covered? Then APPROVE! ✅
+
+*growls softly* Tests missing or failing? CHANGES_REQUESTED! ❌
+
+*wags tail* I take my guard duty seriously! Quality code only! 🐕‍🦺✨
+"""
+
+        prompt_additions = callbacks.on_load_prompt()
+        if len(prompt_additions):
+            result += "\n".join(prompt_additions)
+        return result

code_puppy/agents/subagent_stream_handler.py

@@ -0,0 +1,276 @@
+"""Silenced event stream handler for sub-agents.
+
+This handler suppresses all console output but still:
+- Updates SubAgentConsoleManager with status/metrics
+- Fires stream_event callbacks for the frontend emitter plugin
+- Tracks tool calls, tokens, and status changes
+
+Usage:
+    >>> from code_puppy.agents.subagent_stream_handler import subagent_stream_handler
+    >>> # In agent run:
+    >>> await subagent_stream_handler(ctx, events, session_id="my-session-123")
+"""
+
+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,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Callback Helper
+# =============================================================================
+
+
+def _fire_callback(event_type: str, event_data: Any, session_id: Optional[str]) -> None:
+    """Fire stream_event callback non-blocking.
+
+    Schedules the callback to run asynchronously without waiting for it.
+    Silently ignores errors if no event loop is running or if the callback
+    system is unavailable.
+
+    Args:
+        event_type: Type of the event ('part_start', 'part_delta', 'part_end')
+        event_data: Dictionary containing event-specific data
+        session_id: Optional session ID for the sub-agent
+    """
+    try:
+        from code_puppy import callbacks
+
+        loop = asyncio.get_running_loop()
+        loop.create_task(callbacks.on_stream_event(event_type, event_data, session_id))
+    except RuntimeError:
+        # No event loop running - this can happen during shutdown
+        logger.debug("No event loop available for stream event callback")
+    except ImportError:
+        # Callbacks module not available
+        logger.debug("Callbacks module not available for stream event")
+    except Exception as e:
+        # Don't let callback errors break the stream handler
+        logger.debug(f"Error firing stream event callback: {e}")
+
+
+# =============================================================================
+# Token Estimation
+# =============================================================================
+
+
+def _estimate_tokens(content: str) -> int:
+    """Estimate token count from content string.
+
+    Uses a rough heuristic: ~4 characters per token for English text.
+    This is a ballpark estimate - actual tokenization varies by model.
+
+    Args:
+        content: The text content to estimate tokens for
+
+    Returns:
+        Estimated token count (minimum 1 for non-empty content)
+    """
+    if not content:
+        return 0
+    # Rough estimate: 4 chars = 1 token, minimum 1 for any content
+    return max(1, len(content) // 4)
+
+
+# =============================================================================
+# Main Handler
+# =============================================================================
+
+
+async def subagent_stream_handler(
+    ctx: RunContext,
+    events: AsyncIterable[Any],
+    session_id: Optional[str] = None,
+) -> None:
+    """Silent event stream handler for sub-agents.
+
+    Processes streaming events without producing any console output.
+    Updates the SubAgentConsoleManager with status and metrics, and fires
+    stream_event callbacks for any registered listeners.
+
+    Args:
+        ctx: The pydantic-ai run context
+        events: Async iterable of streaming events (PartStartEvent,
+                PartDeltaEvent, PartEndEvent)
+        session_id: Session ID of the sub-agent for console manager updates.
+                   If None, falls back to get_session_context().
+    """
+    # Late import to avoid circular dependencies
+    from code_puppy.messaging import get_session_context
+    from code_puppy.messaging.subagent_console import SubAgentConsoleManager
+
+    manager = SubAgentConsoleManager.get_instance()
+
+    # Resolve session_id, falling back to context if not provided
+    effective_session_id = session_id or get_session_context()
+
+    # Metrics tracking
+    token_count = 0
+    tool_call_count = 0
+    active_tool_parts: set[int] = set()  # Track active tool call indices
+
+    async for event in events:
+        try:
+            await _handle_event(
+                event=event,
+                manager=manager,
+                session_id=effective_session_id,
+                token_count=token_count,
+                tool_call_count=tool_call_count,
+                active_tool_parts=active_tool_parts,
+            )
+
+            # Update metrics from returned values
+            # (we need to track these at this level since they're modified in _handle_event)
+            if isinstance(event, PartStartEvent):
+                if isinstance(event.part, ToolCallPart):
+                    tool_call_count += 1
+                    active_tool_parts.add(event.index)
+
+            elif isinstance(event, PartDeltaEvent):
+                delta = event.delta
+                if isinstance(delta, (TextPartDelta, ThinkingPartDelta)):
+                    if delta.content_delta:
+                        token_count += _estimate_tokens(delta.content_delta)
+
+            elif isinstance(event, PartEndEvent):
+                active_tool_parts.discard(event.index)
+
+        except Exception as e:
+            # Log but don't crash on event handling errors
+            logger.debug(f"Error handling stream event: {e}")
+            continue
+
+
+async def _handle_event(
+    event: Any,
+    manager: Any,  # SubAgentConsoleManager
+    session_id: Optional[str],
+    token_count: int,
+    tool_call_count: int,
+    active_tool_parts: set[int],
+) -> None:
+    """Handle a single streaming event.
+
+    Updates the console manager and fires callbacks for each event type.
+
+    Args:
+        event: The streaming event to handle
+        manager: SubAgentConsoleManager instance
+        session_id: Session ID for updates
+        token_count: Current token count
+        tool_call_count: Current tool call count
+        active_tool_parts: Set of active tool call indices
+    """
+    if session_id is None:
+        # Can't update manager without session_id
+        logger.debug("No session_id available for stream event")
+        return
+
+    # -------------------------------------------------------------------------
+    # PartStartEvent - Track new parts and update status
+    # -------------------------------------------------------------------------
+    if isinstance(event, PartStartEvent):
+        part = event.part
+        event_data = {
+            "index": event.index,
+            "part_type": type(part).__name__,
+        }
+
+        if isinstance(part, ThinkingPart):
+            manager.update_agent(session_id, status="thinking")
+            event_data["content"] = getattr(part, "content", None)
+
+        elif isinstance(part, TextPart):
+            manager.update_agent(session_id, status="running")
+            event_data["content"] = getattr(part, "content", None)
+
+        elif isinstance(part, ToolCallPart):
+            # tool_call_count is updated in the main handler
+            manager.update_agent(
+                session_id,
+                status="tool_calling",
+                tool_call_count=tool_call_count + 1,  # +1 for this new one
+                current_tool=part.tool_name,
+            )
+            event_data["tool_name"] = part.tool_name
+            event_data["tool_call_id"] = getattr(part, "tool_call_id", None)
+
+        _fire_callback("part_start", event_data, session_id)
+
+    # -------------------------------------------------------------------------
+    # PartDeltaEvent - Track content deltas and update metrics
+    # -------------------------------------------------------------------------
+    elif isinstance(event, PartDeltaEvent):
+        delta = event.delta
+        event_data = {
+            "index": event.index,
+            "delta_type": type(delta).__name__,
+        }
+
+        if isinstance(delta, TextPartDelta):
+            content_delta = delta.content_delta
+            if content_delta:
+                # Token count is updated in main handler
+                new_token_count = token_count + _estimate_tokens(content_delta)
+                manager.update_agent(session_id, token_count=new_token_count)
+                event_data["content_delta"] = content_delta
+
+        elif isinstance(delta, ThinkingPartDelta):
+            content_delta = delta.content_delta
+            if content_delta:
+                new_token_count = token_count + _estimate_tokens(content_delta)
+                manager.update_agent(session_id, token_count=new_token_count)
+                event_data["content_delta"] = content_delta
+
+        elif isinstance(delta, ToolCallPartDelta):
+            # Tool call deltas might have partial args
+            event_data["args_delta"] = getattr(delta, "args_delta", None)
+            event_data["tool_name_delta"] = getattr(delta, "tool_name_delta", None)
+
+        _fire_callback("part_delta", event_data, session_id)
+
+    # -------------------------------------------------------------------------
+    # PartEndEvent - Track part completion and update status
+    # -------------------------------------------------------------------------
+    elif isinstance(event, PartEndEvent):
+        event_data = {
+            "index": event.index,
+            "next_part_kind": getattr(event, "next_part_kind", None),
+        }
+
+        # If this was a tool call part ending, check if we should reset status
+        if event.index in active_tool_parts:
+            # Remove this index from active parts (done in main handler)
+            # If no more active tool parts after removal, reset to running
+            remaining_active = active_tool_parts - {event.index}
+            if not remaining_active:
+                manager.update_agent(
+                    session_id,
+                    current_tool=None,
+                    status="running",
+                )
+
+        _fire_callback("part_end", event_data, session_id)
+
+
+# =============================================================================
+# Exports
+# =============================================================================
+
+__all__ = [
+    "subagent_stream_handler",
+]

code_puppy/api/__init__.py

@@ -0,0 +1,13 @@
+"""Code Puppy REST API module.
+
+This module provides a FastAPI-based REST API for Code Puppy configuration,
+sessions, commands, and real-time WebSocket communication.
+
+Exports:
+    create_app: Factory function to create the FastAPI application
+    main: Entry point to run the server
+"""
+
+from code_puppy.api.app import create_app
+
+__all__ = ["create_app"]