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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: use-computer-cli
-Version: 0.3.0
+Version: 0.3.1
 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
@@ -52,6 +52,7 @@ Requires-Dist: mss>=10; extra == 'local'
 Requires-Dist: pynput>=1.8; extra == 'local'
 Provides-Extra: tree
 Requires-Dist: pyobjc-framework-applicationservices>=10; (sys_platform == 'darwin') and extra == 'tree'
+Requires-Dist: python-xlib>=0.33; (sys_platform == 'linux') and extra == 'tree'
 Requires-Dist: uiautomation>=2.0; (sys_platform == 'win32') and extra == 'tree'
 Provides-Extra: vnc
 Requires-Dist: vncdotool>=1.3; extra == 'vnc'

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "use-computer-cli"
-version = "0.3.0"
+version = "0.3.1"
 description = "Execute input on a screen for computer-use agents: move, click, drag, scroll, type, key, screenshot."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -52,6 +52,11 @@ vnc = ["vncdotool>=1.3"]
 # bindings come from the distro (python3-gi, gir1.2-atspi-2.0) and are reached with a
 # --system-site-packages virtualenv; the error message says so when they are absent.
 tree = [
+    # python-xlib reads _NET_ACTIVE_WINDOW, the only reliable answer to "which window is in
+    # front" -- AT-SPI reports `active` per application and marks several at once. A pure-Python
+    # wheel with no build step, which is exactly what PyGObject was not, so it does not
+    # reintroduce BUG-003. Imported softly: absent, or on Wayland, the tool falls back.
+    "python-xlib>=0.33; sys_platform == 'linux'",
     "uiautomation>=2.0; sys_platform == 'win32'",
     "pyobjc-framework-ApplicationServices>=10; sys_platform == 'darwin'",
 ]
@@ -102,6 +107,7 @@ module = [
     "ApplicationServices.*",
     "Quartz.*",
     "gi.*",
+    "Xlib.*",
     "uiautomation.*",
     "tomli",
 ]

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

@@ -17,7 +17,14 @@ from typing import Any
 from use_computer.accessibility import roles
 from use_computer.accessibility.base import require
 from use_computer.errors import UITreeUnavailableError, UseComputerError
-from use_computer.tree import Box, TreeScope, TreeScopeKind, UINode, WindowInfo
+from use_computer.tree import (
+    ActiveWindow,
+    Box,
+    TreeScope,
+    TreeScopeKind,
+    UINode,
+    WindowInfo,
+)
 
 #: Where a distro puts PyGObject. The compiled part carries the Python version it was built for,
 #: which is the fact that decides whether any of the advice below will work.
@@ -402,6 +409,47 @@ class AtspiProvider:
                 return bool(interface.do_action(index))
         return False
 
+    def active_window(self) -> ActiveWindow | None:
+        """Ask the window manager, because AT-SPI cannot answer this.
+
+        `_NET_ACTIVE_WINDOW` on the root window names exactly one window; AT-SPI's `active` state
+        is per application and marked three at once on the desktop that produced the bug. Imported
+        softly on purpose: no python-xlib, or a Wayland session that publishes no such property,
+        and the caller falls back to the flags.
+        """
+        try:
+            from Xlib import X, display
+        except ImportError:
+            return None
+        try:
+            connection = display.Display()
+        except Exception:
+            return None  # no X server: Wayland, or no session at all
+        try:
+            root = connection.screen().root
+            active = root.get_full_property(
+                connection.intern_atom("_NET_ACTIVE_WINDOW"), X.AnyPropertyType
+            )
+            if active is None or not active.value:
+                return None
+            window = connection.create_resource_object("window", active.value[0])
+            pid = window.get_full_property(
+                connection.intern_atom("_NET_WM_PID"), X.AnyPropertyType
+            )
+            name = window.get_full_property(
+                connection.intern_atom("_NET_WM_NAME"), connection.intern_atom("UTF8_STRING")
+            )
+            return ActiveWindow(
+                pid=int(pid.value[0]) if pid is not None and pid.value else None,
+                title=name.value.decode("utf-8", "replace") if name is not None else None,
+            )
+        except Exception:
+            # A hint that fails is not an error: the caller has a working fallback.
+            return None
+        finally:
+            with suppress(Exception):
+                connection.close()
+
     def activate(self, window_id: str) -> bool:
         """AT-SPI offers no raise for a window.
 

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

@@ -15,7 +15,14 @@ from typing import Any
 from use_computer.accessibility import roles
 from use_computer.accessibility.base import require
 from use_computer.errors import PermissionDeniedError
-from use_computer.tree import Box, TreeScope, TreeScopeKind, UINode, WindowInfo
+from use_computer.tree import (
+    ActiveWindow,
+    Box,
+    TreeScope,
+    TreeScopeKind,
+    UINode,
+    WindowInfo,
+)
 
 #: kAXErrorAPIDisabled -- the process is not trusted for accessibility.
 API_DISABLED = -25211
@@ -197,6 +204,10 @@ class AxProvider:
         roles.COLLAPSE: "AXPress",
     }
 
+    def active_window(self) -> ActiveWindow | None:
+        """This platform's own `active` flag is already per window, so there is nothing to add."""
+        return None
+
     def activate(self, window_id: str) -> bool:
         """macOS windows do accept a raise of their own: AXRaise."""
         element = self._index.get(window_id)

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

