oagi-core 0.13.2__tar.gz → 0.14.0__tar.gz

{oagi_core-0.13.2 → oagi_core-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oagi-core
-Version: 0.13.2
+Version: 0.14.0
 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'
@@ -184,8 +185,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 +203,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
 
@@ -280,11 +288,61 @@ config = YdotoolConfig(
 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 → oagi_core-0.14.0}/README.md

@@ -139,8 +139,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:
@@ -151,6 +157,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
 
@@ -235,11 +242,61 @@ config = YdotoolConfig(
 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.14.0/examples/multi_screen_execution.py

@@ -0,0 +1,74 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+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}")
+
+
+def execute_task_on_specific_screen(task_desc, max_steps=5, screen_index=0):
+    """Synchronous wrapper for async task execution."""
+    # Print all screens and choose one screen for task execution
+    return asyncio.run(
+        async_execute_task_on_specific_screen(task_desc, max_steps, screen_index)
+    )
+
+
+async def async_execute_task_on_specific_screen(task_desc, max_steps=5, screen_index=0):
+    # set OAGI_API_KEY and OAGI_BASE_URL
+    # or AsyncDefaultAgent(api_key="your_api_key", base_url="your_base_url")
+    agent = AsyncDefaultAgent(max_steps=max_steps)
+
+    # executor = lambda actions: print(actions) for debugging
+    action_handler = AsyncPyautoguiActionHandler()
+    image_provider = AsyncScreenshotMaker()
+
+    # Get the target screen info for task execution
+    screen_manager = ScreenManager()
+    all_screens = screen_manager.get_all_screens()
+    screen = all_screens[screen_index]
+    # Set the screen index for handlers
+    action_handler.set_target_screen(screen)
+    image_provider.set_target_screen(screen)
+
+    is_completed = await agent.execute(
+        task_desc,
+        action_handler=action_handler,
+        image_provider=image_provider,
+    )
+
+    return is_completed, await image_provider.last_image()
+
+
+if __name__ == "__main__":
+    # Example task
+    task_desc = "Open Chrome and navigate to google.com"
+    screen_index = 1  # Use the second screen as example
+    success, image = execute_task_on_specific_screen(
+        task_desc, screen_index=screen_index
+    )
+    print(f"\nFinal result: {'Success' if success else 'Failed'}")

{oagi_core-0.13.2 → oagi_core-0.14.0}/metapackage/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi"
-version = "0.13.2"
+version = "0.14.0"
 description = "Official API of OpenAGI Foundation (metapackage with all features)"
 readme = "README.md"
 license = "MIT"
@@ -16,7 +16,7 @@ authors = [
 requires-python = ">= 3.10"
 
 dependencies = [
-    "oagi-core[desktop,server]==0.13.2",
+    "oagi-core[desktop,server]==0.14.0",
 ]
 
 [project.urls]

{oagi_core-0.13.2 → oagi_core-0.14.0}/metapackage/uv.lock

@@ -518,18 +518,18 @@ sdist = { url = "https://files.pythonhosted.org/packages/28/fa/b2ba8229b9381e8f6
 
 [[package]]
 name = "oagi"
-version = "0.13.2"
+version = "0.14.0"
 source = { editable = "." }
 dependencies = [
     { name = "oagi-core", extra = ["desktop", "server"] },
 ]
 
 [package.metadata]
-requires-dist = [{ name = "oagi-core", extras = ["desktop", "server"], specifier = "==0.13.1" }]
+requires-dist = [{ name = "oagi-core", extras = ["desktop", "server"], specifier = "==0.13.2" }]
 
 [[package]]
 name = "oagi-core"
-version = "0.13.1"
+version = "0.13.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "httpx" },
@@ -537,9 +537,9 @@ dependencies = [
     { name = "pydantic" },
     { name = "rich" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/62/b0/6006c57afc693a4afdc5389f1c93e83654745ec2b25d33c091621aec7d15/oagi_core-0.13.1.tar.gz", hash = "sha256:8dcbf45c6eb7203573d04122ebb53c67d7c955bb6bbfe8332fe2e641e7cb689f", size = 304385, upload-time = "2026-01-12T04:14:18.758Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/32/64/cf3f690deafbbacd17333e307f4fa6fc9daa68c69de0e426db3684c9e25b/oagi_core-0.13.2.tar.gz", hash = "sha256:f5b4957bd383ed312753b36476680e99adc42a0ff9d912054cf54021d8b132fe", size = 304580, upload-time = "2026-01-16T02:17:23.505Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/6e/78/0a04d5a28313ab6dc783a5c4d8b32c1871fa2a140f75dfe42f56024c8865/oagi_core-0.13.1-py3-none-any.whl", hash = "sha256:b29637ca080fa7092224231b113b35c07f09657bed203e8e26e13e2c2a65665f", size = 110049, upload-time = "2026-01-12T04:14:17.645Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/12/8d2d0240176cfb275282c735fa57ea7620ba3f8a40ba73a2b151c1c6c3b7/oagi_core-0.13.2-py3-none-any.whl", hash = "sha256:4251a9d4f056b98d653a8e2fce3de8d19f5836130275161ec8b4733646a8933d", size = 110155, upload-time = "2026-01-16T02:17:22.055Z" },
 ]
 
 [package.optional-dependencies]

{oagi_core-0.13.2 → oagi_core-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi-core"
-version = "0.13.2"
+version = "0.14.0"
 description = "Official API of OpenAGI Foundation"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -33,7 +33,8 @@ desktop = [
     "pyautogui>=0.9.54",
     "pyobjc-framework-Quartz>=8.0; sys_platform == 'darwin'",
     "pyobjc-framework-ApplicationServices>=8.0; sys_platform == 'darwin'",
-    "screeninfo>=0.8.1"
+    "screeninfo>=0.8.1",
+    "mss>=9.0.0; sys_platform == 'win32'",
 ]
 server = [
     "fastapi[standard]>=0.100.0",

{oagi_core-0.13.2 → oagi_core-0.14.0}/src/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_core-0.13.2 → oagi_core-0.14.0}/src/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_core-0.13.2 → oagi_core-0.14.0}/src/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_core-0.13.2 → oagi_core-0.14.0}/src/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_core-0.13.2 → oagi_core-0.14.0}/src/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
 
@@ -29,6 +31,14 @@ class AsyncPyautoguiActionHandler:
         self.sync_handler = PyautoguiActionHandler(config=config)
         self.config = config or PyautoguiConfig()
 
+    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_core-0.13.2 → oagi_core-0.14.0}/src/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_core-0.13.2 → oagi_core-0.14.0}/src/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_core-0.13.2 → oagi_core-0.14.0}/src/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_core-0.13.2 → oagi_core-0.14.0}/src/oagi/handler/pyautogui_action_handler.py

@@ -11,6 +11,8 @@ import time
 
 from pydantic import BaseModel, Field
 
+from oagi.handler.screen_manager import Screen
+
 from ..exceptions import check_optional_dependency
 from ..types import Action, ActionType, parse_coords, parse_drag_coords, parse_scroll
 from .capslock_manager import CapsLockManager
@@ -81,6 +83,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 +94,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 +124,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]: