oagi-core 0.13.2__py3-none-any.whl → 0.14.1__py3-none-any.whl

oagi/__init__.py

@@ -81,6 +81,7 @@ _LAZY_IMPORTS_DATA: dict[str, tuple[str, str | None, str | None]] = {
         "screeninfo",
         "desktop",
     ),
+    "ScreenManager": ("oagi.handler.screen_manager", None, None),
 }
 
 if TYPE_CHECKING:
@@ -95,6 +96,7 @@ if TYPE_CHECKING:
         PyautoguiActionHandler,
         PyautoguiConfig,
     )
+    from oagi.handler.screen_manager import ScreenManager
     from oagi.handler.screenshot_maker import ScreenshotMaker
     from oagi.handler.ydotool_action_handler import YdotoolActionHandler, YdotoolConfig
     from oagi.server.config import ServerConfig
@@ -170,4 +172,6 @@ __all__ = [
     "AsyncYdotoolActionHandler",
     "YdotoolActionHandler",
     "YdotoolConfig",
+    # Lazy imports - Screen manager
+    "ScreenManager",
 ]

oagi/agent/default.py

@@ -6,7 +6,6 @@
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
 
-import asyncio
 import logging
 
 from .. import AsyncActor
@@ -16,7 +15,7 @@ from ..constants import (
     DEFAULT_TEMPERATURE,
     MODEL_ACTOR,
 )
-from ..handler.utils import reset_handler
+from ..handler.utils import configure_handler_delay, reset_handler
 from ..types import (
     ActionEvent,
     AsyncActionHandler,
@@ -72,6 +71,9 @@ class AsyncDefaultAgent:
             # Reset handler state at automation start
             reset_handler(action_handler)
 
+            # Configure handler's post_batch_delay from agent's step_delay
+            configure_handler_delay(action_handler, self.step_delay)
+
             for i in range(self.max_steps):
                 step_num = i + 1
                 logger.debug(f"Executing step {step_num}/{self.max_steps}")
@@ -127,10 +129,6 @@ class AsyncDefaultAgent:
                             )
                         )
 
-                # Wait after actions before next screenshot
-                if self.step_delay > 0:
-                    await asyncio.sleep(self.step_delay)
-
                 # Check if task is complete
                 if step.stop:
                     logger.info(f"Task completed successfully after {step_num} steps")

oagi/agent/tasker/taskee_agent.py

@@ -6,7 +6,6 @@
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
 
-import asyncio
 import logging
 from datetime import datetime
 from typing import Any
@@ -19,7 +18,7 @@ from oagi.constants import (
     DEFAULT_TEMPERATURE,
     MODEL_ACTOR,
 )
-from oagi.handler.utils import reset_handler
+from oagi.handler.utils import configure_handler_delay, reset_handler
 from oagi.types import (
     URL,
     ActionEvent,
@@ -126,6 +125,9 @@ class TaskeeAgent(AsyncAgent):
         # Reset handler state at todo execution start
         reset_handler(action_handler)
 
+        # Configure handler's post_batch_delay from agent's step_delay
+        configure_handler_delay(action_handler, self.step_delay)
+
         self.current_todo = instruction
         self.actions = []
         self.total_actions = 0
@@ -355,10 +357,6 @@ class TaskeeAgent(AsyncAgent):
                 self.total_actions += len(step.actions)
                 self.since_reflection += len(step.actions)
 
-            # Wait after actions before next screenshot
-            if self.step_delay > 0:
-                await asyncio.sleep(self.step_delay)
-
             steps_taken += 1
 
             # Check if task is complete

oagi/cli/agent.py

@@ -86,6 +86,11 @@ def add_agent_parser(subparsers: argparse._SubParsersAction) -> None:
         type=float,
         help=f"Delay in seconds after each step before next screenshot (default: {DEFAULT_STEP_DELAY})",
     )
+    run_parser.add_argument(
+        "--screen-index",
+        type=int,
+        help="Choose the index of screen to run the task",
+    )
 
     # agent modes command
     agent_subparsers.add_parser("modes", help="List available agent modes")
@@ -96,6 +101,11 @@ def add_agent_parser(subparsers: argparse._SubParsersAction) -> None:
         help="Check macOS permissions for screen recording and accessibility",
     )
 
+    # agent screens command
+    agent_subparsers.add_parser(
+        "screens", help="List all available screens for agent execution"
+    )
+
 
 def handle_agent_command(args: argparse.Namespace) -> None:
     if args.agent_command == "run":
@@ -104,6 +114,19 @@ def handle_agent_command(args: argparse.Namespace) -> None:
         list_modes()
     elif args.agent_command == "permission":
         check_permissions()
+    elif args.agent_command == "screens":
+        list_screens()
+
+
+def list_screens() -> None:
+    """List all available screens for agent execution."""
+    from oagi import ScreenManager  # noqa: PLC0415
+
+    screen_manager = ScreenManager()
+    screens = screen_manager.get_all_screens()
+    print("Available screens:")
+    for screen_index, screen in enumerate(screens):
+        print(f"  - Index {screen_index}: {screen}")
 
 
 def list_modes() -> None:
@@ -212,6 +235,22 @@ def run_agent(args: argparse.Namespace) -> None:
     from oagi.agent import create_agent  # noqa: PLC0415
     from oagi.handler.wayland_support import is_wayland_display_server  # noqa: PLC0415
 