@@ -15,7 +15,7 @@ from types import ModuleType
 from typing import Protocol, runtime_checkable
 
 from use_computer.errors import UITreeUnavailableError
-from use_computer.tree import TreeScope, UINode, WindowInfo
+from use_computer.tree import ActiveWindow, TreeScope, UINode, WindowInfo
 
 
 @runtime_checkable
@@ -59,6 +59,15 @@ class AccessibilityProvider(Protocol):
         accessible there reports no actions at all.
         """
 
+    def active_window(self) -> ActiveWindow | None:
+        """What the window manager says is in front, as a pid and a title.
+
+        A *hint*. ``None`` means this platform has nothing better than the per-window flags, which
+        is the honest answer on Wayland or without the optional binding. Matching it to a window is
+        policy and lives in ``selectors.mark_active``: a rule that lives in a provider is a rule
+        the other two platforms drift from, which has already happened once here.
+        """
+
     def close(self) -> None:
         """Release whatever the provider holds."""
 

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

@@ -11,7 +11,14 @@ from typing import Any
 from use_computer.accessibility import roles
 from use_computer.accessibility.base import require
 from use_computer.errors import UITreeUnavailableError
-from use_computer.tree import Box, TreeScope, TreeScopeKind, UINode, WindowInfo
+from use_computer.tree import (
+    ActiveWindow,
+    Box,
+    TreeScope,
+    TreeScopeKind,
+    UINode,
+    WindowInfo,
+)
 
 
 class UiaProvider:
@@ -167,6 +174,10 @@ class UiaProvider:
 
     # --- acting ------------------------------------------------------------------------------
 
+    def active_window(self) -> ActiveWindow | None:
+        """This platform's own `active` flag is already per window, so there is nothing to add."""
+        return None
+
     def activate(self, window_id: str) -> bool:
         """Windows has a native raise: `SetActive` on the top-level control."""
         control = self._index.get(window_id)

{use_computer_cli-0.3.0 → use_computer_cli-0.3.1}/src/use_computer/cli.py

@@ -1210,40 +1210,67 @@ def skill_install_command(
     scope: ScopeOption = Scope.PROJECT,
     dir: DirOption = None,
     force: Annotated[bool, typer.Option("--force", help="Overwrite an existing copy.")] = False,
+    format: FormatOption = OutputFormat.TEXT,
 ) -> None:
     """Install the bundled skill."""
     try:
         state = skill_install(scope, override=dir, force=force)
     except UseComputerError as exc:
         _fail(exc)
-    _emit({"action": "install", **_skill_json(state)})
+    _skill_say("install", state, format)
 
 
 @skill_app.command("update")
-def skill_update_command(scope: ScopeOption = Scope.PROJECT, dir: DirOption = None) -> None:
+def skill_update_command(
+    scope: ScopeOption = Scope.PROJECT,
+    dir: DirOption = None,
+    format: FormatOption = OutputFormat.TEXT,
+) -> None:
     """Refresh an installed skill from the bundled copy."""
     try:
         state = skill_update(scope, override=dir)
     except UseComputerError as exc:
         _fail(exc)
-    _emit({"action": "update", **_skill_json(state)})
+    _skill_say("update", state, format)
 
 
 @skill_app.command("remove")
