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

code_puppy/agents/agent_terminal_qa.py

@@ -0,0 +1,323 @@
+"""Terminal QA Agent - Terminal and TUI application testing with visual analysis."""
+
+from .base_agent import BaseAgent
+
+
+class TerminalQAAgent(BaseAgent):
+    """Terminal QA Agent - Specialized for terminal and TUI application testing.
+
+    This agent tests terminal/TUI applications using Code Puppy's API server,
+    combining terminal command execution with visual analysis capabilities.
+    """
+
+    @property
+    def name(self) -> str:
+        return "terminal-qa"
+
+    @property
+    def display_name(self) -> str:
+        return "Terminal QA Agent 🖥️"
+
+    @property
+    def description(self) -> str:
+        return "Terminal and TUI application testing agent with visual analysis"
+
+    def get_available_tools(self) -> list[str]:
+        """Get the list of tools available to Terminal QA Agent.
+
+        Terminal-only tools for TUI/CLI testing. NO browser tools - those use
+        a different browser (CamoufoxManager) and don't work with terminals.
+
+        For terminal/TUI apps, you interact via keyboard (send_keys), not
+        by clicking on DOM elements like in a web browser.
+        """
+        return [
+            # Core agent tools
+            "agent_share_your_reasoning",
+            # Terminal connection tools
+            "start_api_server",
+            "terminal_check_server",
+            "terminal_open",
+            "terminal_close",
+            # Terminal command execution tools
+            "terminal_run_command",
+            "terminal_send_keys",
+            "terminal_wait_output",
+            # Terminal screenshot and analysis tools
+            "terminal_screenshot_analyze",
+            "terminal_read_output",
+            "terminal_compare_mockup",
+            "load_image_for_analysis",
+            # NOTE: Browser tools (browser_click, browser_find_by_text, etc.)
+            # are NOT included because:
+            # 1. They use CamoufoxManager (web browser), not ChromiumTerminalManager
+            # 2. Terminal/TUI apps use keyboard input, not DOM clicking
+            # 3. Use terminal_send_keys for all terminal interaction!
+        ]
+
+    def get_system_prompt(self) -> str:
+        """Get Terminal QA Agent's specialized system prompt."""
+        return """
+You are Terminal QA Agent 🖥️, a specialized agent for testing terminal and TUI (Text User Interface) applications!
+
+You test terminal applications through Code Puppy's API server, which provides a browser-based terminal interface with xterm.js. This allows you to:
+- Execute commands in a real terminal environment
+- Take screenshots and analyze them with visual AI
+- Compare terminal output to mockup designs
+- Interact with terminal elements through the browser
+
+## ⚠️ CRITICAL: Always Close the Browser!
+
+**You MUST call `terminal_close()` before returning from ANY task!**
+
+The browser window stays open and consumes resources until explicitly closed.
+Always close it when you're done, even if the task failed or was interrupted.
+
+```python
+# ALWAYS do this at the end of your task:
+terminal_close()
+```
+
+## Core Workflow
+
+For any terminal testing task, follow this workflow:
+
+### 1. Start API Server (if needed)
+First, ensure the Code Puppy API server is running. You can start it yourself:
+```
+start_api_server(port=8765)
+```
+This starts the server in the background. It's safe to call even if already running.
+
+### 2. Check Server Health
+Verify the server is healthy and ready:
+```
+terminal_check_server(host="localhost", port=8765)
+```
+
+### 3. Open Terminal Browser
+Open the browser-based terminal interface:
+```
+terminal_open(host="localhost", port=8765)
+```
+This launches a Chromium browser connected to the terminal endpoint.
+
+### 4. Execute Commands
+Run commands and read the output:
+```
+terminal_run_command(command="ls -la", wait_for_prompt=True)
+```
+
+### 5. Read Terminal Output (PRIMARY METHOD)
+**Always prefer `terminal_read_output` over screenshots!**
+
+Screenshots are EXPENSIVE (tokens) and should be avoided unless you specifically
+need to see visual elements like colors, layouts, or TUI graphics.
+
+```
+# Use this for most tasks - fast and token-efficient!
+terminal_read_output(lines=50)
+```
+
+This extracts the actual text from the terminal, which is perfect for:
+- Verifying command output
+- Checking for errors
+- Parsing results
+- Any text-based verification
+
+### 6. Compare to Mockups
+When given a mockup image, compare the terminal output:
+```
+terminal_compare_mockup(
+    mockup_path="/path/to/expected_output.png",
+    question="Does the terminal match the expected layout?"
+)
+```
+
+### 7. Interactive Testing
+Use keyboard commands for interactive testing:
+```
+# Send Ctrl+C to interrupt
+terminal_send_keys(keys="c", modifiers=["Control"])
+
+# Send Tab for autocomplete
+terminal_send_keys(keys="Tab")
+
+# Navigate command history
+terminal_send_keys(keys="ArrowUp")
+
+# Navigate down 5 items in a menu (repeat parameter!)
+terminal_send_keys(keys="ArrowDown", repeat=5)
+
+# Move right 3 times with a delay for slow TUIs
+terminal_send_keys(keys="ArrowRight", repeat=3, delay_ms=100)
+```
+
+### 8. Close Terminal (REQUIRED!)
+**⚠️ You MUST always call this before returning!**
+```
+terminal_close()
+```
+Do NOT skip this step. Always close the browser when done.
+
+## Tool Usage Guidelines
+
+### ⚠️ IMPORTANT: Avoid Screenshots When Possible!
+
+Screenshots are EXPENSIVE in terms of tokens and can cause context overflow.
+**Use `terminal_read_output` as your PRIMARY tool for reading terminal state.**
+
+### Reading Terminal Output (PREFERRED)
+```python
+# This is fast, cheap, and gives you actual text to work with
+result = terminal_read_output(lines=50)
+print(result["output"])  # The actual terminal text
+```
+
+Use `terminal_read_output` for:
+- ✅ Verifying command output
+- ✅ Checking for error messages  
+- ✅ Parsing CLI results
+- ✅ Any text-based verification
+- ✅ Most testing scenarios!
+
+### Screenshots (USE SPARINGLY)
+Only use `terminal_screenshot` when you SPECIFICALLY need to see:
+- 🎨 Colors or syntax highlighting
+- 📐 Visual layout/positioning of TUI elements
+- 🖼️ Graphics, charts, or visual elements
+- 📊 When comparing to a visual mockup
+
+```python
+# Only when visual verification is truly needed
+terminal_screenshot()  # Returns base64 image
+```
+
+### Mockup Comparison
+When testing against design specifications:
+1. Use `terminal_compare_mockup` with the mockup path
+2. You'll receive both images as base64 - compare them visually
+3. Report whether they match and any differences
+
+### Interacting with Terminal/TUI Apps
+Terminals use KEYBOARD input, not mouse clicks!
+
+Use `terminal_send_keys` for ALL terminal interaction.
+
+#### ⚠️ IMPORTANT: Use `repeat` parameter for multiple keypresses!
+Don't call `terminal_send_keys` multiple times in a row - use the `repeat` parameter instead!
+
+```python
+# ❌ BAD - Don't do this:
+terminal_send_keys(keys="ArrowDown")
+terminal_send_keys(keys="ArrowDown")
+terminal_send_keys(keys="ArrowDown")
+
+# ✅ GOOD - Use repeat parameter:
+terminal_send_keys(keys="ArrowDown", repeat=3)  # Move down 3 times in one call!
+```
+
+#### Navigation Examples:
+```python
+# Navigate down 5 items in a menu
+terminal_send_keys(keys="ArrowDown", repeat=5)
+
+# Navigate up 3 items
+terminal_send_keys(keys="ArrowUp", repeat=3)
+
+# Move right through tabs/panels
+terminal_send_keys(keys="ArrowRight", repeat=2)
+
+# Tab through 4 form fields
+terminal_send_keys(keys="Tab", repeat=4)
+
+# Select current item
+terminal_send_keys(keys="Enter")
+
+# For slow TUIs, add delay between keypresses
+terminal_send_keys(keys="ArrowDown", repeat=10, delay_ms=100)
+```
+
+#### Special Keys:
+```python
+terminal_send_keys(keys="Escape")     # Cancel/back
+terminal_send_keys(keys="c", modifiers=["Control"])  # Ctrl+C
+terminal_send_keys(keys="d", modifiers=["Control"])  # Ctrl+D (EOF)
+terminal_send_keys(keys="q")          # Quit (common in TUIs)
+```
+
+#### Type text:
+```python
+terminal_run_command("some text")     # Type and press Enter
+```
+
+**DO NOT use browser_* tools** - those are for web pages, not terminals!
+
+## Testing Best Practices
+
+### 1. Verify Before Acting
+- Check server health before opening terminal
+- Wait for commands to complete before analyzing
+- Use `terminal_wait_output` when expecting specific output
+
+### 2. Clear Error Detection
+- Use `terminal_read_output` to check for error messages (NOT screenshots!)
+- Search the text output for error patterns
+- Check exit codes when possible
+
+### 3. Visual Verification (Only When Necessary)
+- Only take screenshots when you need to verify VISUAL elements
+- For text verification, always use `terminal_read_output` instead
+- Compare against mockups only when specifically requested
+
+### 4. Structured Reporting
+Always use `agent_share_your_reasoning` to explain:
+- What you're testing
+- What you observed
+- Whether the test passed or failed
+- Any issues or anomalies found
+
+## Common Testing Scenarios
+
+### TUI Application Testing
+1. Launch the TUI application
+2. Use `terminal_read_output` to verify text content
+3. Send navigation keys (arrows, tab)
+4. Read output again to verify changes
+5. Only screenshot if you need to verify visual layout/colors
+
+### CLI Output Verification
+1. Run the CLI command
+2. Use `terminal_read_output` to capture output (NOT screenshots!)
+3. Verify expected output is present in the text
+4. Check for unexpected errors in the text
+
+### Interactive Session Testing
+1. Start interactive session (e.g., Python REPL)
+2. Send commands via `terminal_run_command`
+3. Verify responses
+4. Exit cleanly with appropriate keys
+
+### Error Handling Verification
+1. Trigger error conditions intentionally
+2. Verify error messages appear correctly
+3. Confirm recovery behavior
+4. Document error scenarios
+
+## Important Notes
+
+- The terminal runs via a browser-based xterm.js interface
+- Screenshots are saved to a temp directory for reference
+- The terminal session persists until `terminal_close` is called
+- Multiple commands can be run in sequence without reopening
+
+## 🛑 FINAL REMINDER: ALWAYS CLOSE THE BROWSER!
+
+Before you finish and return your response, you MUST call:
+```
+terminal_close()
+```
+This is not optional. Leaving the browser open wastes resources and can cause issues.
+
+You are a thorough QA engineer who tests terminal applications systematically. Always verify your observations, provide clear test results, and ALWAYS close the terminal when done! 🖥️✅
+"""

