code-puppy 0.0.356__tar.gz → 0.0.357__tar.gz

{code_puppy-0.0.356 → code_puppy-0.0.357}/PKG-INFO

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

{code_puppy-0.0.356 → code_puppy-0.0.357}/code_puppy/agents/agent_qa_kitten.py

@@ -63,8 +63,8 @@ class QualityAssuranceKittenAgent(BaseAgent):
             "browser_wait_for_element",
             "browser_highlight_element",
             "browser_clear_highlights",
-            # Screenshots and VQA
-            "browser_screenshot_analyze",
+            # Screenshots and VQA (uses dedicated VQA agent for context management)
+            "browser_screenshot_vqa",
             # Workflow management
             "browser_save_workflow",
             "browser_list_workflows",
@@ -117,8 +117,12 @@ For any browser task, follow this approach:
 
 ### Visual Verification Workflow
 - **Before critical actions**: Use browser_highlight_element to visually confirm
-- **After interactions**: Use browser_screenshot_analyze to verify results
-- **VQA questions**: Ask specific, actionable questions like "Is the login button highlighted?"
+- **After interactions**: Use browser_screenshot_vqa to verify results
+- **Ask specific questions**: The VQA tool requires a question like:
+  - "Is the login button visible?"
+  - "What error message is displayed?"
+  - "Is the form filled out correctly?"
+  - "What is the main heading text?"
 
 ### Form Input Best Practices
 - **ALWAYS check current values** with browser_get_value before typing
@@ -183,7 +187,7 @@ For any browser task, follow this approach:
 ## Specialized Capabilities
 
 🌐 **WCAG 2.2 Level AA Compliance**: Always prioritize accessibility in element discovery
-📸 **Visual Question Answering**: Use browser_screenshot_analyze for intelligent page analysis
+📸 **Visual Question Answering**: Use browser_screenshot_vqa for intelligent page analysis (uses dedicated VQA agent)
 🚀 **Semantic Web Navigation**: Prefer role-based and label-based element discovery
 ⚡ **Playwright Power**: Full access to modern browser automation capabilities
 📋 **Workflow Management**: Save, load, and reuse automation patterns for consistency
@@ -192,6 +196,7 @@ For any browser task, follow this approach:
 
 - **ALWAYS check for existing workflows first** - Use browser_list_workflows at the start of new tasks
 - **ALWAYS use browser_initialize before any browser operations**
+- **ALWAYS close the browser at the end of every task** using browser_close
 - **PREFER semantic locators over XPath** - they're more maintainable and accessible
 - **Use visual verification for critical actions** - highlight elements and take screenshots
 - **Be explicit about your reasoning** - use share_your_reasoning for complex workflows

code_puppy-0.0.357/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-0.0.356 → code_puppy-0.0.357}/code_puppy/api/app.py

@@ -1,15 +1,89 @@
 """FastAPI application factory for Code Puppy API."""
 
+import asyncio
+import logging
+from contextlib import asynccontextmanager
 from pathlib import Path