-def skill_remove_command(scope: ScopeOption = Scope.PROJECT, dir: DirOption = None) -> None:
+def skill_remove_command(
+    scope: ScopeOption = Scope.PROJECT,
+    dir: DirOption = None,
+    format: FormatOption = OutputFormat.TEXT,
+) -> None:
     """Remove an installed skill."""
     try:
         state = skill_remove(scope, override=dir)
     except UseComputerError as exc:
         _fail(exc)
-    _emit({"action": "remove", **_skill_json(state)})
+    _skill_say("remove", state, format)
 
 
 @skill_app.command("status")
-def skill_status_command(scope: ScopeOption = Scope.PROJECT, dir: DirOption = None) -> None:
+def skill_status_command(
+    scope: ScopeOption = Scope.PROJECT,
+    dir: DirOption = None,
+    format: FormatOption = OutputFormat.TEXT,
+) -> None:
     """Report whether the skill is installed and current."""
     state = skill_status(scope, override=dir)
-    _emit({"action": "status", **_skill_json(state)})
+    _skill_say("status", state, format)
+
+
+def _skill_say(action: str, state: Any, format: OutputFormat) -> None:
+    """The skill commands answer in text like everything else.
+
+    This is the command an agent runs to find out whether its own instructions are current, and it
+    was the last one still replying with a JSON object. A contract with three exceptions is not a
+    contract.
+    """
+    payload = {"action": action, **_skill_json(state)}
+    if format is OutputFormat.JSON:
+        _emit(payload)
+        return
+    _write(render.skill(payload))
 
 
 def _skill_json(state: Any) -> dict[str, Any]:

{use_computer_cli-0.3.0 → use_computer_cli-0.3.1}/src/use_computer/render.py

@@ -159,6 +159,17 @@ def config(payload: Mapping[str, Any]) -> str:
     return "\n".join(lines)
 
 