+    # Create screen manager for multi-screen support
+    # Must be initialized before importing pyautogui to ensure correct DPI awareness in Windows
+    target_screen = None
+    if args.screen_index is not None:
+        from oagi.handler import ScreenManager  # noqa: PLC0415
+
+        screen_index = args.screen_index
+        screen_manager = ScreenManager()
+        all_screens = screen_manager.get_all_screens()
+        if screen_index >= len(all_screens) or screen_index < 0:
+            raise ValueError(
+                f"Error: Screen index {screen_index} not found. Available screen indices: {list(range(len(all_screens)))}"
+            )
+        target_screen = all_screens[screen_index]
+        print(f"Target screen: {target_screen}")
+
     # Select appropriate action handler based on display server
     if is_wayland_display_server():
         check_optional_dependency("screeninfo", "Agent execution (Wayland)", "desktop")
@@ -280,6 +319,11 @@ def run_agent(args: argparse.Namespace) -> None:
     # Create image provider
     image_provider = AsyncScreenshotMaker()
 
+    if target_screen:
+        # Set the target screen for the image and action provider
+        image_provider.set_target_screen(target_screen)
+        action_handler.set_target_screen(target_screen)
+
     if args.instruction:
         print(f"Starting agent with instruction: {args.instruction}")
     else:

oagi/constants.py

@@ -35,7 +35,7 @@ DEFAULT_REFLECTION_INTERVAL = 4
 DEFAULT_REFLECTION_INTERVAL_TASKER = 20
 
 # Timing & Delays
-DEFAULT_STEP_DELAY = 0.3
+DEFAULT_STEP_DELAY = 1.0
 
 # Temperature Defaults
 DEFAULT_TEMPERATURE = 0.5

oagi/handler/__init__.py

@@ -21,6 +21,7 @@ _LAZY_IMPORTS: dict[str, str] = {
     "AsyncYdotoolActionHandler": "oagi.handler.async_ydotool_action_handler",
     "YdotoolActionHandler": "oagi.handler.ydotool_action_handler",
     "YdotoolConfig": "oagi.handler.ydotool_action_handler",
+    "ScreenManager": "oagi.handler.screen_manager",
 }
 
 if TYPE_CHECKING:
@@ -32,6 +33,7 @@ if TYPE_CHECKING:
         PyautoguiActionHandler,
         PyautoguiConfig,
     )
+    from oagi.handler.screen_manager import ScreenManager
     from oagi.handler.screenshot_maker import ScreenshotMaker
     from oagi.handler.ydotool_action_handler import YdotoolActionHandler, YdotoolConfig
 
@@ -60,4 +62,5 @@ __all__ = [
     "YdotoolConfig",
     "YdotoolActionHandler",
     "AsyncYdotoolActionHandler",
+    "ScreenManager",
 ]

oagi/handler/async_pyautogui_action_handler.py

@@ -8,6 +8,8 @@
 
 import asyncio
 
+from oagi.handler.screen_manager import Screen
+
 from ..types import Action
 from .pyautogui_action_handler import PyautoguiActionHandler, PyautoguiConfig
 
@@ -27,7 +29,16 @@ class AsyncPyautoguiActionHandler:
             config: PyautoguiConfig instance for customizing behavior
         """
         self.sync_handler = PyautoguiActionHandler(config=config)
-        self.config = config or PyautoguiConfig()
+        # Share the same config object so configure_handler_delay() works
+        self.config = self.sync_handler.config
+
+    def set_target_screen(self, screen: Screen) -> None:
+        """Set the target screen for the action handler.
+
+        Args:
+            screen (Screen): The screen object to set as the target.
+        """
+        self.sync_handler.set_target_screen(screen)
 
     def reset(self):
         """Reset handler state.

oagi/handler/async_screenshot_maker.py

@@ -8,6 +8,8 @@
 
 import asyncio
 
+from oagi.handler.screen_manager import Screen
+
 from ..types import Image, ImageConfig
 from .screenshot_maker import ScreenshotMaker
 
@@ -29,6 +31,9 @@ class AsyncScreenshotMaker:
         self.sync_screenshot_maker = ScreenshotMaker(config=config)
         self.config = config
 
+    def set_target_screen(self, screen: Screen) -> None:
+        self.sync_screenshot_maker.set_target_screen(screen)
+
     async def __call__(self) -> Image:
         """
         Capture a screenshot asynchronously using a thread pool executor.

oagi/handler/async_ydotool_action_handler.py

@@ -8,6 +8,8 @@
 
 import asyncio
 
+from oagi.handler.screen_manager import Screen
+
 from ..types import Action
 from .ydotool_action_handler import YdotoolActionHandler, YdotoolConfig
 
@@ -29,6 +31,14 @@ class AsyncYdotoolActionHandler:
         self.config = config or YdotoolConfig()
         self.sync_handler = YdotoolActionHandler(config=self.config)
 
+    def set_target_screen(self, screen: Screen) -> None:
+        """Set the target screen for the action handler.
+
+        Args:
+            screen (Screen): The screen object to set as the target.
+        """
+        self.sync_handler.set_target_screen(screen)
+
     def reset(self):
         """Reset handler state.
 

oagi/handler/pil_image.py

@@ -7,6 +7,7 @@
 # -----------------------------------------------------------------------------
 
 import io
+import sys
 
 from ..exceptions import check_optional_dependency
 from ..types.models.image_config import ImageConfig
@@ -39,17 +40,47 @@ class PILImage:
         return cls(image, config)
 
     @classmethod
-    def from_screenshot(cls, config: ImageConfig | None = None) -> "PILImage":
-        """Create PILImage from screenshot."""
+    def from_screenshot(
+        cls,
+        config: ImageConfig | None = None,
+        region: tuple[int, int, int, int] | None = None,
+    ) -> "PILImage":
+        """Create PILImage from screenshot.
+
+        Args:
+            config: ImageConfig for transformations
+            region: Optional (x, y, width, height) tuple for cropping
+        """
         # Use flameshot by default in Wayland display environment
         if is_wayland_display_server():