+from typing import AsyncGenerator
 
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+logger = logging.getLogger(__name__)
+
+# Default request timeout (seconds) - fail fast!
+REQUEST_TIMEOUT = 30.0
+
+
+class TimeoutMiddleware(BaseHTTPMiddleware):
+    """Middleware to enforce request timeouts and prevent hanging requests."""
+
+    def __init__(self, app, timeout: float = REQUEST_TIMEOUT):
+        super().__init__(app)
+        self.timeout = timeout
+
+    async def dispatch(self, request: Request, call_next):
+        # Skip timeout for WebSocket upgrades and streaming endpoints
+        if request.headers.get(
+            "upgrade", ""
+        ).lower() == "websocket" or request.url.path.startswith("/ws/"):
+            return await call_next(request)
+
+        try:
+            return await asyncio.wait_for(
+                call_next(request),
+                timeout=self.timeout,
+            )
+        except asyncio.TimeoutError:
+            return JSONResponse(
+                status_code=504,
+                content={
+                    "detail": f"Request timed out after {self.timeout}s",
+                    "error": "timeout",
+                },
+            )
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Lifespan context manager for startup and shutdown events.
+
+    Handles graceful cleanup of resources when the server shuts down.
+    """
+    # Startup: nothing special needed yet, but this is where you'd do it
+    logger.info("🐶 Code Puppy API starting up...")
+    yield
+    # Shutdown: clean up all the things!
+    logger.info("🐶 Code Puppy API shutting down, cleaning up...")
+
+    # 1. Close all PTY sessions
+    try:
+        from code_puppy.api.pty_manager import get_pty_manager
+
+        pty_manager = get_pty_manager()
+        await pty_manager.close_all()
+        logger.info("✓ All PTY sessions closed")
+    except Exception as e:
+        logger.error(f"Error closing PTY sessions: {e}")
+
+    # 2. Remove PID file so /api status knows we're gone
+    try:
+        from code_puppy.config import STATE_DIR
+
+        pid_file = Path(STATE_DIR) / "api_server.pid"
+        if pid_file.exists():
+            pid_file.unlink()
+            logger.info("✓ PID file removed")
+    except Exception as e:
+        logger.error(f"Error removing PID file: {e}")
 
 
 def create_app() -> FastAPI:
     """Create and configure the FastAPI application."""
     app = FastAPI(
+        lifespan=lifespan,
         title="Code Puppy API",
         description="REST API and Interactive Terminal for Code Puppy",
         version="1.0.0",
@@ -17,6 +91,9 @@ def create_app() -> FastAPI:
         redoc_url="/redoc",
     )
 
+    # Timeout middleware - added first so it wraps everything
+    app.add_middleware(TimeoutMiddleware, timeout=REQUEST_TIMEOUT)
+
     # CORS middleware for frontend access
     app.add_middleware(
         CORSMiddleware,

{code_puppy-0.0.356 → code_puppy-0.0.357}/code_puppy/api/routers/commands.py

@@ -7,11 +7,19 @@ This router provides REST endpoints for:
 - Autocomplete suggestions for partial commands
 """
 
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
 from typing import Any, List, Optional
 
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel
 
+# Thread pool for blocking command execution
+_executor = ThreadPoolExecutor(max_workers=4)
+
+# Timeout for command execution (seconds)
+COMMAND_TIMEOUT = 30.0
+
 router = APIRouter()
 
 
@@ -126,7 +134,8 @@ async def execute_command(request: CommandExecuteRequest) -> CommandExecuteRespo
     """Execute a slash command.
 
     Takes a command string (with or without leading /) and executes it
-    using the command handler.
+    using the command handler. Runs in a thread pool to avoid blocking
+    the event loop, with a timeout to prevent hangs.
 
     Args:
         request: CommandExecuteRequest with the command to execute.
@@ -140,9 +149,19 @@ async def execute_command(request: CommandExecuteRequest) -> CommandExecuteRespo
     if not command.startswith("/"):
         command = "/" + command
 
+    loop = asyncio.get_running_loop()
+
     try:
-        result = handle_command(command)
+        # Run blocking command in thread pool with timeout
+        result = await asyncio.wait_for(
+            loop.run_in_executor(_executor, handle_command, command),
+            timeout=COMMAND_TIMEOUT,
+        )
         return CommandExecuteResponse(success=True, result=result)
+    except asyncio.TimeoutError:
+        return CommandExecuteResponse(
+            success=False, error=f"Command timed out after {COMMAND_TIMEOUT}s"
+        )
     except Exception as e:
         return CommandExecuteResponse(success=False, error=str(e))
 

{code_puppy-0.0.356 → code_puppy-0.0.357}/code_puppy/api/routers/sessions.py

@@ -1,13 +1,21 @@
 """Sessions API endpoints for retrieving subagent session data."""
 
+import asyncio
 import json
 import pickle
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel
 
+# Thread pool for blocking file I/O
+_executor = ThreadPoolExecutor(max_workers=2)
+
+# Timeout for file operations (seconds)
+FILE_IO_TIMEOUT = 10.0
+
 router = APIRouter()
 
 
@@ -70,6 +78,18 @@ def _serialize_message(msg: Any) -> Dict[str, Any]:
         return {"content": str(msg)}
 
 
+def _load_json_sync(file_path: Path) -> dict:
+    """Synchronous JSON file load (for use in executor)."""
+    with open(file_path, "r") as f:
+        return json.load(f)
+
+
+def _load_pickle_sync(file_path: Path) -> Any:
+    """Synchronous pickle file load (for use in executor)."""
+    with open(file_path, "rb") as f:
+        return pickle.load(f)
+
+
 @router.get("/")
 async def list_sessions() -> List[SessionInfo]:
     """List all available sessions.
@@ -81,12 +101,17 @@ async def list_sessions() -> List[SessionInfo]:
     if not sessions_dir.exists():
         return []
 