+def skill(payload: Mapping[str, Any]) -> str:
+    """What a `skill` command did, on one line: action, scope, state, path."""
+    parts = [
+        str(payload.get("action", "")),
+        str(payload.get("scope", "")),
+        str(payload.get("status", "")),
+        str(payload.get("path", "")),
+    ]
+    return "  ".join(part for part in parts if part)
+
+
 __all__ = [
     "TREE_LEGEND",
     "WINDOWS_LEGEND",
@@ -166,4 +177,5 @@ __all__ = [
     "windows",
     "windows_for_a_reader",
     "config",
+    "skill",
 ]

{use_computer_cli-0.3.0 → use_computer_cli-0.3.1}/src/use_computer/runner.py

@@ -68,12 +68,12 @@ from use_computer.selectors import (
     clamp_text,
     count,
     find,
+    mark_active,
     mark_unexposed,
     notable_states,
     prune,
     resolve_one,
     resolve_window,
-    sole_active,
     subtree,
     summarise_offscreen,
     walk,
@@ -428,7 +428,7 @@ class Session:
             return _Outcome(tree=self._tree(action))
 
         if isinstance(action, WindowsAction):
-            found = tuple(sole_active(self._provider().windows()))
+            found = tuple(self._window_list())
             if action.format is OutputFormat.JSON:
                 return _Outcome(windows=WindowsResult(windows=found))
             return _Outcome(windows=WindowsResult(text=render.windows(found)))
@@ -540,9 +540,19 @@ class Session:
         again = self._window_for(resolved)
         return self._name_window(again) if again is not None else root.describe()
 
+    def _window_list(self) -> list[WindowInfo]:
+        """The windows, with the active mark settled once.
+
+        Settled here rather than in each provider, and with the window manager's answer preferred
+        over the per-window flags where a provider can offer one.
+        """
+        provider = self._provider()
+        entries: list[WindowInfo] = mark_active(provider.windows(), provider.active_window())
+        return entries
+
     def _window_for(self, scope: TreeScope) -> WindowInfo | None:
         """The entry in `windows` this scope names, when it names exactly one."""
-        entries = sole_active(self._provider().windows())
+        entries = self._window_list()
         if scope.kind is TreeScopeKind.FOCUSED:
             return next((entry for entry in entries if entry.active), None)
         if scope.kind is TreeScopeKind.ID:
@@ -632,8 +642,7 @@ class Session:
             # windows claiming to be active is not an answer, and picking the first is how an
             # agent reads, clicks and verifies inside the wrong application, consistently.
             return TreeScope(
-                kind=TreeScopeKind.ID,
-                value=active_window(sole_active(self._provider().windows())).id,
+                kind=TreeScopeKind.ID, value=active_window(self._window_list()).id
             )
         if scope.kind is not TreeScopeKind.TITLE or not scope.value:
             return scope

{use_computer_cli-0.3.0 → use_computer_cli-0.3.1}/src/use_computer/selectors.py

@@ -15,7 +15,7 @@ from use_computer.errors import (
     NodeNotFoundError,
     UITreeUnavailableError,
 )
-from use_computer.tree import Box, NodeSelector, UINode, WindowInfo
+from use_computer.tree import ActiveWindow, Box, NodeSelector, UINode, WindowInfo
 
 #: Roles that are worth keeping even when the platform reports no actions and no name -- an
 #: empty text field has nothing to say about itself and is still the thing an agent came for.
@@ -111,6 +111,37 @@ def is_interesting(node: UINode) -> bool:
     return is_on_screen(node) and (is_interactable(node) or carries_text(node))
 
 
+def mark_active(
+    entries: Sequence[WindowInfo], hint: ActiveWindow | None = None
+) -> list[WindowInfo]:
+    """Decide which single window is the active one, preferring what the window manager says.
+
+    The flags cannot settle it. AT-SPI reports `active` per *application*, so on an ordinary
+    desktop three windows claimed it at once. A window manager can settle it -- on X11
+    `_NET_ACTIVE_WINDOW` names one window, by pid and title -- and where that answer exists it wins
+    over the flags.
+
+    The hint is a hint: absent on Wayland, absent without the binding, and wrong if an application
+    renamed its window between the two reads. It never invents a mark, and when it matches nothing
+    the flags decide exactly as before.
+    """
+    matched = _by_hint(entries, hint) if hint is not None else None
+    if matched is None:
+        return sole_active(entries)
+    return [entry.model_copy(update={"active": entry.id == matched.id}) for entry in entries]
+
+
+def _by_hint(entries: Sequence[WindowInfo], hint: ActiveWindow) -> WindowInfo | None:
+    """The one window this hint names, or nothing -- never a first match."""
+    candidates = [entry for entry in entries if hint.pid is not None and entry.pid == hint.pid]
+    if len(candidates) == 1:
+        return candidates[0]
+    if not candidates:
+        return None
+    named = [entry for entry in candidates if entry.title == hint.title]
+    return named[0] if len(named) == 1 else None
+
+
 def sole_active(entries: Sequence[WindowInfo]) -> list[WindowInfo]:
     """Leave the active mark on at most one window.
 

{use_computer_cli-0.3.0 → use_computer_cli-0.3.1}/src/use_computer/skill/SKILL.md

@@ -2,7 +2,7 @@
 name: use-computer
 description: Read and act on a GUI — the accessibility tree of what is on screen (roles, names, clickable boxes), then click, focus, toggle, expand, select, set a value, type, press keys, drag, scroll, screenshot. Locally or over VNC. Ask the tree first and use ui-locator's pixel coordinates only when the tree cannot see the element. Bring a window forward before aiming at it, and confirm what happened by re-reading, not by trusting the line.
 x-skill-id: use-computer
-x-skill-version: "5"
+x-skill-version: "6"
 ---
 
 # use-computer
@@ -136,6 +136,9 @@ id      app              role    title                  pid     box
 0/34/0  Codex            window  ChatGPT                144775  0,0 1920x1038     *
 ```
 
+`*` marks the window that is actually in front — the window manager's answer where there is one,
+not a flag the toolkit sets per application. At most one window ever carries it.
+
 Use the `title` as `--window` for everything that follows, and **`app` to tell windows apart** — a
 title alone will not tell you which one is Telegram. The `*` marks the one `--window focused`
 resolves to.
@@ -450,10 +453,11 @@ of an element action is also the cheapest way to check a selector is unambiguous
   screenshots and coordinates. Otherwise the message names exactly what to install: an extra on
   Windows and macOS, and on Linux the distro packages plus a `--system-site-packages` virtualenv,
   because the extra does not help there.
-- **`AmbiguousWindowError` on `focused`** — several windows claim to be active, which on Linux
-  means the platform reports it per application and cannot say which is on top. Read `windows` and
-  pass `--window ID`. When it is ambiguous, `windows` shows **no** `*` at all rather than a
-  guess — an empty column is the answer, not a missing one.
+- **`AmbiguousWindowError` on `focused`** — nothing could say which window is on top. Where a
+  window manager can be asked it settles this, so seeing it means it could not be (Wayland, no
+  session, a window renamed between two reads). Read `windows` and pass `--window ID`. When it is
+  ambiguous, `windows` shows **no** `*` at all rather than a guess — an empty column is the
+  answer, not a missing one.
 - **`BackendNotAvailableError`** — the extra is not installed. The message names it.
 - **Local backend not enabled** — the `local` backend controls the user's own machine and needs
   an explicit opt-in. Tell the user to set `allow-local = true` in the profile; do not work

{use_computer_cli-0.3.0 → use_computer_cli-0.3.1}/src/use_computer/tree.py

@@ -183,6 +183,20 @@ class WindowsResult(BaseModel):
     windows: tuple[WindowInfo, ...] = ()
 
 
+class ActiveWindow(BaseModel):
+    """What a window manager says is in front: a hint, never a decision.
+
+    AT-SPI cannot answer this -- it reports `active` per application, so several windows claim it
+    at once. A window manager can: on X11 `_NET_ACTIVE_WINDOW` names exactly one. Matching the hint
+    to a window is policy and lives in `selectors.py`, so the three platforms cannot drift on it.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    pid: int | None = None
+    title: str | None = None
+
+
 class TreeScope(BaseModel):
     """What to snapshot. The focused window by default, never the whole desktop."""
 

{use_computer_cli-0.3.0 → use_computer_cli-0.3.1}/tests/fake_provider.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 
 from use_computer.errors import PermissionDeniedError, UITreeUnavailableError
-from use_computer.tree import Box, TreeScope, UINode, WindowInfo
+from use_computer.tree import ActiveWindow, Box, TreeScope, UINode, WindowInfo
 
 
 def node(
@@ -100,6 +100,8 @@ class FakeProvider:
     window_list: tuple[WindowInfo, ...] | None = None
     #: Whether this platform has a native raise. AT-SPI does not; Windows and macOS do.
     native_raise: bool = False
+    #: What a window manager would say is in front, when the test is about that.
+    hint: ActiveWindow | None = None
     activated: list[str] = field(default_factory=list)
 
     def windows(self) -> list[WindowInfo]:
@@ -131,6 +133,9 @@ class FakeProvider:
         self.calls.append((node_id, action, value))
         return action not in self.refuse
 
+    def active_window(self) -> ActiveWindow | None:
+        return self.hint
+
     def activate(self, window_id: str) -> bool:
         self.activated.append(window_id)
         return self.native_raise

{use_computer_cli-0.3.0 → use_computer_cli-0.3.1}/tests/test_cli.py

@@ -592,3 +592,18 @@ def test_a_single_screenshot_keeps_its_whole_path(
     result = invoke(runner, "screenshot")
     assert strip_ansi(result.stdout).split("\n")[0].startswith("/")
     assert "screenshots in " not in strip_ansi(result.stdout)
+
+
+def test_the_skill_command_answers_in_text(runner: CliRunner) -> None:
+    # The command an agent runs to find out whether its own instructions are current, and the last
+    # one still replying with a JSON object after the contract was inverted.
+    result = invoke(runner, "skill", "status")
+    assert result.exit_code == EXIT_OK
+    assert not result.stdout.lstrip().startswith("{")
+    assert result.stdout.split()[0] == "status"
+
+
+def test_the_skill_command_still_has_a_json_form(runner: CliRunner) -> None:
+    result = invoke(runner, "skill", "status", "--format", "json")
+    assert result.exit_code == EXIT_OK
+    assert json.loads(result.stdout)["action"] == "status"

{use_computer_cli-0.3.0 → use_computer_cli-0.3.1}/tests/test_skill.py

@@ -111,19 +111,19 @@ def test_the_scope_flag_accepts_every_documented_value() -> None:
     assert {scope.value for scope in Scope} == {"user", "project", "agents", "claude"}
 
 
-def test_the_cli_reports_json(project: Path) -> None:
+def test_the_cli_reports_what_it_did(project: Path) -> None:
     runner = CliRunner()
     result = runner.invoke(app, ["skill", "install"], catch_exceptions=False)
     assert result.exit_code == EXIT_OK
-    payload = json.loads(result.stdout)
-    assert payload["status"] == "up-to-date"
-    assert payload["scope"] == "project"
+    assert result.stdout.split()[:3] == ["install", "project", "up-to-date"]
 
     again = runner.invoke(app, ["skill", "install"], catch_exceptions=False)
     assert again.exit_code == EXIT_FAILURE
 
-    status_result = runner.invoke(app, ["skill", "status"], catch_exceptions=False)
+    status_result = runner.invoke(
+        app, ["skill", "status", "--format", "json"], catch_exceptions=False
+    )
     assert json.loads(status_result.stdout)["installed"] is True
 
     removed = runner.invoke(app, ["skill", "remove"], catch_exceptions=False)
-    assert json.loads(removed.stdout)["status"] == "missing"
+    assert removed.stdout.split()[:3] == ["remove", "project", "missing"]

use_computer_cli-0.3.1/tests/test_which_window.py

@@ -0,0 +1,113 @@
+"""Which window is the active one, and what happens when the platform cannot say.
+
+Measured on a real desktop: three windows carried the mark at once, because AT-SPI reports
+`active` per *application*. Neither that flag, nor `focused`, nor looking for a focused
+descendant identified the window actually on top.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from tests.fake_provider import window
+from use_computer.errors import AmbiguousWindowError, UITreeUnavailableError
+from use_computer.render import windows_for_a_reader
+from use_computer.selectors import active_window, mark_active, sole_active
+from use_computer.tree import ActiveWindow
+
+
+def test_one_claim_is_left_alone() -> None:
+    marked = sole_active([window("0/1", "A", active=True), window("0/2", "B")])
+    assert [entry.active for entry in marked] == [True, False]
+
+
+def test_several_claims_leave_no_mark_at_all() -> None:
+    # Saying nothing is worth more than a mark that is wrong two times in three, and this column
+    # is the first thing an agent is told to read.
+    marked = sole_active(
+        [
+            window("0/19", "", active=True),
+            window("0/34", "ChatGPT", active=True),
+            window("0/37", "Drawing", active=True),
+        ]
+    )
+    assert [entry.active for entry in marked] == [False, False, False]
+
+
+def test_the_column_then_shows_no_star() -> None:
+    text = windows_for_a_reader(
+        sole_active([window("0/1", "A", active=True), window("0/2", "B", active=True)])
+    )
+    assert "*" not in text.replace("active", "")
+
+
+def test_focused_refuses_rather_than_taking_the_first() -> None:
+    # Picking the first match is how an agent reads, clicks and verifies inside the wrong
+    # application, consistently and with no sign anything went wrong.
+    with pytest.raises(AmbiguousWindowError) as excinfo:
+        active_window([window("0/34", "ChatGPT", active=True), window("0/37", "Draw", active=True)])
+    assert {entry.id for entry in excinfo.value.candidates} == {"0/34", "0/37"}
+    assert "--window" in str(excinfo.value)
+
+
+def test_no_claim_at_all_says_how_to_name_one() -> None:
+    with pytest.raises(UITreeUnavailableError) as excinfo:
+        active_window([window("0/1", "A"), window("0/2", "B")])
+    assert "--window" in str(excinfo.value)
+
+
+def test_one_claim_resolves() -> None:
+    assert active_window([window("0/1", "A"), window("0/2", "B", active=True)]).id == "0/2"
+
+
+# --- what the window manager says --------------------------------------------------------------
+
+
+def test_the_window_manager_settles_what_the_flags_could_not() -> None:
+    # Three windows claimed `active`; `_NET_ACTIVE_WINDOW` names one, by pid and title.
+    entries = [
+        window("0/19", "", active=True),
+        window("0/29", "a terminal", active=True),
+        window("0/37", "Drawing", active=True),
+    ]
+    entries[1] = entries[1].model_copy(update={"pid": 2379})
+    marked = mark_active(entries, ActiveWindow(pid=2379, title="a terminal"))
+    assert [entry.active for entry in marked] == [False, True, False]
+
+
+def test_the_hint_wins_over_a_flag_that_disagrees() -> None:
+    entries = [
+        window("0/29", "a terminal", active=True).model_copy(update={"pid": 1}),
+        window("0/37", "Drawing").model_copy(update={"pid": 2}),
+    ]
+    marked = mark_active(entries, ActiveWindow(pid=2, title="Drawing"))
+    assert [entry.active for entry in marked] == [False, True]
+
+
+def test_one_pid_with_several_windows_is_settled_by_the_title() -> None:
+    entries = [
+        window("0/34/0", "ChatGPT").model_copy(update={"pid": 9}),
+        window("0/34/1", "Notes").model_copy(update={"pid": 9}),
+    ]
+    marked = mark_active(entries, ActiveWindow(pid=9, title="Notes"))
+    assert [entry.active for entry in marked] == [False, True]
+
+
+def test_a_hint_that_matches_nothing_leaves_the_flags_alone() -> None:
+    # Wayland, a renamed window, a pid the tree does not know: never invent a mark.
+    entries = [window("0/1", "A", active=True), window("0/2", "B")]
+    assert [e.active for e in mark_active(entries, ActiveWindow(pid=999))] == [True, False]
+
+
+def test_no_hint_at_all_behaves_exactly_as_before() -> None:
+    entries = [window("0/1", "A", active=True), window("0/2", "B", active=True)]
+    assert [entry.active for entry in mark_active(entries, None)] == [False, False]
+
+
+def test_an_ambiguous_hint_does_not_guess() -> None:
+    entries = [
+        window("0/34/0", "ChatGPT").model_copy(update={"pid": 9}),
+        window("0/34/1", "ChatGPT").model_copy(update={"pid": 9}),
+    ]
+    marked = mark_active(entries, ActiveWindow(pid=9, title="ChatGPT"))
+    assert [entry.active for entry in marked] == [False, False]

use_computer_cli-0.3.0/tests/test_which_window.py

@@ -1,59 +0,0 @@
-"""Which window is the active one, and what happens when the platform cannot say.
-
-Measured on a real desktop: three windows carried the mark at once, because AT-SPI reports
-`active` per *application*. Neither that flag, nor `focused`, nor looking for a focused
-descendant identified the window actually on top.
-"""
-
-from __future__ import annotations
-
-import pytest
-
-from tests.fake_provider import window
-from use_computer.errors import AmbiguousWindowError, UITreeUnavailableError
-from use_computer.render import windows_for_a_reader
-from use_computer.selectors import active_window, sole_active
-
-
-def test_one_claim_is_left_alone() -> None:
-    marked = sole_active([window("0/1", "A", active=True), window("0/2", "B")])
-    assert [entry.active for entry in marked] == [True, False]
-
-
-def test_several_claims_leave_no_mark_at_all() -> None:
-    # Saying nothing is worth more than a mark that is wrong two times in three, and this column
-    # is the first thing an agent is told to read.
-    marked = sole_active(
-        [
-            window("0/19", "", active=True),
-            window("0/34", "ChatGPT", active=True),
-            window("0/37", "Drawing", active=True),
-        ]
-    )
-    assert [entry.active for entry in marked] == [False, False, False]
-
-
-def test_the_column_then_shows_no_star() -> None:
-    text = windows_for_a_reader(
-        sole_active([window("0/1", "A", active=True), window("0/2", "B", active=True)])
-    )
-    assert "*" not in text.replace("active", "")
-
-
-def test_focused_refuses_rather_than_taking_the_first() -> None:
-    # Picking the first match is how an agent reads, clicks and verifies inside the wrong
-    # application, consistently and with no sign anything went wrong.
-    with pytest.raises(AmbiguousWindowError) as excinfo:
-        active_window([window("0/34", "ChatGPT", active=True), window("0/37", "Draw", active=True)])
-    assert {entry.id for entry in excinfo.value.candidates} == {"0/34", "0/37"}
-    assert "--window" in str(excinfo.value)
-
-
-def test_no_claim_at_all_says_how_to_name_one() -> None:
-    with pytest.raises(UITreeUnavailableError) as excinfo:
-        active_window([window("0/1", "A"), window("0/2", "B")])
-    assert "--window" in str(excinfo.value)
-
-
-def test_one_claim_resolves() -> None:
-    assert active_window([window("0/1", "A"), window("0/2", "B", active=True)]).id == "0/2"