-            return cls(wayland_screenshot(), config)
+            return cls(wayland_screenshot(region=region), config)
 
         # Lazy import to avoid DISPLAY issues in headless environments
         check_optional_dependency("pyautogui", "PILImage.from_screenshot()", "desktop")
         import pyautogui  # noqa: PLC0415
 
-        screenshot = pyautogui.screenshot()
+        if sys.platform == "win32" and region is not None:
+            # Use mss instead of pyautogui for screenshots in multi-monitor Windows setups
+            import mss  # noqa: PLC0415
+
+            with mss.mss() as sct:
+                screenshot_data = sct.grab(
+                    {
+                        "top": region[1],
+                        "left": region[0],
+                        "width": region[2],
+                        "height": region[3],
+                    }
+                )
+                screenshot = PILImageLib.frombytes(
+                    "RGB",
+                    screenshot_data.size,
+                    screenshot_data.bgra,
+                    "raw",
+                    "BGRX",
+                )
+        else:
+            screenshot = pyautogui.screenshot(region=region)
         return cls(screenshot, config)
 
     def transform(self, config: ImageConfig) -> "PILImage":

oagi/handler/pyautogui_action_handler.py

@@ -11,6 +11,9 @@ import time
 
 from pydantic import BaseModel, Field
 
+from oagi.handler.screen_manager import Screen
+
+from ..constants import DEFAULT_STEP_DELAY
 from ..exceptions import check_optional_dependency
 from ..types import Action, ActionType, parse_coords, parse_drag_coords, parse_scroll
 from .capslock_manager import CapsLockManager
@@ -55,6 +58,12 @@ class PyautoguiConfig(BaseModel):
         default=0.1,
         description="Delay in seconds after moving to position before clicking",
     )
+    post_batch_delay: float = Field(
+        default=DEFAULT_STEP_DELAY,
+        ge=0,
+        description="Delay after executing all actions in a batch (seconds). "
+        "Allows UI to settle before next screenshot.",
+    )
 
 
 class PyautoguiActionHandler:
@@ -81,6 +90,8 @@ class PyautoguiActionHandler:
         pyautogui.PAUSE = self.config.action_pause
         # Initialize caps lock manager
         self.caps_manager = CapsLockManager(mode=self.config.capslock_mode)
+        # The origin position of coordinates (the top-left corner of the target screen)
+        self.origin_x, self.origin_y = 0, 0
 
     def reset(self):
         """Reset handler state.
@@ -90,6 +101,15 @@ class PyautoguiActionHandler:
         """
         self.caps_manager.reset()
 
