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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oagi-core
-Version: 0.14.0
+Version: 0.14.2
 Summary: Official API of OpenAGI Foundation
 Project-URL: Homepage, https://github.com/agiopen-org/oagi
 Author-email: OpenAGI Foundation <contact@agiopen.org>
@@ -154,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)
@@ -279,10 +282,11 @@ 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)

{oagi_core-0.14.0 → oagi_core-0.14.2}/README.md

@@ -108,12 +108,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)
@@ -233,10 +236,11 @@ 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)

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi"
-version = "0.14.0"
+version = "0.14.2"
 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.14.0",
+    "oagi-core[desktop,server]==0.14.2",
 ]
 
 [project.urls]

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

@@ -516,20 +516,29 @@ dependencies = [
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/28/fa/b2ba8229b9381e8f6381c1dcae6f4159a7f72349e414ed19cfbbd1817173/MouseInfo-0.1.3.tar.gz", hash = "sha256:2c62fb8885062b8e520a3cce0a297c657adcc08c60952eb05bc8256ef6f7f6e7", size = 10850, upload-time = "2020-03-27T21:20:10.136Z" }
 
+[[package]]
+name = "mss"
+version = "10.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/40/ca/49b67437a8c46d9732c9c274d7b1fc0c181cfe290d699a0c5e94701dfe79/mss-10.1.0.tar.gz", hash = "sha256:7182baf7ee16ca569e2804028b6ab9bcbf6be5c46fc2880840f33b513b9cb4f8", size = 84200, upload-time = "2025-08-16T12:11:00.119Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/23/28/1e3e5cd1d677cca68b26166f704f72e35b1e8b6d5076d8ebeebc4e40a649/mss-10.1.0-py3-none-any.whl", hash = "sha256:9179c110cadfef5dc6dc4a041a0cd161c74c379218648e6640b48c6b5cfe8918", size = 24525, upload-time = "2025-08-16T12:10:59.111Z" },
+]
+
 [[package]]
 name = "oagi"
-version = "0.14.0"
+version = "0.14.2"
 source = { editable = "." }
 dependencies = [
     { name = "oagi-core", extra = ["desktop", "server"] },
 ]
 
 [package.metadata]
-requires-dist = [{ name = "oagi-core", extras = ["desktop", "server"], specifier = "==0.13.2" }]
+requires-dist = [{ name = "oagi-core", extras = ["desktop", "server"], specifier = "==0.14.1" }]
 
 [[package]]
 name = "oagi-core"
-version = "0.13.2"
+version = "0.14.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "httpx" },
@@ -537,13 +546,14 @@ dependencies = [
     { name = "pydantic" },
     { name = "rich" },
 ]
