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

code_puppy/tools/browser/browser_screenshot.py

@@ -1,19 +1,21 @@
-"""Screenshot and visual analysis tool with VQA capabilities."""
+"""Screenshot tool for browser automation.
 
-import asyncio
+Captures screenshots and returns them via ToolReturn with BinaryContent
+so multimodal models can directly see and analyze - no separate VQA agent needed.
+"""
+
+import time
 from datetime import datetime
 from pathlib import Path
 from tempfile import gettempdir, mkdtemp
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Union
 
-from pydantic import BaseModel
-from pydantic_ai import RunContext
+from pydantic_ai import BinaryContent, RunContext, ToolReturn
 
 from code_puppy.messaging import emit_error, emit_info, emit_success
 from code_puppy.tools.common import generate_group_id
 
-from .camoufox_manager import get_camoufox_manager
-from .vqa_agent import run_vqa_analysis
+from .browser_manager import get_session_browser_manager
 
 _TEMP_SCREENSHOT_ROOT = Path(
     mkdtemp(prefix="code_puppy_screenshots_", dir=gettempdir())
@@ -21,21 +23,11 @@ _TEMP_SCREENSHOT_ROOT = Path(
 
 
 def _build_screenshot_path(timestamp: str) -> Path:
-    """Return the target path for a screenshot using a shared temp directory."""
+    """Return the target path for a screenshot."""
     filename = f"screenshot_{timestamp}.png"
     return _TEMP_SCREENSHOT_ROOT / filename
 
 
-class ScreenshotResult(BaseModel):
-    """Result from screenshot operation."""
-
-    success: bool
-    screenshot_path: Optional[str] = None
-    screenshot_data: Optional[bytes] = None
-    timestamp: Optional[str] = None
-    error: Optional[str] = None
-
-
 async def _capture_screenshot(
     page,
     full_page: bool = False,
@@ -45,41 +37,37 @@ async def _capture_screenshot(
 ) -> Dict[str, Any]:
     """Internal screenshot capture function."""
     try:
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
 
         # Take screenshot
         if element_selector:
-            # Screenshot specific element
             element = await page.locator(element_selector).first
             if not await element.is_visible():
                 return {
                     "success": False,
                     "error": f"Element '{element_selector}' is not visible",
                 }
-            screenshot_data = await element.screenshot()
+            screenshot_bytes = await element.screenshot()
         else:
-            # Screenshot page or full page
-            screenshot_data = await page.screenshot(full_page=full_page)
+            screenshot_bytes = await page.screenshot(full_page=full_page)
 
-        result = {
+        result: Dict[str, Any] = {
             "success": True,
-            "screenshot_data": screenshot_data,
+            "screenshot_bytes": screenshot_bytes,
             "timestamp": timestamp,
         }
 
         if save_screenshot:
             screenshot_path = _build_screenshot_path(timestamp)
             screenshot_path.parent.mkdir(parents=True, exist_ok=True)
-
             with open(screenshot_path, "wb") as f:
-                f.write(screenshot_data)
-
+                f.write(screenshot_bytes)
             result["screenshot_path"] = str(screenshot_path)
-            message = f"Screenshot saved: {screenshot_path}"
+
             if group_id:
-                emit_success(message, message_group=group_id)
-            else:
-                emit_success(message)
+                emit_success(
+                    f"Screenshot saved: {screenshot_path}", message_group=group_id
+                )
 
         return result
 
@@ -87,46 +75,42 @@ async def _capture_screenshot(
         return {"success": False, "error": str(e)}
 
 
-async def take_screenshot_and_analyze(
-    question: str,
+async def take_screenshot(
     full_page: bool = False,
     element_selector: Optional[str] = None,
     save_screenshot: bool = True,
-) -> Dict[str, Any]:
-    """
-    Take a screenshot and analyze it using visual understanding.
+) -> Union[ToolReturn, Dict[str, Any]]:
+    """Take a screenshot of the browser page.
+
+    Returns a ToolReturn with BinaryContent so multimodal models can
+    directly see and analyze the screenshot.
 
     Args:
-        question: The specific question to ask about the screenshot
-        full_page: Whether to capture the full page or just viewport
-        element_selector: Optional selector to screenshot just a specific element
-        save_screenshot: Whether to save the screenshot to disk
+        full_page: Whether to capture full page or just viewport.
+        element_selector: Optional selector to screenshot specific element.
+        save_screenshot: Whether to save the screenshot to disk.
 
     Returns:
-        Dict containing analysis results and screenshot info
+        ToolReturn containing:
+            - return_value: Success message with screenshot path
+            - content: List with description and BinaryContent image
+            - metadata: Screenshot details (path, target, timestamp)
+        Or Dict with error info if failed.
     """
     target = element_selector or ("full_page" if full_page else "viewport")
-    group_id = generate_group_id(
-        "browser_screenshot_analyze", f"{question[:50]}_{target}"
-    )
-    emit_info(
-        f"BROWSER SCREENSHOT ANALYZE 📷 question='{question[:100]}{'...' if len(question) > 100 else ''}' target={target}",
-        message_group=group_id,
-    )
+    group_id = generate_group_id("browser_screenshot", target)
+    emit_info(f"BROWSER SCREENSHOT 📷 target={target}", message_group=group_id)
+
     try:
-        # Get the current browser page
-        browser_manager = get_camoufox_manager()
+        browser_manager = get_session_browser_manager()
         page = await browser_manager.get_current_page()
 
         if not page:
-            return {
-                "success": False,
-                "error": "No active browser page available. Please navigate to a webpage first.",
-                "question": question,
-            }
+            error_msg = "No active browser page. Navigate to a webpage first."
+            emit_error(error_msg, message_group=group_id)
+            return {"success": False, "error": error_msg}
 
-        # Take screenshot
-        screenshot_result = await _capture_screenshot(
+        result = await _capture_screenshot(
             page,
             full_page=full_page,
             element_selector=element_selector,
@@ -134,108 +118,62 @@ async def take_screenshot_and_analyze(
             group_id=group_id,
         )
 
-        if not screenshot_result["success"]:
-            error_message = screenshot_result.get("error", "Screenshot failed")
-            emit_error(
-                f"Screenshot capture failed: {error_message}",
-                message_group=group_id,
-            )
-            return {
-                "success": False,
-                "error": error_message,
-                "question": question,
-            }
-
-        screenshot_bytes = screenshot_result.get("screenshot_data")
-        if not screenshot_bytes:
-            emit_error(
-                "Screenshot captured but pixel data missing; cannot run visual analysis.",
-                message_group=group_id,
-            )
-            return {
-                "success": False,
-                "error": "Screenshot captured but no image bytes available for analysis.",
-                "question": question,
-            }
-
-        try:
-            vqa_result = await asyncio.to_thread(
-                run_vqa_analysis,
-                question,
-                screenshot_bytes,
-            )
-        except Exception as exc:
-            emit_error(
-                f"Visual question answering failed: {exc}",
-                message_group=group_id,
-            )
-            return {
-                "success": False,
-                "error": f"Visual analysis failed: {exc}",
-                "question": question,
-                "screenshot_info": {
-                    "path": screenshot_result.get("screenshot_path"),
-                    "timestamp": screenshot_result.get("timestamp"),
-                    "full_page": full_page,
-                    "element_selector": element_selector,
-                },
-            }
-
-        emit_success(
-            f"Visual analysis answer: {vqa_result.answer}",
-            message_group=group_id,
-        )
-        emit_info(
-            f"Observations: {vqa_result.observations}",
-            message_group=group_id,
-        )
-
-        return {
-            "success": True,
-            "question": question,
-            "answer": vqa_result.answer,
-            "confidence": vqa_result.confidence,
-            "observations": vqa_result.observations,
-            "screenshot_info": {
-                "path": screenshot_result.get("screenshot_path"),
-                "size": len(screenshot_bytes),
-                "timestamp": screenshot_result.get("timestamp"),
+        if not result["success"]:
+            emit_error(result.get("error", "Screenshot failed"), message_group=group_id)
+            return {"success": False, "error": result.get("error")}
+
+        screenshot_path = result.get("screenshot_path", "(not saved)")
+
+        # Return as ToolReturn with BinaryContent so the model can SEE the image!
+        return ToolReturn(
+            return_value=f"Screenshot captured successfully. Saved to: {screenshot_path}",
+            content=[
+                f"Here's the browser screenshot ({target}):",
+                BinaryContent(
+                    data=result["screenshot_bytes"],
+                    media_type="image/png",
+                ),
+                "Please analyze what you see and describe any relevant details.",
+            ],
+            metadata={
+                "success": True,
+                "screenshot_path": screenshot_path,
+                "target": target,
                 "full_page": full_page,
                 "element_selector": element_selector,
+                "timestamp": time.time(),
             },
-        }
+        )
 
     except Exception as e:
-        emit_error(f"Screenshot analysis failed: {str(e)}", message_group=group_id)
-        return {"success": False, "error": str(e), "question": question}
+        error_msg = f"Screenshot failed: {str(e)}"
+        emit_error(error_msg, message_group=group_id)
+        return {"success": False, "error": error_msg}
 
 
 def register_take_screenshot_and_analyze(agent):
-    """Register the screenshot analysis tool."""
+    """Register the screenshot tool."""
 
     @agent.tool
     async def browser_screenshot_analyze(
         context: RunContext,
-        question: str,
         full_page: bool = False,
         element_selector: Optional[str] = None,
-        save_screenshot: bool = True,
-    ) -> Dict[str, Any]:
+    ) -> Union[ToolReturn, Dict[str, Any]]:
         """
-        Take a screenshot and analyze it to answer a specific question.
+        Take a screenshot of the browser page.
+
+        Returns the screenshot via ToolReturn with BinaryContent that you can
+        see directly. Use this to see what's displayed in the browser.
 
         Args:
-            question: The specific question to ask about the screenshot
-            full_page: Whether to capture the full page or just viewport
-            element_selector: Optional CSS/XPath selector to screenshot specific element
-            save_screenshot: Whether to save the screenshot to disk
+            full_page: Capture full page (True) or just viewport (False).
+            element_selector: Optional CSS selector to screenshot specific element.
 
         Returns:
-            Dict with analysis results including answer, confidence, and observations
+            ToolReturn with the screenshot image you can analyze, or error dict.
         """
-        return await take_screenshot_and_analyze(
-            question=question,
+        return await take_screenshot(
             full_page=full_page,
             element_selector=element_selector,
-            save_screenshot=save_screenshot,
         )

code_puppy/tools/browser/browser_scripts.py

@@ -7,7 +7,7 @@ from pydantic_ai import RunContext
 from code_puppy.messaging import emit_error, emit_info, emit_success
 from code_puppy.tools.common import generate_group_id
 
-from .camoufox_manager import get_camoufox_manager
+from .browser_manager import get_session_browser_manager
 
 
 async def execute_javascript(
@@ -21,14 +21,16 @@ async def execute_javascript(
         message_group=group_id,
     )
     try:
-        browser_manager = get_camoufox_manager()
+        browser_manager = get_session_browser_manager()
         page = await browser_manager.get_current_page()
 
         if not page:
             return {"success": False, "error": "No active browser page available"}
 
         # Execute JavaScript
-        result = await page.evaluate(script, timeout=timeout)
+        # Note: page.evaluate() does NOT accept a timeout parameter
+        # The timeout arg to this function is kept for API compatibility but unused
+        result = await page.evaluate(script)
 
         emit_success("JavaScript executed successfully", message_group=group_id)
 
@@ -52,7 +54,7 @@ async def scroll_page(
         message_group=group_id,
     )
     try:
-        browser_manager = get_camoufox_manager()
+        browser_manager = get_session_browser_manager()
         page = await browser_manager.get_current_page()
 
         if not page:
@@ -60,7 +62,7 @@ async def scroll_page(
 
         if element_selector:
             # Scroll specific element
-            element = page.locator(element_selector)
+            element = page.locator(element_selector).first
             await element.scroll_into_view_if_needed()
 
             # Get element's current scroll position and dimensions
@@ -146,13 +148,13 @@ async def scroll_to_element(
         message_group=group_id,
     )
     try:
-        browser_manager = get_camoufox_manager()
+        browser_manager = get_session_browser_manager()
         page = await browser_manager.get_current_page()
 
         if not page:
             return {"success": False, "error": "No active browser page available"}
 
-        element = page.locator(selector)
+        element = page.locator(selector).first
         await element.wait_for(state="attached", timeout=timeout)
         await element.scroll_into_view_if_needed()
 
@@ -178,7 +180,7 @@ async def set_viewport_size(
         message_group=group_id,
     )
     try:
-        browser_manager = get_camoufox_manager()
+        browser_manager = get_session_browser_manager()
         page = await browser_manager.get_current_page()
 
         if not page:
@@ -209,13 +211,13 @@ async def wait_for_element(
         message_group=group_id,
     )
     try:
-        browser_manager = get_camoufox_manager()
+        browser_manager = get_session_browser_manager()
         page = await browser_manager.get_current_page()
 
         if not page:
             return {"success": False, "error": "No active browser page available"}
 
-        element = page.locator(selector)
+        element = page.locator(selector).first
         await element.wait_for(state=state, timeout=timeout)
 
         emit_success(f"Element {selector} is now {state}", message_group=group_id)
@@ -240,13 +242,13 @@ async def highlight_element(
         message_group=group_id,
     )
     try:
-        browser_manager = get_camoufox_manager()
+        browser_manager = get_session_browser_manager()
         page = await browser_manager.get_current_page()
 
         if not page:
             return {"success": False, "error": "No active browser page available"}
 
-        element = page.locator(selector)
+        element = page.locator(selector).first
         await element.wait_for(state="visible", timeout=timeout)
 
         # Add highlight style
@@ -277,7 +279,7 @@ async def clear_highlights() -> Dict[str, Any]:
         message_group=group_id,
     )
     try:
-        browser_manager = get_camoufox_manager()
+        browser_manager = get_session_browser_manager()
         page = await browser_manager.get_current_page()
 
         if not page:

code_puppy/tools/browser/chromium_terminal_manager.py

@@ -0,0 +1,259 @@
+"""Chromium Terminal Manager - Simple Chromium browser for terminal use.
+
+This module provides a browser manager for Chromium terminal automation.
+Each instance gets its own ephemeral browser context, allowing multiple
+terminal QA agents to run simultaneously without profile conflicts.
+"""
+
+import logging
+import uuid
+from typing import Optional
+
+from playwright.async_api import Browser, BrowserContext, Page, async_playwright
+
+from code_puppy.messaging import emit_info, emit_success
+
+logger = logging.getLogger(__name__)
+
+# Store active manager instances by session ID
+_active_managers: dict[str, "ChromiumTerminalManager"] = {}
+
+
+class ChromiumTerminalManager:
+    """Browser manager for Chromium terminal automation.
+
+    Each instance gets its own ephemeral browser context, allowing multiple
+    terminal QA agents to run simultaneously without profile conflicts.
+
+    Key features:
+    - Ephemeral contexts (no profile locking issues)
+    - Multiple instances can run simultaneously
+    - Visible (headless=False) by default for terminal use
+    - Simple API: initialize, get_current_page, new_page, close
+
+    Usage:
+        manager = get_chromium_terminal_manager()  # or with session_id
+        await manager.async_initialize()
+        page = await manager.get_current_page()
+        await page.goto("https://example.com")
+        await manager.close()
+    """
+
+    _browser: Optional[Browser] = None
+    _context: Optional[BrowserContext] = None
+    _playwright: Optional[object] = None
+    _initialized: bool = False
+
+    def __init__(self, session_id: Optional[str] = None) -> None:
+        """Initialize manager settings.
+
+        Args:
+            session_id: Optional session ID for tracking this instance.
+                If None, a UUID will be generated.
+        """
+        import os
+
+        self.session_id = session_id or str(uuid.uuid4())[:8]
+
+        # Default to headless=False - we want to see the terminal browser!
+        # Can override with CHROMIUM_HEADLESS=true if needed
+        self.headless = os.getenv("CHROMIUM_HEADLESS", "false").lower() == "true"
+
+        logger.debug(
+            f"ChromiumTerminalManager created: session={self.session_id}, "
+            f"headless={self.headless}"
+        )
+
+    async def async_initialize(self) -> None:
+        """Initialize the Chromium browser.
+
+        Launches a Chromium browser with an ephemeral context. The browser
+        runs in visible mode by default (headless=False) for terminal use.
+
+        Raises:
+            Exception: If browser initialization fails.
+        """
+        if self._initialized:
+            logger.debug(
+                f"ChromiumTerminalManager {self.session_id} already initialized"
+            )
+            return
+
+        try:
+            emit_info(
+                f"Initializing Chromium terminal browser (session: {self.session_id})..."
+            )
+
+            # Start Playwright
+            self._playwright = await async_playwright().start()
+
+            # Launch browser (not persistent - allows multiple instances)
+            self._browser = await self._playwright.chromium.launch(
+                headless=self.headless,
+            )
+
+            # Create ephemeral context
+            self._context = await self._browser.new_context()
+            self._initialized = True
+
+            emit_success(
+                f"Chromium terminal browser initialized (session: {self.session_id})"
+            )
+            logger.info(
+                f"Chromium initialized: session={self.session_id}, headless={self.headless}"
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to initialize Chromium: {e}")
+            await self._cleanup()
+            raise
+
+    async def get_current_page(self) -> Optional[Page]:
+        """Get the currently active page, creating one if none exist.
+
+        Lazily initializes the browser if not already initialized.
+
+        Returns:
+            The current page, or None if context is unavailable.
+        """
+        if not self._initialized or not self._context:
+            await self.async_initialize()
+
+        if not self._context:
+            logger.warning("No browser context available")
+            return None
+
+        pages = self._context.pages
+        if pages:
+            return pages[0]
+
+        # Create a new blank page if none exist
+        logger.debug("No existing pages, creating new blank page")
+        return await self._context.new_page()
+
+    async def new_page(self, url: Optional[str] = None) -> Page:
+        """Create a new page, optionally navigating to a URL.
+
+        Lazily initializes the browser if not already initialized.
+
+        Args:
+            url: Optional URL to navigate to after creating the page.
+
+        Returns:
+            The newly created page.
+
+        Raises:
+            RuntimeError: If browser context is not available.
+        """
+        if not self._initialized:
+            await self.async_initialize()
+
+        if not self._context:
+            raise RuntimeError("Browser context not available")
+
+        page = await self._context.new_page()
+        logger.debug(f"Created new page{f' navigating to {url}' if url else ''}")
+
+        if url:
+            await page.goto(url)
+
+        return page
+
+    async def close_page(self, page: Page) -> None:
+        """Close a specific page.
+
+        Args:
+            page: The page to close.
+        """
+        await page.close()
+        logger.debug("Page closed")
+
+    async def get_all_pages(self) -> list[Page]:
+        """Get all open pages.
+
+        Returns:
+            List of all open pages, or empty list if no context.
+        """
+        if not self._context:
+            return []
+        return self._context.pages
+
+    async def _cleanup(self, silent: bool = False) -> None:
+        """Clean up browser resources.
+
+        Args:
+            silent: If True, suppress all errors (used during shutdown).
+        """
+        try:
+            if self._context:
+                try:
+                    await self._context.close()
+                except Exception:
+                    pass
+                self._context = None
+
+            if self._browser:
+                try:
+                    await self._browser.close()
+                except Exception:
+                    pass
+                self._browser = None
+
+            if self._playwright:
+                try:
+                    await self._playwright.stop()
+                except Exception:
+                    pass
+                self._playwright = None
+
+            self._initialized = False
+
+            # Remove from active managers
+            if self.session_id in _active_managers:
+                del _active_managers[self.session_id]
+
+            if not silent:
+                logger.debug(
+                    f"Browser resources cleaned up (session: {self.session_id})"
+                )
+
+        except Exception as e:
+            if not silent:
+                logger.warning(f"Warning during cleanup: {e}")
+
+    async def close(self) -> None:
+        """Close the browser and clean up all resources.
+
+        This properly shuts down the browser and releases all resources.
+        Should be called when done with the browser.
+        """
+        await self._cleanup()
+        emit_info(f"Chromium terminal browser closed (session: {self.session_id})")
+
+
+def get_chromium_terminal_manager(
+    session_id: Optional[str] = None,
+) -> ChromiumTerminalManager:
+    """Get or create a ChromiumTerminalManager instance.
+
+    Args:
+        session_id: Optional session ID. If provided and a manager with this
+            session exists, returns that manager. Otherwise creates a new one.
+            If None, uses 'default' as the session ID.
+
+    Returns:
+        A ChromiumTerminalManager instance.
+
+    Example:
+        # Default session (for single-agent use)
+        manager = get_chromium_terminal_manager()
+
+        # Named session (for multi-agent use)
+        manager = get_chromium_terminal_manager("agent-1")
+    """
+    session_id = session_id or "default"
+
+    if session_id not in _active_managers:
+        _active_managers[session_id] = ChromiumTerminalManager(session_id)
+
+    return _active_managers[session_id]