+    def set_target_screen(self, screen: Screen) -> None:
+        """Set the target screen for the action handler.
+
+        Args:
+            screen (Screen): The screen object to set as the target.
+        """
+        self.screen_width, self.screen_height = screen.width, screen.height
+        self.origin_x, self.origin_y = screen.x, screen.y
+
     def _denormalize_coords(self, x: float, y: float) -> tuple[int, int]:
         """Convert coordinates from 0-1000 range to actual screen coordinates.
 
@@ -111,6 +131,10 @@ class PyautoguiActionHandler:
         elif screen_y > self.screen_height - 1:
             screen_y = self.screen_height - 1
 
+        # Add origin offset to convert relative to top-left corner
+        screen_x += self.origin_x
+        screen_y += self.origin_y
+
         return screen_x, screen_y
 
     def _parse_coords(self, args_str: str) -> tuple[int, int]:
@@ -275,3 +299,7 @@ class PyautoguiActionHandler:
             except Exception as e:
                 print(f"Error executing action {action.type}: {e}")
                 raise
+
+        # Wait after batch for UI to settle before next screenshot
+        if self.config.post_batch_delay > 0:
+            time.sleep(self.config.post_batch_delay)

oagi/handler/screen_manager.py

@@ -0,0 +1,187 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+
+import sys
+from dataclasses import dataclass
+
+from oagi.exceptions import check_optional_dependency
+
+# Guard flag to prevent multiple DPI awareness calls on Windows
+_dpi_awareness_set = False
+
+
+@dataclass
+class Screen:
+    """
+    Screen represents a single display screen.
+
+    Attributes:
+        name (str): The name of the screen.
+        x (int): The x-coordinate of the top-left corner of the screen.
+        y (int): The y-coordinate of the top-left corner of the screen.
+        width (int): The width of the screen in pixels.
+        height (int): The height of the screen in pixels.
+        is_primary (bool): True if this is the primary screen, False otherwise.
+    """
+
+    name: str
+    x: int
+    y: int
+    width: int
+    height: int
+    is_primary: bool = False
+
+
+class ScreenManager:
+    """
+    ScreenManager is responsible for detecting and managing screens.
+    """
+
+    def __init__(self):
+        self.screens = []
+        # Enable DPI awareness if on Windows
+        if sys.platform == "win32":
+            self.enable_windows_dpi_awareness()
+
+    def get_all_screens(self) -> list[Screen]:
+        if self.screens:
+            return self.screens
+        if sys.platform == "darwin":
+            screens = self._get_darwin_screen_info()
+        elif sys.platform == "win32":
+            screens = self._get_windows_screen_info()
+        else:
+            screens = self._get_linux_screen_info()
+        # Find the primary screen
+        primary_screen, alternative_screens = None, []
+        for screen in screens:
+            if screen.is_primary:
+                primary_screen = screen
+            else:
+                alternative_screens.append(screen)
+        # order the alternative_screens by x coordinate ascending and y coordinate ascending
+        alternative_screens = sorted(
+            alternative_screens, key=lambda item: (item.x, item.y)
+        )
+        # Add the primary screen to the front of the list if it exists
+        if primary_screen:
+            self.screens = [primary_screen]
+        self.screens += alternative_screens
+        return self.screens
+
+    def _get_darwin_screen_info(self) -> list[Screen]:
+        """
+        Get screen information for macOS using AppKit.
+
+        Returns:
+            list[Screen]: A list of Screen objects representing all detected screens.
+        """
+        check_optional_dependency("AppKit", "ScreenManager", "desktop")
+        import AppKit  # noqa: PLC0415
+
+        # Force the RunLoop to update once
+        # This "accepts input" which forces macOS to update screen geometry
+        loop = AppKit.NSRunLoop.currentRunLoop()
+        loop.acceptInputForMode_beforeDate_(
+            AppKit.NSDefaultRunLoopMode, AppKit.NSDate.distantPast()
+        )
+        # Retrieve screen information using AppKit
+        screens = AppKit.NSScreen.screens()
+        screen_list = []
+        for screen in screens:
+            frame = screen.frame()
+            # Origin (0,0) is bottom-left of the primary screen
+            x, y = int(frame.origin.x), int(frame.origin.y)
+            width, height = int(frame.size.width), int(frame.size.height)
+            name = screen.localizedName()
+            # Normalize the origin to Top-Left
+            y = int(AppKit.NSScreen.screens()[0].frame().size.height) - (y + height)
+            screen_list.append(Screen(name, x, y, width, height, x == 0 and y == 0))
+        return screen_list
+
+    def _get_windows_screen_info(self) -> list[Screen]:
+        """
+        Get screen information for Windows using mss.
+
+        Returns:
+            list[Screen]: A list of Screen objects representing all detected screens.
+        """
+        check_optional_dependency("mss", "ScreenManager", "desktop")
+        import mss  # noqa: PLC0415
+
+        screen_list = []
+        for index, screen in enumerate(mss.mss().monitors[1:]):
+            screen_list.append(
+                Screen(
+                    f"DISPLAY{index}",
+                    screen["left"],
+                    screen["top"],
+                    screen["width"],
+                    screen["height"],
+                    screen["top"] == 0 and screen["left"] == 0,
+                )
+            )
+        return screen_list
+
+    def _get_linux_screen_info(self) -> list[Screen]:
+        """
+        Get screen information for Linux and other platforms as default.
+
+        Returns:
+            list[Screen]: A list of Screen objects representing all detected screens.
+        """
+        check_optional_dependency("screeninfo", "ScreenManager", "desktop")
+        import screeninfo  # noqa: PLC0415
+
+        screen_list = []
+        for screen in screeninfo.get_monitors():
+            screen_list.append(
+                Screen(
+                    screen.name,
+                    screen.x,
+                    screen.y,
+                    screen.width,
+                    screen.height,
+                    screen.is_primary,
+                )
+            )
+        return screen_list
+
+    @staticmethod
+    def enable_windows_dpi_awareness():
+        """
+        Enable per-monitor DPI awareness to fix multi-monitor scaling issues.
+
+        On Windows with mixed scaling between monitors, applications that are not
+        DPI-aware will have their coordinates virtualized, causing clicks/moves to
+        land at incorrect positions. Enabling DPI awareness ensures PyAutoGUI and mss
+        works in physical pixels across all monitors.
+
+        This method is idempotent - subsequent calls after the first successful call
+        will be no-ops.
+        """
+        global _dpi_awareness_set
+        if _dpi_awareness_set:
+            return
+
+        import ctypes  # noqa: PLC0415
+
+        try:
+            # For Windows 8.1 and Windows 10/11
+            # 2 = PROCESS_PER_MONITOR_DPI_AWARE
+            PROCESS_PER_MONITOR_DPI_AWARE = 2
+            ctypes.windll.shcore.SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE)
+            _dpi_awareness_set = True
+        except Exception:
+            try:
+                # Fallback for older Windows versions
+                ctypes.windll.user32.SetProcessDPIAware()
+                _dpi_awareness_set = True
+            except Exception:
+                raise RuntimeError("Could not set DPI awareness")

oagi/handler/screenshot_maker.py

@@ -8,6 +8,8 @@
 
 from typing import Optional
 
+from oagi.handler.screen_manager import Screen
+
 from ..types import Image
 from ..types.models.image_config import ImageConfig
 from .pil_image import PILImage
@@ -19,11 +21,16 @@ class ScreenshotMaker:
     def __init__(self, config: ImageConfig | None = None):
         self.config = config or ImageConfig()
         self._last_image: Optional[PILImage] = None
+        self.region: Optional[tuple[int, int, int, int]] = None
+
+    def set_target_screen(self, screen: Screen) -> None:
+        """Set the target screen for screenshotting."""
+        self.region = (screen.x, screen.y, screen.width, screen.height)
 
     def __call__(self) -> Image:
         """Take and process a screenshot."""
         # Create PILImage from screenshot
-        pil_image = PILImage.from_screenshot()
+        pil_image = PILImage.from_screenshot(region=self.region)
 
         # Apply transformation if config is set
         if self.config:

oagi/handler/utils.py

@@ -19,3 +19,17 @@ def reset_handler(handler) -> None:
     """
     if hasattr(handler, "reset"):
         handler.reset()
+
+
+def configure_handler_delay(handler, step_delay: float) -> None:
+    """Configure handler's post_batch_delay from agent's step_delay.
+
+    Uses duck-typing to check if the handler has a config with post_batch_delay.
+    This allows agents to control the delay after action execution.
+
+    Args:
+        handler: The action handler to configure
+        step_delay: The delay in seconds to set
+    """
+    if hasattr(handler, "config") and hasattr(handler.config, "post_batch_delay"):
+        handler.config.post_batch_delay = step_delay