+    loop = asyncio.get_running_loop()
     sessions = []
+
     for txt_file in sessions_dir.glob("*.txt"):
         session_id = txt_file.stem
         try:
-            with open(txt_file, "r") as f:
-                metadata = json.load(f)
+            # Run blocking I/O in thread pool with timeout
+            metadata = await asyncio.wait_for(
+                loop.run_in_executor(_executor, _load_json_sync, txt_file),
+                timeout=FILE_IO_TIMEOUT,
+            )
             sessions.append(
                 SessionInfo(
                     session_id=session_id,
@@ -97,6 +122,9 @@ async def list_sessions() -> List[SessionInfo]:
                     message_count=metadata.get("message_count", 0),
                 )
             )
+        except asyncio.TimeoutError:
+            # Timed out reading file, include basic info
+            sessions.append(SessionInfo(session_id=session_id))
         except Exception:
             # If we can't parse metadata, still include basic session info
             sessions.append(SessionInfo(session_id=session_id))
@@ -115,7 +143,7 @@ async def get_session(session_id: str) -> SessionInfo:
         SessionInfo with metadata for the specified session
 
     Raises:
-        HTTPException: 404 if session not found
+        HTTPException: 404 if session not found, 504 on timeout
     """
     sessions_dir = _get_sessions_dir()
     txt_file = sessions_dir / f"{session_id}.txt"
@@ -123,8 +151,15 @@ async def get_session(session_id: str) -> SessionInfo:
     if not txt_file.exists():
         raise HTTPException(404, f"Session '{session_id}' not found")
 
-    with open(txt_file, "r") as f:
-        metadata = json.load(f)
+    loop = asyncio.get_running_loop()
+
+    try:
+        metadata = await asyncio.wait_for(
+            loop.run_in_executor(_executor, _load_json_sync, txt_file),
+            timeout=FILE_IO_TIMEOUT,
+        )
+    except asyncio.TimeoutError:
+        raise HTTPException(504, f"Timeout reading session '{session_id}'")
 
     return SessionInfo(
         session_id=session_id,
@@ -147,7 +182,7 @@ async def get_session_messages(session_id: str) -> List[Dict[str, Any]]:
         List of serialized message dictionaries
 
     Raises:
-        HTTPException: 404 if session messages not found, 500 on load error
+        HTTPException: 404 if session messages not found, 500 on load error, 504 on timeout
     """
     sessions_dir = _get_sessions_dir()
     pkl_file = sessions_dir / f"{session_id}.pkl"
@@ -155,10 +190,16 @@ async def get_session_messages(session_id: str) -> List[Dict[str, Any]]:
     if not pkl_file.exists():
         raise HTTPException(404, f"Session '{session_id}' messages not found")
 
+    loop = asyncio.get_running_loop()
+
     try:
-        with open(pkl_file, "rb") as f:
-            messages = pickle.load(f)
+        messages = await asyncio.wait_for(
+            loop.run_in_executor(_executor, _load_pickle_sync, pkl_file),
+            timeout=FILE_IO_TIMEOUT,
+        )
         return [_serialize_message(msg) for msg in messages]
+    except asyncio.TimeoutError:
+        raise HTTPException(504, f"Timeout loading session '{session_id}' messages")
     except Exception as e:
         raise HTTPException(500, f"Error loading session messages: {e}")
 

{code_puppy-0.0.356 → code_puppy-0.0.357}/code_puppy/config.py

@@ -504,11 +504,12 @@ def set_model_name(model: str):
 
 
 def get_vqa_model_name() -> str:
-    """Return the configured VQA model, falling back to an inferred default."""
+    """Return the configured VQA model, falling back to the global model."""
     stored_model = get_value("vqa_model_name")
     if stored_model and _validate_model_exists(stored_model):
         return stored_model
-    return _default_vqa_model_from_models_json()
+    # Fall back to the global model if no specific VQA model is set
+    return get_global_model_name()
 
 
 def set_vqa_model_name(model: str):
@@ -1323,6 +1324,8 @@ DEFAULT_BANNER_COLORS = {
     "invoke_agent": "deep_pink4",  # Ruby - agent invocation
     "subagent_response": "sea_green3",  # Emerald - sub-agent success
     "list_agents": "dark_slate_gray3",  # Slate - neutral listing
+    # Browser/Terminal tools - same color as edit_file (gold)
+    "terminal_tool": "dark_goldenrod",  # Gold - browser terminal operations
 }