use-computer-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{use_computer_cli-0.2.1 → use_computer_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: use-computer-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Execute input on a screen for computer-use agents: move, click, drag, scroll, type, key, screenshot.
 Project-URL: Homepage, https://github.com/applica-software-guru/use-computer
 Author: Bruno Fortunato

{use_computer_cli-0.2.1 → use_computer_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "use-computer-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "Execute input on a screen for computer-use agents: move, click, drag, scroll, type, key, screenshot."
 readme = "README.md"
 requires-python = ">=3.10"

{use_computer_cli-0.2.1 → use_computer_cli-0.3.0}/src/use_computer/accessibility/atspi.py

@@ -126,7 +126,31 @@ class AtspiProvider:
     # --- reading -----------------------------------------------------------------------------
 
     def windows(self) -> list[WindowInfo]:
-        return [info for info, _ in self._window_pairs()]
+        found = [info for info, _ in self._window_pairs()]
+        if any(info.active for info in found):
+            return found
+        # Nothing claims `active`. Some desktops only ever report `focused`, so fall back to it
+        # rather than returning a list with no mark at all -- but never mix the two: `focused` on
+        # this desktop marks the shell, which is not a window anybody wants to act in.
+        return [
+            info.model_copy(update={"active": info.id in self._focused_ids()})
+            for info in found
+        ]
+
+    def _focused_ids(self) -> frozenset[str]:
+        ids: set[str] = set()
+        try:
+            desktop = self._desktop()
+            for app_index, app in enumerate(self._children(desktop)):
+                try:
+                    for index, window in enumerate(self._children(app)):
+                        if "focused" in set(self._states(window)):
+                            ids.add(f"0/{app_index}/{index}")
+                except Exception:
+                    continue
+        except Exception:
+            return frozenset()
+        return frozenset(ids)
 
     def _window_pairs(self) -> list[tuple[WindowInfo, Any]]:
         """Every window, with the accessible it describes, so a match can be acted on."""
@@ -147,7 +171,7 @@ class AtspiProvider:
                                 app=app_name,
                                 pid=pid if pid > 0 else None,
                                 box=self._box(window),
-                                active="active" in states or "focused" in states,
+                                active="active" in states,
                             ),
                             window,
                         )
@@ -262,7 +286,7 @@ class AtspiProvider:
 
     def _is_active(self, window: Any) -> bool:
         states = set(self._states(window))
-        return "active" in states or "focused" in states
+        return "active" in states
 
     #: AT-SPI reports an element that is not currently rendered at INT_MIN with a 1x1 size --
     #: the items of a closed menu, for instance. That is a sentinel, not a position, and letting
@@ -378,6 +402,15 @@ class AtspiProvider:
                 return bool(interface.do_action(index))
         return False
 
+    def activate(self, window_id: str) -> bool:
+        """AT-SPI offers no raise for a window.
+
+        A window accessible reports no actions at all -- verified: `It supports: none` -- so there
+        is nothing native to call here. False tells the caller to focus a descendant instead,
+        which is what actually moves `_NET_ACTIVE_WINDOW`.
+        """
+        return False
+
     def close(self) -> None:
         self._index = {}
 

{use_computer_cli-0.2.1 → use_computer_cli-0.3.0}/src/use_computer/accessibility/ax.py

@@ -197,6 +197,17 @@ class AxProvider:
         roles.COLLAPSE: "AXPress",
     }
 
+    def activate(self, window_id: str) -> bool:
+        """macOS windows do accept a raise of their own: AXRaise."""
+        element = self._index.get(window_id)
+        if element is None:
+            return False
+        try:
+            status = self._api.AXUIElementPerformAction(element, "AXRaise")
+        except Exception:
+            return False
+        return bool(status == 0)
+
     def perform(self, node_id: str, action: str, value: str | None) -> bool:
         element = self._index.get(node_id)
         if element is None:

{use_computer_cli-0.2.1 → use_computer_cli-0.3.0}/src/use_computer/accessibility/base.py