oagi/handler/wayland_support.py

@@ -43,7 +43,7 @@ def get_screen_size() -> tuple[int, int]:
     raise Exception("No monitor found, cannot get the screen size info")
 
 
-def screenshot() -> Image:
+def screenshot(region: tuple[int, int, int, int] | None = None) -> Image:
     """
     Use Flameshot to take a screenshot and return an Image object
 
@@ -52,7 +52,11 @@ def screenshot() -> Image:
     # Check if flameshot is installed
     if shutil.which("flameshot") is None:
         raise RuntimeError("flameshot not found. Ensure it is installed and in PATH.")
-    cmd = ["flameshot", "full", "--region", "all", "--raw"]
+    cmd = ["flameshot", "full", "--raw"]
+    if region:
+        cmd.extend(["--region", f"{region[2]}x{region[3]}+{region[0]}+{region[1]}"])
+    else:
+        cmd.extend(["--region", "all"])
     res = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
     if res.returncode != 0:
         raise RuntimeError(

oagi/handler/ydotool_action_handler.py

@@ -10,6 +10,9 @@ import time
 
 from pydantic import BaseModel, Field
 
+from oagi.handler.screen_manager import Screen
+
+from ..constants import DEFAULT_STEP_DELAY
 from ..types import Action, ActionType, parse_coords, parse_drag_coords, parse_scroll
 from .capslock_manager import CapsLockManager
 from .wayland_support import Ydotool, get_screen_size
@@ -36,6 +39,12 @@ class YdotoolConfig(BaseModel):
         default="",
         description="Custom socket address for ydotool (e.g., '/tmp/ydotool.sock')",
     )
+    post_batch_delay: float = Field(
+        default=DEFAULT_STEP_DELAY,
+        ge=0,
+        description="Delay after executing all actions in a batch (seconds). "
+        "Allows UI to settle before next screenshot.",
+    )
 
 
 class YdotoolActionHandler(Ydotool):
@@ -62,6 +71,8 @@ class YdotoolActionHandler(Ydotool):
         self.action_pause = self.config.action_pause
         # Initialize caps lock manager
         self.caps_manager = CapsLockManager(mode=self.config.capslock_mode)
+        # The origin position of coordinates (the top-left corner of the screen)
+        self.origin_x, self.origin_y = 0, 0
 
     def reset(self):
         """Reset handler state.
@@ -71,6 +82,15 @@ class YdotoolActionHandler(Ydotool):
         """
         self.caps_manager.reset()
 
+    def set_target_screen(self, screen: Screen) -> None:
+        """Set the target screen for the action handler.
+
+        Args:
+            screen (Screen): The screen object to set as the target.
+        """
+        self.screen_width, self.screen_height = screen.width, screen.height
+        self.origin_x, self.origin_y = screen.x, screen.y
+
     def _execute_action(self, action: Action) -> bool:
         """
         Execute a group of actions and return whether FINISH is reached.
@@ -168,6 +188,10 @@ class YdotoolActionHandler(Ydotool):
         elif screen_y > self.screen_height - 1:
             screen_y = self.screen_height - 1
 
+        # Add origin offset to convert relative to top-left corner
+        screen_x += self.origin_x
+        screen_y += self.origin_y
+
         return screen_x, screen_y
 
     def _normalize_key(self, key: str) -> str:
@@ -224,3 +248,7 @@ class YdotoolActionHandler(Ydotool):
             except Exception as e:
                 print(f"Error executing action {action.type}: {e}")
                 raise
+
+        # Wait after batch for UI to settle before next screenshot
+        if self.config.post_batch_delay > 0:
+            time.sleep(self.config.post_batch_delay)