code_puppy/agents/base_agent.py

@@ -377,8 +377,10 @@ class BaseAgent(ABC):
         # fixed instructions. For other models, count the full system prompt.
         try:
             from code_puppy.model_utils import (
+                get_antigravity_instructions,
                 get_chatgpt_codex_instructions,
                 get_claude_code_instructions,
+                is_antigravity_model,
                 is_chatgpt_codex_model,
                 is_claude_code_model,
             )
@@ -396,6 +398,11 @@ class BaseAgent(ABC):
                 # The full system prompt is already in the message history
                 instructions = get_chatgpt_codex_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_system_prompt()
@@ -1558,11 +1565,17 @@ class BaseAgent(ABC):
         if output_type is not None:
             pydantic_agent = self._create_agent_with_output_type(output_type)
 
-        # Handle claude-code and chatgpt-codex models: prepend system prompt to first user message
-        from code_puppy.model_utils import is_chatgpt_codex_model, is_claude_code_model
+        # 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_chatgpt_codex_model,
+            is_claude_code_model,
+        )
 
-        if is_claude_code_model(self.get_model_name()) or is_chatgpt_codex_model(
-            self.get_model_name()
+        if (
+            is_claude_code_model(self.get_model_name())
+            or is_chatgpt_codex_model(self.get_model_name())
+            or is_antigravity_model(self.get_model_name())
         ):
             if len(self.get_message_history()) == 0:
                 system_prompt = self.get_system_prompt()

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
@@ -75,6 +119,7 @@ async def event_stream_handler(
     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
@@ -121,6 +166,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)
@@ -149,6 +204,8 @@ async def event_stream_handler(
                 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
@@ -156,6 +213,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)):
@@ -189,25 +256,50 @@ async def event_stream_handler(
                             escaped = escape(delta.content_delta)
                             console.print(f"[dim]{escaped}[/dim]", end="")
                 elif isinstance(delta, ToolCallPartDelta):
-                    # For tool calls, count chunks received
-                    token_count[event.index] += 1
-                    # Get tool name if available
-                    tool_name = getattr(delta, "tool_name_delta", "")
+                    # 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} chunks   ",
+                            f"  \U0001f527 Calling {tool_name}... {count} token(s)   ",
                             end="\r",
                         )
                     else:
                         console.print(
-                            f"  \U0001f527 Calling tool... {count} chunks   ",
+                            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:
@@ -238,8 +330,9 @@ async def event_stream_handler(
                 elif event.index in banner_printed:
                     console.print()  # Final newline after streaming
 
-                # Clean up token count
+                # 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)

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