hud-python 0.2.10__py3-none-any.whl → 0.3.1__py3-none-any.whl

hud/tools/edit.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+from typing import Any, Literal, get_args
+
+from .base import CLIResult, ToolError, ToolResult
+from .utils import maybe_truncate, run
+
+Command = Literal[
+    "view",
+    "create",
+    "str_replace",
+    "insert",
+    "undo_edit",
+]
+SNIPPET_LINES: int = 4
+
+
+class EditTool:
+    """
+    An filesystem editor tool that allows the agent to view, create, and edit files.
+    The tool parameters are defined by Anthropic and are not editable.
+    """
+
+    _file_history: dict[Path, list[str]]
+
+    def __init__(self) -> None:
+        self._file_history = defaultdict(list)
+
+    async def __call__(
+        self,
+        *,
+        command: Command,
+        path: str,
+        file_text: str | None = None,
+        view_range: list[int] | None = None,
+        old_str: str | None = None,
+        new_str: str | None = None,
+        insert_line: int | None = None,
+        **kwargs: Any,
+    ) -> CLIResult:
+        _path = Path(path)
+        self.validate_path(command, _path)
+        if command == "view":
+            return await self.view(_path, view_range)
+        elif command == "create":
+            if file_text is None:
+                raise ToolError("Parameter `file_text` is required for command: create")
+            await self.write_file(_path, file_text)
+            self._file_history[_path].append(file_text)
+            return ToolResult(output=f"File created successfully at: {_path}")
+        elif command == "str_replace":
+            if old_str is None:
+                raise ToolError("Parameter `old_str` is required for command: str_replace")
+            return await self.str_replace(_path, old_str, new_str)
+        elif command == "insert":
+            if insert_line is None:
+                raise ToolError("Parameter `insert_line` is required for command: insert")
+            if new_str is None:
+                raise ToolError("Parameter `new_str` is required for command: insert")
+            return await self.insert(_path, insert_line, new_str)
+        elif command == "undo_edit":
+            return await self.undo_edit(_path)
+        raise ToolError(
+            f"Unrecognized command {command}. The allowed commands for the {self.name} tool are: "
+            f"{', '.join(get_args(Command))}"
+        )
+
+    def validate_path(self, command: str, path: Path) -> None:
+        """
+        Check that the path/command combination is valid.
+        """
+        # Check if its an absolute path
+        if not path.is_absolute():
+            suggested_path = Path("") / path
+            raise ToolError(
+                f"The path {path} is not an absolute path, it should start with `/`. "
+                f"Maybe you meant {suggested_path}?"
+            )
+        # Check if path exists
+        if not path.exists() and command != "create":
+            raise ToolError(f"The path {path} does not exist. Please provide a valid path.")
+        if path.exists() and command == "create":
+            raise ToolError(
+                f"File already exists at: {path}. Cannot overwrite files using command `create`."
+            )
+        # Check if the path points to a directory
+        if path.is_dir() and command != "view":
+            raise ToolError(
+                f"The path {path} is a dir and only the `view` command can be used on dirs."
+            )
+
+    async def view(self, path: Path, view_range: list[int] | None = None) -> CLIResult:
+        """Implement the view command"""
+        if path.is_dir():
+            if view_range:
+                raise ToolError(
+                    "The `view_range` parameter is not allowed when `path` points to a directory."
+                )
+
+            import shlex
+
+            safe_path = shlex.quote(str(path))
+            _, stdout, stderr = await run(rf"find {safe_path} -maxdepth 2 -not -path '*/\.*'")
+            if not stderr:
+                stdout = (
+                    f"Here's the files and directories up to 2 levels deep in {path}, "
+                    f"excluding hidden items:\n{stdout}\n"
+                )
+            return CLIResult(output=stdout, error=stderr)
+
+        file_content = await self.read_file(path)
+        init_line = 1
+        if view_range:
+            if len(view_range) != 2 or not all(isinstance(i, int) for i in view_range):
+                raise ToolError("Invalid `view_range`. It should be a list of two integers.")
+            file_lines = file_content.split("\n")
+            n_lines_file = len(file_lines)
+            init_line, final_line = view_range
+            if init_line < 1 or init_line > n_lines_file:
+                raise ToolError(
+                    f"Invalid `view_range`: {view_range}. Its first element `{init_line}` "
+                    f"should be within the range of lines of the file: {[1, n_lines_file]}"
+                )
+            if final_line > n_lines_file:
+                raise ToolError(
+                    f"Invalid `view_range`: {view_range}. Its second element `{final_line}` "
+                    f"should be smaller than the number of lines in the file: `{n_lines_file}`"
+                )
+            if final_line != -1 and final_line < init_line:
+                raise ToolError(
+                    f"Invalid `view_range`: {view_range}. Its second element `{final_line}` "
+                    f"should be larger or equal than its first `{init_line}`"
+                )
+
+            if final_line == -1:
+                file_content = "\n".join(file_lines[init_line - 1 :])
+            else:
+                file_content = "\n".join(file_lines[init_line - 1 : final_line])
+
+        return CLIResult(output=self._make_output(file_content, str(path), init_line=init_line))
+
+    async def str_replace(self, path: Path, old_str: str, new_str: str | None) -> CLIResult:
+        """
+        Implement the str_replace command, which replaces old_str with new_str in the file content.
+        """
+        # Read the file content
+        file_content = (await self.read_file(path)).expandtabs()
+        old_str = old_str.expandtabs()
+        new_str = new_str.expandtabs() if new_str is not None else ""
+
+        # Check if old_str is unique in the file
+        occurrences = file_content.count(old_str)
+        if occurrences == 0:
+            raise ToolError(
+                f"No replacement was performed, old_str `{old_str}` did not appear verbatim in "
+                f"{path}."
+            )
+        elif occurrences > 1:
+            file_content_lines = file_content.split("\n")
+            lines = [idx + 1 for idx, line in enumerate(file_content_lines) if old_str in line]
+            raise ToolError(
+                f"No replacement was performed. Multiple occurrences of old_str `{old_str}` "
+                f"in lines {lines}. Please ensure it is unique"
+            )
+
+        # Replace old_str with new_str
+        new_file_content = file_content.replace(old_str, new_str)
+
+        # Write the new content to the file
+        await self.write_file(path, new_file_content)
+
+        # Save the content to history
+        self._file_history[path].append(file_content)
+
+        # Create a snippet of the edited section
+        replacement_line = file_content.split(old_str)[0].count("\n")
+        start_line = max(0, replacement_line - SNIPPET_LINES)
+        end_line = replacement_line + SNIPPET_LINES + new_str.count("\n")
+        snippet = "\n".join(new_file_content.split("\n")[start_line : end_line + 1])
+
+        # Prepare the success message
+        success_msg = f"The file {path} has been edited. "
+        success_msg += self._make_output(snippet, f"a snippet of {path}", start_line + 1)
+        success_msg += (
+            "Review the changes and make sure they are as expected. "
+            "Edit the file again if necessary."
+        )
+
+        return CLIResult(output=success_msg)
+
+    async def insert(self, path: Path, insert_line: int, new_str: str) -> CLIResult:
+        """
+        Implement the insert command, which inserts new_str at the specified line in the file.
+        """
+        file_text = (await self.read_file(path)).expandtabs()
+        new_str = new_str.expandtabs()
+        file_text_lines = file_text.split("\n")
+        n_lines_file = len(file_text_lines)
+
+        if insert_line < 0 or insert_line > n_lines_file:
+            raise ToolError(
+                f"Invalid `insert_line` parameter: {insert_line}. It should be within the range "
+                f"of lines of the file: {[0, n_lines_file]}"
+            )
+
+        new_str_lines = new_str.split("\n")
+        new_file_text_lines = (
+            file_text_lines[:insert_line] + new_str_lines + file_text_lines[insert_line:]
+        )
+        snippet_lines = (
+            file_text_lines[max(0, insert_line - SNIPPET_LINES) : insert_line]
+            + new_str_lines
+            + file_text_lines[insert_line : insert_line + SNIPPET_LINES]
+        )
+
+        new_file_text = "\n".join(new_file_text_lines)
+        snippet = "\n".join(snippet_lines)
+
+        await self.write_file(path, new_file_text)
+        self._file_history[path].append(file_text)
+
+        success_msg = f"The file {path} has been edited. "
+        success_msg += self._make_output(
+            snippet,
+            "a snippet of the edited file",
+            max(1, insert_line - SNIPPET_LINES + 1),
+        )
+        success_msg += (
+            "Review the changes and make sure they are as expected (correct indentation, "
+            "no duplicate lines, etc). Edit the file again if necessary."
+        )
+        return CLIResult(output=success_msg)
+
+    async def undo_edit(self, path: Path) -> CLIResult:
+        """Implement the undo_edit command."""
+        if not self._file_history[path]:
+            raise ToolError(f"No edit history found for {path}.")
+
+        old_text = self._file_history[path].pop()
+        await self.write_file(path, old_text)
+
+        return CLIResult(
+            output=f"Last edit to {path} undone successfully. "
+            f"{self._make_output(old_text, str(path))}"
+        )
+
+    async def read_file(self, path: Path) -> str:
+        """Read the content of a file from a given path; raise a ToolError if an error occurs."""
+        try:
+            import shlex
+
+            safe_path = shlex.quote(str(path))
+            code, out, err = await run(f"cat {safe_path}")
+            if code != 0:
+                raise ToolError(f"Ran into {err} while trying to read {path}")
+            return out
+        except Exception as e:
+            raise ToolError(f"Ran into {e} while trying to read {path}") from None
+
+    async def write_file(self, path: Path, file: str) -> None:
+        """Write the content of a file to a given path; raise a ToolError if an error occurs."""
+        try:
+            import shlex
+
+            safe_path = shlex.quote(str(path))
+            code, _, err = await run(f"cat > {safe_path} << 'EOF'\n{file}\nEOF")
+            if code != 0:
+                raise ToolError(f"Ran into {err} while trying to write to {path}")
+        except Exception as e:
+            raise ToolError(f"Ran into {e} while trying to write to {path}") from None
+
+    def _make_output(
+        self,
+        file_content: str,
+        file_descriptor: str,
+        init_line: int = 1,
+        expand_tabs: bool = True,
+    ) -> str:
+        """Generate output for the CLI based on the content of a file."""
+        file_content = maybe_truncate(file_content)
+        if expand_tabs:
+            file_content = file_content.expandtabs()
+        file_content = "\n".join(
+            [f"{i + init_line:6}\t{line}" for i, line in enumerate(file_content.split("\n"))]
+        )
+        return (
+            f"Here's the result of running `cat -n` on {file_descriptor}:\n" + file_content + "\n"
+        )