{oagi_core-0.13.2.dist-info → oagi_core-0.14.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oagi-core
-Version: 0.13.2
+Version: 0.14.1
 Summary: Official API of OpenAGI Foundation
 Project-URL: Homepage, https://github.com/agiopen-org/oagi
 Author-email: OpenAGI Foundation <contact@agiopen.org>
@@ -31,6 +31,7 @@ Requires-Dist: openai>=1.3.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=10.0.0
 Provides-Extra: desktop
+Requires-Dist: mss>=9.0.0; (sys_platform == 'win32') and extra == 'desktop'
 Requires-Dist: pillow>=9.0.0; extra == 'desktop'
 Requires-Dist: pyautogui>=0.9.54; extra == 'desktop'
 Requires-Dist: pyobjc-framework-applicationservices>=8.0; (sys_platform == 'darwin') and extra == 'desktop'
@@ -153,12 +154,15 @@ from oagi import AsyncPyautoguiActionHandler, PyautoguiConfig
 
 # Customize action behavior
 config = PyautoguiConfig(
-    drag_duration=1.0,      # Slower drags for precision (default: 0.5)
-    scroll_amount=50,       # Larger scroll steps (default: 30)
-    wait_duration=2.0,      # Longer waits (default: 1.0)
-    action_pause=0.2,       # More pause between actions (default: 0.1)
-    hotkey_interval=0.1,    # Interval between keys in hotkey combinations (default: 0.1)
-    capslock_mode="session" # Caps lock mode: 'session' or 'system' (default: 'session')
+    drag_duration=1.0,       # Slower drags for precision (default: 0.5)
+    scroll_amount=50,        # Larger scroll steps (default: 2 on macOS, 100 on others)
+    wait_duration=2.0,       # Longer waits for WAIT action (default: 1.0)
+    action_pause=0.2,        # Pause between PyAutoGUI calls (default: 0.1)
+    hotkey_interval=0.1,     # Interval between keys in hotkey combos (default: 0.1)
+    capslock_mode="session", # Caps lock mode: 'session' or 'system' (default: 'session')
+    macos_ctrl_to_cmd=True,  # Replace ctrl with cmd on macOS (default: True)
+    click_pre_delay=0.1,     # Delay after move before click (default: 0.1)
+    post_batch_delay=1.0,    # Delay after actions before next screenshot (default: 1.0)
 )
 
 action_handler = AsyncPyautoguiActionHandler(config=config)
@@ -184,8 +188,14 @@ oagi agent modes
 # Check macOS permissions (screen recording & accessibility)
 oagi agent permission
 
+# Print all available screens and their indices
+oagi agent screens
+
 # Export execution history
 oagi agent run "Complete the form" --export html --export-file report.html
+
+# Run with a specific screen
+oagi agent run "Search weather on Google" --screen-index 1
 ```
 
 CLI options:
@@ -196,6 +206,7 @@ CLI options:
 - `--step-delay`: Delay after each action before next screenshot (default: 0.3s)
 - `--export`: Export format (markdown, html, json)
 - `--export-file`: Output file path for export
+- `--screen-index`: Screen index for multi-screen environments
 
 ### Image Processing
 
@@ -271,20 +282,71 @@ from oagi import AsyncYdotoolActionHandler, YdotoolConfig
 # Customize action behavior
 config = YdotoolConfig(
     scroll_amount=50,        # Larger scroll steps (default: 20)
-    wait_duration=2.0,       # Longer waits (default: 1.0)
-    action_pause=1.0,        # More pause between actions (default: 0.5)
+    wait_duration=2.0,       # Longer waits for WAIT action (default: 1.0)
+    action_pause=1.0,        # Pause between Ydotool calls (default: 0.5)
     capslock_mode="session", # Caps lock mode: 'session' or 'system' (default: 'session')
-    socket_address="/tmp/ydotool.sock"  # Customized Socket address for ydotool (ydotool uses 'YDOTOOL_SOCKET' environment variable by default)
+    socket_address="/tmp/ydotool.sock",  # Custom socket address (default: YDOTOOL_SOCKET env var)
+    post_batch_delay=1.0,    # Delay after actions before next screenshot (default: 1.0)
 )
 
 action_handler = AsyncYdotoolActionHandler(config=config)
 ```
 
+### Multi-Screen Execution
+When running on multi-screen environments, you can choose which screen to use for task execution. The `ScreenManager` class provides methods to list available screens, while the `AsyncPyautoguiActionHandler` and `AsyncScreenshotMaker` classes allow you to set the target screen for actions and screenshots. In the result of `get_all_screens`, the primary screen is always the first one in the list and the remaining screens are appended in the ascending order of their origin coordinates.
+
+```python
+import asyncio
+import sys
+from oagi import ScreenManager
+
+# Must be initialized before importing pyautogui to ensure correct DPI awareness in Windows
+if sys.platform == "win32":
+    ScreenManager.enable_windows_dpi_awareness()
+
+from oagi import (
+    AsyncDefaultAgent,
+    AsyncPyautoguiActionHandler,
+    AsyncScreenshotMaker,
+)
+
+def print_all_screens():
+    """Print all available screens."""
+    screen_manager = ScreenManager()
+    all_screens = screen_manager.get_all_screens()
+    print("Available screens:")
+    for screen_index, screen in enumerate(all_screens):
+        print(f"  - Index {screen_index}: {screen}")
+
+async def main():
+    agent = AsyncDefaultAgent(max_steps=10)
+    action_handler = AsyncPyautoguiActionHandler()
+    image_provider = AsyncScreenshotMaker()
+    # Get all available screens
+    screen_manager = ScreenManager()
+    all_screens = screen_manager.get_all_screens()
+    # Choose a screen for task execution
+    screen_index = 1  # Use the second screen as example
+    target_screen = all_screens[screen_index]
+    # Set the target screen for handlers
+    action_handler.set_target_screen(target_screen)
+    image_provider.set_target_screen(target_screen)
+    completed = await agent.execute(
+        "Search weather on Google",
+        action_handler=action_handler,
+        image_provider=image_provider,
+    )
+    return completed
+
+asyncio.run(main())
+```
+
 ## Examples
 
 See the [`examples/`](examples/) directory for more usage patterns:
 - `execute_task_auto.py` - Automated task execution with `AsyncDefaultAgent`
 - `execute_task_manual.py` - Manual step-by-step control with `Actor`
+- `multi_screen_execution.py` - Automated task execution on multi-screen environments
 - `continued_session.py` - Continuing tasks across sessions
 - `screenshot_with_config.py` - Image compression and optimization
 - `socketio_server_basic.py` - Socket.IO server example

{oagi_core-0.13.2.dist-info → oagi_core-0.14.1.dist-info}/RECORD

@@ -1,5 +1,5 @@
-oagi/__init__.py,sha256=ly956qE0F4FlzaU-kPsKAhpG2Kc3D9T_BJDZmWqioOc,5616
-oagi/constants.py,sha256=VUEgpwup55rTrvPC2xhtjZgpUHJlVaNRidiUlXXEjx0,1228
+oagi/__init__.py,sha256=TVBbIMEXQh5Z8JumqrivMPBLYt3E5HmGPi973NDx2Qs,5797
+oagi/constants.py,sha256=qcNisliLRZUr6krXpS49AAPfFYvkZuWQcAJ8ZdEnhic,1228
 oagi/exceptions.py,sha256=Rco37GQTPYUfc2vRO3hozxPF_s8mKFDpFvBg2UKWo3Y,3066
 oagi/logging.py,sha256=YT3KCMFj5fzO98R9xlDDgfSotUuz1xRD6OZeYM2rKoo,1760
 oagi/platform_info.py,sha256=GEqNWnwePszVEM21toGGi07o3PaX8O059CYRr0RUM_M,1424
@@ -10,7 +10,7 @@ oagi/actor/base.py,sha256=-ecocyZ9-NQ4C4jjsHLUcs3ixZ99rFbzqwFsiVKZVR0,8001
 oagi/actor/short.py,sha256=wKLCxvf7Ys6rYxXpHe4zbZdbf_1q1qcmm5WyWubwj3E,2630
 oagi/actor/sync.py,sha256=QTY1WNTI75jwkWBghdVViHIp5rYkbm3kumlLedU8YeQ,3588
 oagi/agent/__init__.py,sha256=KTVLUMhbjgpTJoOWMUZkkiqwhgumvbOZV2tJ9XCLfao,901
-oagi/agent/default.py,sha256=Ax05kBa8Fb14Ev8wd9LS6xkF65grf6qdxxTlgpkkDuk,4715
+oagi/agent/default.py,sha256=mP4Gdld5I0sP0ANyn1CLkFvgk9qPkzYbwJeZUGhlsew,4712
 oagi/agent/factories.py,sha256=syi_EOlU4SUjo-0CKaML8eIPu3ToUEKua2VHp9lvNF0,5839
 oagi/agent/protocol.py,sha256=IQJGiMN4yZIacrh5e9JQsoM9TyHb8wJRQR4LAk8dSA0,1615
 oagi/agent/registry.py,sha256=7bMA2-pH3xQ9ZavrHB_mnc2fOGSMeICPbOGtHoM7It0,4851
@@ -24,10 +24,10 @@ oagi/agent/tasker/__init__.py,sha256=1iTEFe7lzcqh96TL9R0QADPpLJLrUP0shtZ4DlZSv_8
 oagi/agent/tasker/memory.py,sha256=NR13l5yxRA8GUE-oupAP4W1n80ZNG0SxpUfxsNltkUY,5033
 oagi/agent/tasker/models.py,sha256=sMQgwIMKhT1tvVF2yoc1hh8GwEiJ6i6qPMy9WoiA8JM,2137
 oagi/agent/tasker/planner.py,sha256=q6IvH6sfU2kYX1NcC9VHjGaQ0X9jF18yjuAYXisNCg0,15489
-oagi/agent/tasker/taskee_agent.py,sha256=OugYJbTbFKxgNjbIyQBBH4Zm5u5PuWN1F6R81_eIro8,18090
+oagi/agent/tasker/taskee_agent.py,sha256=IfRg_YixHkxHuiGCqok5cPDLD7PXUqlsoRAfWnWswMI,18091
 oagi/agent/tasker/tasker_agent.py,sha256=yb0BdQzJyAPpK3njHPWgQruV8zpUGBXn1WjOGEMIO-g,11291
 oagi/cli/__init__.py,sha256=aDnJViTseShpo5fdGPTj-ELysZhmdvB6Z8mEj2D-_N4,359
-oagi/cli/agent.py,sha256=lT95jgfzf-LizOWbzYfhq_EkcYcLvJH2uL-HKnYW_es,11533
+oagi/cli/agent.py,sha256=CWvwwbo4eiq-USYmDHnKafEX8Nk6zsGsUmNzB4QftkQ,13186
 oagi/cli/display.py,sha256=Y8_Dn5RIEfRqZUHVGF6URItW0C3XC7bPLWoAmmhvBS0,1829
 oagi/cli/main.py,sha256=faHns0HaQCGyylDn2YZLpjQESuEiMYjoQVoMkt8FsH4,2292
 oagi/cli/server.py,sha256=JFpzCOeaftITxesz8Ya-_Efs03bgotBg7aYwmMZhPwU,3033
@@ -37,20 +37,21 @@ oagi/client/__init__.py,sha256=F9DShPUdb6vZYmN1fpM1VYzp4MWqUao_e_R1KYmM4Q4,410
 oagi/client/async_.py,sha256=BANE0KU14WBuXp6suBhr8JSlpWhN5SR2aJJ7wAJBDLQ,9574
 oagi/client/base.py,sha256=CWAvE0AcpL8HD_i00n7Fq53AIAQGhBhS_n6LifUCqxE,14736
 oagi/client/sync.py,sha256=4xNqqNihXmgLU385h22mMJ9wmmlw-jeOdWI4fmpEpTk,9369
-oagi/handler/__init__.py,sha256=rqxbj6Bp9MGndLBVhqRx8b-GSYR3PC5ktErMvd-HzRI,2397
+oagi/handler/__init__.py,sha256=ZMQIeN_uJKUK_dn0w7ggsPfdRzzwts7G-Sppsrt22Lg,2528
 oagi/handler/_macos.py,sha256=Gs8GrhA_WAyv9Yw0D41duliP32Xk6vouyMeWjWJJT90,5187
 oagi/handler/_windows.py,sha256=MSgPDYEOetSjbn9eJDSrdzBVlUGgGsTlegaTDc4C4Ss,2828
 oagi/handler/_ydotool.py,sha256=WjvE6RGRm8j3SEWpgfMw31aow3z3qkiMupuUHYt-QAM,2948
-oagi/handler/async_pyautogui_action_handler.py,sha256=wfNRBBURZnwQkNTcs9OPMmFJIAPtnXmcqxWbjda_q7I,1863
-oagi/handler/async_screenshot_maker.py,sha256=8QCtUV59ozpOpvkqhUMb8QDI2qje2gsoFT1qB60tfJM,1689
-oagi/handler/async_ydotool_action_handler.py,sha256=BRGqZB2u1k7R1acUX9k0TfdrmWS2eh3opc8LoqnlwJ4,1848
+oagi/handler/async_pyautogui_action_handler.py,sha256=vZLf6LyRUzPAr8hGmKQDDyXMmc3ZAhlCCN4dIfi3vnY,2245
+oagi/handler/async_screenshot_maker.py,sha256=_myV4Rq6X_evCOuatalFSW5nsUDXi_0ej0GQ7V4n3JE,1856
+oagi/handler/async_ydotool_action_handler.py,sha256=HB4QQk3OaG08g37eLb3EwsnkWKWPrpDei0ZsnBxrGZY,2159
 oagi/handler/capslock_manager.py,sha256=40LzWt1_1wbncF5koUTdbd9V3eo5Ex_mEWwjtEmHAf4,1878
-oagi/handler/pil_image.py,sha256=GQw2o8ORQinrM3AxhgNBbLhrkZajOL8YagU7UF-kkes,4357
-oagi/handler/pyautogui_action_handler.py,sha256=P6YPgsXr3mQn_lh6rVLzWBomg9s5EIwbKZYbOgCAa5A,10640
-oagi/handler/screenshot_maker.py,sha256=j1jTW-awx3vAnb1N5_FIMBC0Z-rNVQbiBP-S6Gh5dlE,1284
-oagi/handler/utils.py,sha256=jj10z-v4_LUuVb8aClyXkUfZVEaqsWgi3be4t3Gw7oI,697
-oagi/handler/wayland_support.py,sha256=jeQDqpwAxxREaGAYePQuK14nuEMPGmMEvMz2ymS-rT4,7727
-oagi/handler/ydotool_action_handler.py,sha256=8cmOFaEsYMI5BiYdYRuUIaSXDNgrdk-B3OnHVbEa9Sk,8608
+oagi/handler/pil_image.py,sha256=s8UGZ6ALbmOxRO2GL1EUFN7_6ZEFseSE9OHABCe7wek,5380
+oagi/handler/pyautogui_action_handler.py,sha256=vjCtv6VaW0NNrId7PZR0-Y2VWe701t6KptQmun57aFo,11737
+oagi/handler/screen_manager.py,sha256=FV0-6ZyTVv9yZlAg4Krga0xW9O_LDsk1iaCJjWgET-g,6565
+oagi/handler/screenshot_maker.py,sha256=740k7NjDRKW6KwVqy_nVoczgVuw9_yTKM0gLFKB1iNs,1600
+oagi/handler/utils.py,sha256=vfOe5H6kb50WhzxVc9Gv3i1rVXTkmv2L8fQ3mb5ECb4,1235
+oagi/handler/wayland_support.py,sha256=qUIAQMqc3wp1VIypVmZjFDYT8t0yH0QvikTTV8pD-XA,7905
+oagi/handler/ydotool_action_handler.py,sha256=28aUeu6F4r8oWSiZNHLdKPGQYTMJS6sOzLphQSmi7-4,9698
 oagi/server/__init__.py,sha256=uZx8u3vJUb87kkNzwmmVrgAgbqRu0WxyMIQCLSx56kk,452
 oagi/server/agent_wrappers.py,sha256=j8va0A7u80bzOM82nndAplK1uaO_T3kufHWScK6kfWM,3263
 oagi/server/config.py,sha256=AJ1PLKuxrc6pRuur1hm5DwG2g2otxPwOCfKgzIACkSk,1691
@@ -75,8 +76,8 @@ oagi/types/models/step.py,sha256=RSI4H_2rrUBq_xyCoWKaq7JHdJWNobtQppaKC1l0aWU,471
 oagi/utils/__init__.py,sha256=vHXyX66hEsf33OJJkmZSUjaTYU0UngfbtjcZgxfOj3A,441
 oagi/utils/output_parser.py,sha256=U7vzmoD8pyzDg23z3vy-L9a_jKPsAlr3x8lIdPszrY8,5322
 oagi/utils/prompt_builder.py,sha256=_Q1HY82YUrq3jSCTZ3Rszu3qmI3Wn_fmq8hf14NuwQM,2180
-oagi_core-0.13.2.dist-info/METADATA,sha256=DfZTkJyg0UmS4UH4V67rHhrsdfonwImQnSz7zOdI3QQ,14203
-oagi_core-0.13.2.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-oagi_core-0.13.2.dist-info/entry_points.txt,sha256=zzgsOSWX6aN3KUB0Z1it8DMxFFBJBqmZVqMVAJRjYuw,44
-oagi_core-0.13.2.dist-info/licenses/LICENSE,sha256=sy5DLA2M29jFT4UfWsuBF9BAr3FnRkYtnAu6oDZiIf8,1075
-oagi_core-0.13.2.dist-info/RECORD,,
+oagi_core-0.14.1.dist-info/METADATA,sha256=r-RhbjurIDIEWOnL7rKM_nmGb5A7pSs4QH9h0HtsRZo,16854
+oagi_core-0.14.1.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+oagi_core-0.14.1.dist-info/entry_points.txt,sha256=zzgsOSWX6aN3KUB0Z1it8DMxFFBJBqmZVqMVAJRjYuw,44
+oagi_core-0.14.1.dist-info/licenses/LICENSE,sha256=sy5DLA2M29jFT4UfWsuBF9BAr3FnRkYtnAu6oDZiIf8,1075
+oagi_core-0.14.1.dist-info/RECORD,,