-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" }
+sdist = { url = "https://files.pythonhosted.org/packages/94/20/3dfff9883e8786fc0b79ea915ba83cfbce3addd3149568601b80c3bc83a3/oagi_core-0.14.1.tar.gz", hash = "sha256:407faa59b3ced203901a1b35a5b3bc25407e8b61f82ab9b202f01412c73175bf", size = 310008, upload-time = "2026-01-23T08:09:08.54Z" }
 wheels = [
-    { 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" },
+    { url = "https://files.pythonhosted.org/packages/62/d1/4485bbddbdf1868aa46deaa98d49ad4624e243c9b32321c81374402bcde8/oagi_core-0.14.1-py3-none-any.whl", hash = "sha256:36b0e10a79c0508eedd28f8a5d89230b7236452ed64bed7150b22f99a50f1a18", size = 114938, upload-time = "2026-01-23T08:09:07.4Z" },
 ]
 
 [package.optional-dependencies]
 desktop = [
+    { name = "mss", marker = "sys_platform == 'win32'" },
     { name = "pillow" },
     { name = "pyautogui" },
     { name = "pyobjc-framework-applicationservices", marker = "sys_platform == 'darwin'" },

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi-core"
-version = "0.14.0"
+version = "0.14.2"
 description = "Official API of OpenAGI Foundation"
 readme = "README.md"
 license = { file = "LICENSE" }

{oagi_core-0.14.0 → oagi_core-0.14.2}/src/oagi/__init__.py

@@ -38,6 +38,10 @@ from oagi.types.models import (
 # Format: name -> (module_path, package_to_check, extra_name)
 # package_to_check is None if no optional dependency is required
 _LAZY_IMPORTS_DATA: dict[str, tuple[str, str | None, str | None]] = {
+    # Action converters (no optional dependencies)
+    "OagiActionConverter": ("oagi.converters.oagi", None, None),
+    "ConverterConfig": ("oagi.converters.base", None, None),
+    "BaseActionConverter": ("oagi.converters.base", None, None),
     # Desktop handlers (require pyautogui/PIL)
     "AsyncPyautoguiActionHandler": (
         "oagi.handler.async_pyautogui_action_handler",
@@ -88,6 +92,8 @@ if TYPE_CHECKING:
     from oagi.agent.default import AsyncDefaultAgent
     from oagi.agent.observer.agent_observer import AsyncAgentObserver
     from oagi.agent.tasker import TaskerAgent
+    from oagi.converters.base import BaseActionConverter, ConverterConfig
+    from oagi.converters.oagi import OagiActionConverter
     from oagi.handler.async_pyautogui_action_handler import AsyncPyautoguiActionHandler
     from oagi.handler.async_screenshot_maker import AsyncScreenshotMaker
     from oagi.handler.async_ydotool_action_handler import AsyncYdotoolActionHandler
@@ -174,4 +180,8 @@ __all__ = [
     "YdotoolConfig",
     # Lazy imports - Screen manager
     "ScreenManager",
+    # Lazy imports - Action converters
+    "OagiActionConverter",
+    "ConverterConfig",
+    "BaseActionConverter",
 ]

{oagi_core-0.14.0 → oagi_core-0.14.2}/src/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_core-0.14.0 → oagi_core-0.14.2}/src/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_core-0.14.2/src/oagi/converters/__init__.py

@@ -0,0 +1,56 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+"""Action converters for VLM support.
+
+This module provides the base class and OAGI implementation for action converters.
+Third parties can inherit from BaseActionConverter to create custom converters.
+
+Example usage:
+    from oagi.converters import OagiActionConverter, ConverterConfig
+
+    # Configure for 1920x1080 sandbox
+    config = ConverterConfig(sandbox_width=1920, sandbox_height=1080)
+    converter = OagiActionConverter(config=config)
+
+    # Convert OAGI actions to pyautogui strings
+    result = converter(actions)  # list[str]
+
+    # Convert to runtime API steps
+    for cmd in result:
+        step = converter.action_string_to_step(cmd)
+        # Execute step via runtime API...
+
+Creating custom converters:
+    from oagi.converters import BaseActionConverter, ConverterConfig
+
+    class MyActionConverter(BaseActionConverter[MyAction]):
+        @property
+        def coord_width(self) -> int:
+            return 1000  # Your model's coordinate width
+
+        @property
+        def coord_height(self) -> int:
+            return 1000  # Your model's coordinate height
+
+        def _convert_single_action(self, action: MyAction) -> list[str]:
+            # Convert action to pyautogui command strings
+            ...
+
+        def serialize_actions(self, actions: list[MyAction]) -> list[dict]:
+            # Serialize actions for trajectory logging
+            ...
+"""
+
+from .base import BaseActionConverter, ConverterConfig
+from .oagi import OagiActionConverter
+
+__all__ = [
+    "BaseActionConverter",
+    "ConverterConfig",
+    "OagiActionConverter",
+]

oagi_core-0.14.2/src/oagi/converters/base.py

@@ -0,0 +1,292 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+"""Base class for action converters.
+
+This module provides the abstract base class for converting model-specific
+actions to pyautogui command strings for remote execution.
+"""
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from ..handler.capslock_manager import CapsLockManager
+from ..handler.utils import (
+    CoordinateScaler,
+    normalize_key,
+    parse_hotkey,
+    validate_keys,
+)
+
+T = TypeVar("T")
+
+
+@dataclass
+class ConverterConfig:
+    """Configuration for action converters.
+
+    Matches the configuration options in PyautoguiConfig for consistency.
+    """
+
+    sandbox_width: int = 1920
+    sandbox_height: int = 1080
+    drag_duration: float = 0.5
+    scroll_amount: int = 2
+    wait_duration: float = 1.0
+    hotkey_interval: float = 0.1
+    capslock_mode: str = "session"
+    strict_coordinate_validation: bool = False
+    """If True, raise ValueError when coordinates are outside valid range.
+    If False (default), clamp coordinates to valid range (original behavior)."""
+
+
+class BaseActionConverter(ABC, Generic[T]):
+    """Abstract base class for action converters.
+
+    Subclasses must implement:
+    - coord_width/coord_height properties for input coordinate space
+    - _convert_single_action() for model-specific conversion logic
+    - serialize_actions() for trajectory logging
+
+    Provides common functionality:
+    - Coordinate scaling via CoordinateScaler
+    - Key normalization via shared utils
+    - __call__ interface returning list of action strings
+    - action_string_to_step() for runtime API format
+    """
+
+    def __init__(
+        self,
+        *,
+        config: ConverterConfig | None = None,
+        logger: Any | None = None,
+    ):
+        """Initialize the converter.
+
+        Args:
+            config: Converter configuration. Uses defaults if not provided.
+            logger: Optional logger instance for debug/error logging.
+        """
+        self.config = config or ConverterConfig()
+        self.logger = logger
+
+        # Initialize coordinate scaler
+        self._coord_scaler = CoordinateScaler(
+            source_width=self.coord_width,
+            source_height=self.coord_height,
+            target_width=self.config.sandbox_width,
+            target_height=self.config.sandbox_height,
+        )
+
+        # Initialize caps lock manager
+        self.caps_manager = CapsLockManager(mode=self.config.capslock_mode)
+
+        # Track last cursor position (for actions without explicit coordinates)
+        self._last_x: int | None = None
+        self._last_y: int | None = None
+
+    @property
+    @abstractmethod
+    def coord_width(self) -> int:
+        """Input coordinate space width (e.g., 1024 for XGA, 1000 for OAGI)."""
+        ...
+
+    @property
+    @abstractmethod
+    def coord_height(self) -> int:
+        """Input coordinate space height (e.g., 768 for XGA, 1000 for OAGI)."""
+        ...
+
+    @property
+    def scale_x(self) -> float:
+        """X scaling factor from input to sandbox coordinates."""
+        return self._coord_scaler.scale_x
+
+    @property
+    def scale_y(self) -> float:
+        """Y scaling factor from input to sandbox coordinates."""
+        return self._coord_scaler.scale_y
+
+    def scale_coordinate(self, x: int | float, y: int | float) -> tuple[int, int]:
+        """Scale coordinates from model space to sandbox space.
+
+        Args:
+            x: X coordinate in model space
+            y: Y coordinate in model space
+
+        Returns:
+            Tuple of (scaled_x, scaled_y) in sandbox space
+        """
+        return self._coord_scaler.scale(x, y)
+
+    def normalize_key(self, key: str) -> str:
+        """Normalize a key name to pyautogui format.
+
+        Args:
+            key: Key name to normalize
+
+        Returns:
+            Normalized key name
+        """
+        return normalize_key(key)
+
+    def parse_hotkey(self, hotkey_str: str, *, validate: bool = True) -> list[str]:
+        """Parse a hotkey string into a list of normalized key names.
+
+        Args:
+            hotkey_str: Hotkey string (e.g., "ctrl+c")
+            validate: If True, validate keys against PYAUTOGUI_VALID_KEYS
+
+        Returns:
+            List of normalized key names
+        """
+        return parse_hotkey(hotkey_str, validate=validate)
+
+    def validate_keys(self, keys: list[str]) -> None:
+        """Validate that all keys are recognized by pyautogui.
+
+        Args:
+            keys: List of key names to validate
+
+        Raises:
+            ValueError: If any key is invalid
+        """
+        validate_keys(keys)
+
+    def _get_last_or_center(self) -> tuple[int, int]:
+        """Get last cursor position or screen center as fallback.
+
+        Returns:
+            Tuple of (x, y) coordinates
+        """
+        if self._last_x is not None and self._last_y is not None:
+            return self._last_x, self._last_y
+        return self.config.sandbox_width // 2, self.config.sandbox_height // 2
+
+    def _log_error(self, message: str) -> None:
+        """Log an error message if logger is available."""
+        if self.logger:
+            self.logger.error(message)
+
+    def _log_info(self, message: str) -> None:
+        """Log an info message if logger is available."""
+        if self.logger:
+            self.logger.info(message)
+
+    def _log_debug(self, message: str) -> None:
+        """Log a debug message if logger is available."""
+        if self.logger:
+            self.logger.debug(message)
+
+    def __call__(self, actions: list[T]) -> list[str]:
+        """Convert actions to list of pyautogui command strings.
+
+        Args:
+            actions: List of model-specific action objects
+
+        Returns:
+            List of pyautogui command strings
+
+        Raises:
+            RuntimeError: If all action conversions failed
+        """
+        converted: list[str] = []
+        failed: list[tuple[str, str]] = []
+        skipped: list[str] = []
+
+        if not actions:
+            return converted
+
+        for action in actions:
+            try:
+                action_strings = self._convert_single_action(action)
+
+                if not action_strings:
+                    # No-op action (e.g., screenshot, cursor_position)
+                    action_type = getattr(action, "action_type", repr(action))
+                    skipped.append(str(action_type))
+                    continue
+
+                converted.extend(action_strings)
+
+            except Exception as e:
+                action_repr = repr(action)
+                self._log_error(f"Failed to convert action: {action_repr}, error: {e}")
+                failed.append((action_repr, str(e)))
+
+        if skipped:
+            self._log_debug(f"Skipped no-op actions: {skipped}")
+
+        if not converted and actions and failed:
+            raise RuntimeError(
+                f"All action conversions failed ({len(failed)}/{len(actions)}): {failed}"
+            )
+
+        return converted
+
+    @abstractmethod
+    def _convert_single_action(self, action: T) -> list[str]:
+        """Convert a single action to pyautogui command string(s).
+
+        Args:
+            action: Model-specific action object
+
+        Returns:
+            List of pyautogui command strings (may be empty for no-op actions)
+
+        Raises:
+            ValueError: If action format is invalid
+        """
+        ...
+
+    @abstractmethod
+    def serialize_actions(self, actions: list[T]) -> list[dict[str, Any]]:
+        """Serialize actions for trajectory logging.
+
+        Args:
+            actions: List of model-specific action objects
+
+        Returns:
+            List of serialized action dictionaries
+        """
+        ...
+
+    def action_string_to_step(self, action: str) -> dict[str, Any]:
+        """Convert an action string into a step for runtime/do API.
+
+        Args:
+            action: Action string (e.g., "pyautogui.click(x=100, y=200)")
+
+        Returns:
+            Step dict for runtime API
+        """
+        action_str = str(action).strip()
+
+        # Special markers
+        upper = action_str.upper()
+        if upper in ["DONE", "FAIL"]:
+            return {"type": "sleep", "parameters": {"seconds": 0}}
+
+        # WAIT(seconds)
+        wait_match = re.match(
+            r"^WAIT\((?P<sec>[0-9]*\.?[0-9]+)\)$", action_str, re.IGNORECASE
+        )
+        if wait_match:
+            seconds = float(wait_match.group("sec"))
+            return {"type": "sleep", "parameters": {"seconds": seconds}}
+
+        # pyautogui code path
+        if "pyautogui" in action_str.lower():
+            return {
+                "type": "pyautogui",
+                "parameters": {"code": action_str},
+            }
+
+        # Default: shell command
+        return {"type": "execute", "parameters": {"command": action_str, "shell": True}}