@@ -50,6 +50,15 @@ class AccessibilityProvider(Protocol):
         nothing at all. ``False`` is what makes ``--via auto`` fall back to a coordinate click.
         """
 
+    def activate(self, window_id: str) -> bool:
+        """Bring a window forward, natively, if this platform has a way.
+
+        ``True`` means the window was raised. ``False`` is not a failure: it means this platform
+        offers no raise for a window object, and the caller should focus a descendant instead --
+        which raises the top-level window on all three. AT-SPI is the ``False`` case; a window
+        accessible there reports no actions at all.
+        """
+
     def close(self) -> None:
         """Release whatever the provider holds."""
 

{use_computer_cli-0.2.1 → use_computer_cli-0.3.0}/src/use_computer/accessibility/uia.py

@@ -167,6 +167,17 @@ class UiaProvider:
 
     # --- acting ------------------------------------------------------------------------------
 
+    def activate(self, window_id: str) -> bool:
+        """Windows has a native raise: `SetActive` on the top-level control."""
+        control = self._index.get(window_id)
+        if control is None:
+            return False
+        try:
+            return bool(control.SetActive())
+        except Exception:
+            # Not every control exposes it, and the caller has a working fallback.
+            return False
+
     def perform(self, node_id: str, action: str, value: str | None) -> bool:
         control = self._index.get(node_id)
         if control is None:

{use_computer_cli-0.2.1 → use_computer_cli-0.3.0}/src/use_computer/actions.py

@@ -7,6 +7,7 @@ in actuation units and canonical key names.
 
 from __future__ import annotations
 
+from difflib import get_close_matches
 from enum import Enum
 from pathlib import Path
 from typing import Annotated, Any, Literal
@@ -48,7 +49,25 @@ class BaseAction(BaseModel):
         return None
 
 
-class _Positioned(BaseAction):
+class _InAWindow(BaseAction):
+    """An action whose coordinate belongs to a particular window.
+
+    A coordinate lands on whatever window is in front. That is what a bare coordinate has always
+    meant, and it is fine until the agent meant a particular window -- which is most of the time.
+    Naming it here is how the caller says so, and the window is brought forward before the
+    coordinate is sent. Measured: two drags aimed at a canvas selected text in a terminal instead,
+    and `--verify` then confirmed the wrong action with the wrong evidence.
+    """
+
+    window: TreeScope | None = None
+
+    @field_validator("window", mode="before")
+    @classmethod
+    def _parse_scope(cls, value: Any) -> Any:
+        return TreeScope.parse(value) if isinstance(value, str) else value
+
+
+class _Positioned(_InAWindow):
     """An action that may carry a coordinate. Omitting it acts where the pointer already is."""
 
     x: int | None = None
@@ -130,7 +149,7 @@ class RightClickAction(_PositionedOrSelected):
     action: Literal["right_click"] = "right_click"
 
 
-class DragAction(BaseAction):
+class DragAction(_InAWindow):
     action: Literal["drag"] = "drag"
     from_x: int
     from_y: int
@@ -297,6 +316,23 @@ class ShowMenuAction(_ElementAction):
     action: Literal["show_menu"] = "show_menu"
 
 
+class ActivateAction(BaseAction):
+    """Bring a window forward and give it keyboard focus.
+
+    The only action whose target is a window rather than an element or a point. A window object
+    exposes no actions of its own on any of the three platforms -- AT-SPI answers `It supports:
+    none` -- so it is done by focusing a descendant, which raises the top-level window everywhere.
+    """
+
+    action: Literal["activate"] = "activate"
+    window: TreeScope
+
+    @field_validator("window", mode="before")
+    @classmethod
+    def _parse_scope(cls, value: Any) -> Any:
+        return TreeScope.parse(value) if isinstance(value, str) else value
+
+
 Action = Annotated[
     MoveAction
     | ClickAction
@@ -315,7 +351,8 @@ Action = Annotated[
     | CollapseAction
     | SelectAction
     | SetValueAction
-    | ShowMenuAction,
+    | ShowMenuAction
+    | ActivateAction,
     Field(discriminator="action"),
 ]
 
@@ -339,6 +376,72 @@ def selector_of(action: Action) -> NodeSelector | None:
 #: Parses a batch file: a JSON array of action objects, discriminated on `action`.
 ActionListAdapter: TypeAdapter[list[Action]] = TypeAdapter(list[Action])
 
+#: Every action name, in the spelling the discriminator uses.
+ACTION_NAMES: tuple[str, ...] = (
+    "move",
+    "click",
+    "double_click",
+    "right_click",
+    "drag",
+    "scroll",
+    "type",
+    "key",
+    "screenshot",
+    "tree",
+    "windows",
+    "focus",
+    "toggle",
+    "expand",
+    "collapse",
+    "select",
+    "set_value",
+    "show_menu",
+    "activate",
+)
+
+
+def _cli_spelling(name: str) -> str:
+    """How this action is spelled as a command: `set_value` is typed `set-value`."""
+    return name.replace("_", "-")
+
+
+def normalise_action_names(data: Any) -> Any:
+    """Accept the CLI's own spelling of an action name inside a batch.
+
+    The command is `use-computer set-value`; the batch wanted `set_value`. Same action, two
+    spellings, and nothing said so -- an agent that has just read `set-value --help` has no reason
+    to expect a different name three lines later.
+    """
+    if not isinstance(data, list):
+        return data
+    out = []
+    for item in data:
+        if isinstance(item, dict) and isinstance(item.get("action"), str):
+            item = {**item, "action": item["action"].replace("-", "_")}
+        out.append(item)
+    return out
+
+
+def check_action_names(data: Any) -> None:
+    """Fail on an unknown action with a sentence, before pydantic offers its union.
+
+    The union's own error is four hundred characters naming every variant except the one the
+    caller should have written. This is a message to somebody mid-task who cannot see the code.
+    """
+    if not isinstance(data, list):
+        return
+    for index, item in enumerate(data):
+        if not isinstance(item, dict):
+            continue
+        name = item.get("action")
+        if not isinstance(name, str) or name in ACTION_NAMES:
+            continue
+        close = get_close_matches(name, ACTION_NAMES, n=1, cutoff=0.6)
+        suggestion = f" Did you mean {_cli_spelling(close[0])!r}?" if close else ""
+        raise ValueError(
+            f"unknown action {_cli_spelling(name)!r} at index {index}.{suggestion}"
+        )
+
 #: Parses a single action object.
 ActionAdapter: TypeAdapter[Action] = TypeAdapter(Action)