hud/tools/executors/__init__.py

@@ -0,0 +1,30 @@
+"""Executors for running system commands."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import BaseExecutor
+
+if TYPE_CHECKING:
+    from .pyautogui import PyAutoGUIExecutor
+    from .xdo import XDOExecutor
+
+__all__ = [
+    "BaseExecutor",
+    "PyAutoGUIExecutor",
+    "XDOExecutor",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import executors to avoid importing pyautogui unless needed."""
+    if name == "PyAutoGUIExecutor":
+        from .pyautogui import PyAutoGUIExecutor
+
+        return PyAutoGUIExecutor
+    elif name == "XDOExecutor":
+        from .xdo import XDOExecutor
+
+        return XDOExecutor
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

hud/tools/executors/base.py

@@ -0,0 +1,331 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Literal
+
+from hud.tools.base import ToolResult
+
+logger = logging.getLogger(__name__)
+
+
+class BaseExecutor:
+    """
+    Base executor that provides simulation implementations for all CLA (Common Language Actions).
+
+    This class:
+    1. Defines all action methods that HudComputer expects
+    2. Provides simulation implementations for environments without display
+    3. Serves as the base class for platform-specific executors (XDO, PyAutoGUI)
+
+    When used directly, it simulates all actions. Subclasses provide real implementations.
+    """
+
+    def __init__(self, display_num: int | None = None) -> None:
+        """
+        Initialize the base executor.
+
+        Args:
+            display_num: X display number (for Linux/X11 systems)
+        """
+        self.display_num = display_num
+        self._screenshot_delay = 0.5
+        logger.info("BaseExecutor initialized")
+
+    # ===== Core CLA Actions =====
+
+    async def click(
+        self,
+        x: int | None = None,
+        y: int | None = None,
+        button: Literal["left", "right", "middle", "back", "forward"] = "left",
+        pattern: list[int] | None = None,
+        hold_keys: list[str] | None = None,
+        take_screenshot: bool = True,
+    ) -> ToolResult:
+        """
+        Click at specified coordinates.
+
+        Args:
+            x, y: Coordinates to click at (None = current position)
+            button: Mouse button to use
+            pattern: List of delays for multi-clicks (e.g., [100] for double-click)
+            hold_keys: Keys to hold during click
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = f"[SIMULATED] Click at ({x}, {y}) with {button} button"
+        if pattern:
+            msg += f" (multi-click pattern: {pattern})"
+        if hold_keys:
+            msg += f" while holding {hold_keys}"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def type(
+        self, text: str, enter_after: bool = False, delay: int = 12, take_screenshot: bool = True
+    ) -> ToolResult:
+        """
+        Type text using keyboard.
+
+        Args:
+            text: Text to type
+            enter_after: Whether to press Enter after typing
+            delay: Delay between keystrokes in milliseconds
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = f"[SIMULATED] Type '{text}'"
+        if enter_after:
+            msg += " followed by Enter"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def press(self, keys: list[str], take_screenshot: bool = True) -> ToolResult:
+        """
+        Press a key combination (hotkey).
+
+        Args:
+            keys: List of keys to press together (e.g., ["ctrl", "c"])
+            take_screenshot: Whether to capture screenshot after action
+        """
+        key_combo = "+".join(keys)
+        msg = f"[SIMULATED] Press key combination: {key_combo}"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def key(self, key_sequence: str, take_screenshot: bool = True) -> ToolResult:
+        """
+        Press a single key or key combination.
+
+        Args:
+            key_sequence: Key or combination like "Return" or "ctrl+a"
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = f"[SIMULATED] Press key: {key_sequence}"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def keydown(self, keys: list[str], take_screenshot: bool = True) -> ToolResult:
+        """
+        Press and hold keys.
+
+        Args:
+            keys: Keys to press and hold
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = f"[SIMULATED] Key down: {', '.join(keys)}"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def keyup(self, keys: list[str], take_screenshot: bool = True) -> ToolResult:
+        """
+        Release held keys.
+
+        Args:
+            keys: Keys to release
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = f"[SIMULATED] Key up: {', '.join(keys)}"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def scroll(
+        self,
+        x: int | None = None,
+        y: int | None = None,
+        scroll_x: int | None = None,
+        scroll_y: int | None = None,
+        hold_keys: list[str] | None = None,
+        take_screenshot: bool = True,
+    ) -> ToolResult:
+        """
+        Scroll at specified position.
+
+        Args:
+            x, y: Position to scroll at (None = current position)
+            scroll_x: Horizontal scroll amount (positive = right)
+            scroll_y: Vertical scroll amount (positive = down)
+            hold_keys: Keys to hold during scroll
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = "[SIMULATED] Scroll"
+        if x is not None and y is not None:
+            msg += f" at ({x}, {y})"
+        if scroll_x:
+            msg += f" horizontally by {scroll_x}"
+        if scroll_y:
+            msg += f" vertically by {scroll_y}"
+        if hold_keys:
+            msg += f" while holding {hold_keys}"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def move(
+        self,
+        x: int | None = None,
+        y: int | None = None,
+        offset_x: int | None = None,
+        offset_y: int | None = None,
+        take_screenshot: bool = True,
+    ) -> ToolResult:
+        """
+        Move mouse cursor.
+
+        Args:
+            x, y: Absolute coordinates to move to
+            offset_x, offset_y: Relative offset from current position
+            take_screenshot: Whether to capture screenshot after action
+        """
+        if x is not None and y is not None:
+            msg = f"[SIMULATED] Move mouse to ({x}, {y})"
+        elif offset_x is not None or offset_y is not None:
+            msg = f"[SIMULATED] Move mouse by offset ({offset_x or 0}, {offset_y or 0})"
+        else:
+            msg = "[SIMULATED] Move mouse (no coordinates specified)"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def drag(
+        self,
+        path: list[tuple[int, int]],
+        pattern: list[int] | None = None,
+        hold_keys: list[str] | None = None,
+        take_screenshot: bool = True,
+    ) -> ToolResult:
+        """
+        Drag along a path.
+
+        Args:
+            path: List of (x, y) coordinates defining the drag path
+            pattern: Delays between path points in milliseconds
+            hold_keys: Keys to hold during drag
+            take_screenshot: Whether to capture screenshot after action
+        """
+        if len(path) < 2:
+            return ToolResult(error="Drag path must have at least 2 points")
+
+        start = path[0]
+        end = path[-1]
+        msg = f"[SIMULATED] Drag from {start} to {end}"
+        if len(path) > 2:
+            msg += f" via {len(path) - 2} intermediate points"
+        if hold_keys:
+            msg += f" while holding {hold_keys}"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def mouse_down(
+        self,
+        button: Literal["left", "right", "middle", "back", "forward"] = "left",
+        take_screenshot: bool = True,
+    ) -> ToolResult:
+        """
+        Press and hold a mouse button.
+
+        Args:
+            button: Mouse button to press
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = f"[SIMULATED] Mouse down: {button} button"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def mouse_up(
+        self,
+        button: Literal["left", "right", "middle", "back", "forward"] = "left",
+        take_screenshot: bool = True,
+    ) -> ToolResult:
+        """
+        Release a mouse button.
+
+        Args:
+            button: Mouse button to release
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = f"[SIMULATED] Mouse up: {button} button"
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    async def hold_key(self, key: str, duration: float, take_screenshot: bool = True) -> ToolResult:
+        """
+        Hold a key for a specified duration.
+
+        Args:
+            key: The key to hold
+            duration: Duration in seconds
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = f"[SIMULATED] Hold key '{key}' for {duration} seconds"
+        await asyncio.sleep(duration)  # Simulate the wait
+
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    # ===== Utility Actions =====
+
+    async def wait(self, time: int) -> ToolResult:
+        """
+        Wait for specified time.
+
+        Args:
+            time: Time to wait in milliseconds
+        """
+        duration_seconds = time / 1000.0
+        await asyncio.sleep(duration_seconds)
+        return ToolResult(output=f"Waited {time}ms")
+
+    async def screenshot(self) -> str | None:
+        """
+        Take a screenshot and return base64 encoded image.
+
+        Returns:
+            Base64 encoded PNG image or None if failed
+        """
+        logger.info("[SIMULATION] Taking screenshot")
+        return "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="  # noqa: E501
+
+    async def position(self) -> ToolResult:
+        """
+        Get current cursor position.
+
+        Returns:
+            ToolResult with position information
+        """
+        return ToolResult(output="[SIMULATED] Mouse position: (0, 0)")
+
+    # ===== Legacy/Compatibility Methods =====
+
+    async def execute(self, command: str, take_screenshot: bool = True) -> ToolResult:
+        """
+        Execute a raw command (for backwards compatibility).
+
+        Args:
+            command: Command to execute
+            take_screenshot: Whether to capture screenshot after action
+        """
+        msg = f"[SIMULATED] Execute: {command}"
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ToolResult(output=msg, base64_image=screenshot)
+
+    # Compatibility aliases
+    async def type_text(
+        self, text: str, delay: int = 12, take_screenshot: bool = True
+    ) -> ToolResult:
+        """Alias for type() to maintain compatibility."""
+        return await self.type(
+            text, enter_after=False, delay=delay, take_screenshot=take_screenshot
+        )
+
+    async def mouse_move(self, x: int, y: int, take_screenshot: bool = True) -> ToolResult:
+        """Alias for move() to maintain compatibility."""
+        return await self.move(x=x, y=y, take_screenshot=take_screenshot)