agentremote-cli 1.0.0__py3-none-any.whl

remotecli/agent_window.py

@@ -0,0 +1,249 @@
+"""Window lookup and foreground helpers for agent commands."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Callable, Dict, Iterable
+
+from .agent_cache import WindowCache, WindowRef
+from .agent_result import _error
+from .agent_utils import _extract_int, _first_present, _first_text, _truthy
+
+
+WaitAndUnpack = Callable[[Dict[str, Any], str, float, float], Dict[str, Any]]
+
+
+class WindowResolver:
+    """Resolve app queries into concrete pid/window_id pairs."""
+
+    def __init__(
+        self,
+        client: Any,
+        cua: Any,
+        window_cache: WindowCache,
+        wait_and_unpack: WaitAndUnpack,
+        default_session_id: str = "",
+    ) -> None:
+        self._client = client
+        self._cua = cua
+        self._window_cache = window_cache
+        self._wait_and_unpack = wait_and_unpack
+        self._default_session_id = default_session_id
+
+    def resolve_window(
+        self,
+        app_query: str,
+        wait_timeout: float,
+        poll_interval: float,
+        session_id: str = "",
+        use_window_cache: bool = True,
+        refresh_window: bool = False,
+    ) -> tuple[WindowRef | None, Dict[str, Any] | None]:
+        session = self.resolve_session_id(session_id)
+        if use_window_cache and session and not refresh_window:
+            cached_ref = self._window_cache.get(self._client, session, app_query)
+            if cached_ref:
+                return cached_ref, None
+
+        apps_result = self._wait_and_unpack(
+            self._cua.list_apps(app_query, max_results=5),
+            "list_apps",
+            wait_timeout,
+            poll_interval,
+        )
+        if not apps_result.get("ok"):
+            apps_result["action"] = "resolve_window"
+            return None, apps_result
+
+        apps = list(_extract_apps(apps_result.get("json")))
+        if not apps:
+            return None, _error("resolve_window", f"no app matched: {app_query}", app=app_query)
+
+        last_error: Dict[str, Any] | None = None
+        for app in _ranked_apps(apps, app_query):
+            pid = _extract_int(app, "pid", "process_id", "processId", "id")
+            if not pid:
+                last_error = _error("resolve_window", f"matched app has no pid: {app_query}", app=app)
+                continue
+
+            windows_result = self._wait_and_unpack(
+                self._cua.list_windows(pid),
+                "list_windows",
+                wait_timeout,
+                poll_interval,
+            )
+            if not windows_result.get("ok"):
+                windows_result["action"] = "resolve_window"
+                last_error = windows_result
+                continue
+
+            windows = list(_extract_windows(windows_result.get("json")))
+            if not windows:
+                last_error = _error("resolve_window", f"no windows for pid: {pid}", pid=pid, app=app)
+                continue
+
+            window = _select_window(windows)
+            window_id = _extract_int(window, "window_id", "windowId", "id", "hwnd", "handle")
+            if not window_id:
+                last_error = _error("resolve_window", f"matched window has no window_id: {pid}", window=window)
+                continue
+
+            ref = WindowRef(
+                pid=pid,
+                window_id=window_id,
+                title=str(window.get("title") or window.get("name") or ""),
+                app=app,
+                window=window,
+            )
+            if use_window_cache and session:
+                self._window_cache.put(self._client, session, app_query, ref)
+            return ref, None
+
+        return None, last_error or _error(
+            "resolve_window",
+            f"no usable app window matched: {app_query}",
+            app=app_query,
+        )
+
+    def foreground_window(
+        self,
+        ref: WindowRef,
+        wait_timeout: float,
+        poll_interval: float,
+    ) -> None:
+        self._wait_and_unpack(
+            self._cua.bring_to_front(ref.pid, ref.window_id),
+            "bring_to_front",
+            wait_timeout,
+            poll_interval,
+        )
+
+    def refresh_window(
+        self,
+        app_query: str,
+        wait_timeout: float,
+        poll_interval: float,
+        session_id: str,
+    ) -> tuple[WindowRef | None, Dict[str, Any] | None]:
+        session = self.resolve_session_id(session_id)
+        if session:
+            self._window_cache.remove_app(self._client, session, app_query)
+        return self.resolve_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id=session,
+            use_window_cache=True,
+            refresh_window=True,
+        )
+
+    def should_refresh_cached_window(
+        self,
+        ref: WindowRef,
+        result: Dict[str, Any],
+        session_id: str,
+        use_window_cache: bool,
+    ) -> bool:
+        return bool(
+            ref.cached
+            and use_window_cache
+            and self.resolve_session_id(session_id)
+            and not result.get("ok")
+        )
+
+    def resolve_session_id(self, session_id: str = "") -> str:
+        return (
+            session_id
+            or self._default_session_id
+            or os.environ.get("REMOTECLI_SESSION", "")
+        ).strip()
+
+    def cache_context(self) -> Dict[str, Any]:
+        if not self._window_cache.last_error:
+            return {}
+        return {"window_cache_error": self._window_cache.last_error}
+
+
+def _extract_apps(payload: Any) -> Iterable[Dict[str, Any]]:
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    if not isinstance(payload, dict):
+        return []
+    for key in ("matches", "apps", "applications", "items", "processes"):
+        value = payload.get(key)
+        if isinstance(value, list):
+            return [item for item in value if isinstance(item, dict)]
+    return [payload] if _extract_int(payload, "pid", "process_id", "id") else []
+
+
+def _ranked_apps(apps: list[Dict[str, Any]], query: str) -> list[Dict[str, Any]]:
+    indexed = list(enumerate(apps))
+    ranked = sorted(
+        indexed,
+        key=lambda item: (_app_score(item[1], query), -item[0]),
+        reverse=True,
+    )
+    return [app for _index, app in ranked]
+
+
+def _app_score(app: Dict[str, Any], query: str) -> int:
+    score = 0
+    pid = _extract_int(app, "pid", "process_id", "processId", "id")
+    if pid:
+        score += 1000
+    else:
+        score -= 500
+
+    if _truthy(_first_present(app, "running", "is_running", "isRunning")):
+        score += 300
+    if _truthy(_first_present(app, "active", "is_active", "foreground", "is_foreground")):
+        score += 120
+
+    windows = app.get("windows")
+    if isinstance(windows, list) and windows:
+        score += 80
+
+    kind = _first_text(app, "kind", "type", "app_type", "appType", "source") or ""
+    kind_text = kind.lower()
+    if any(term in kind_text for term in ("desktop", "win32", "process")):
+        score += 80
+    if any(term in kind_text for term in ("uwp", "share", "appx")):
+        score -= 80
+
+    query_text = " ".join(str(query or "").lower().split())
+    identity = " ".join(
+        str(_first_present(app, key) or "")
+        for key in (
+            "name",
+            "title",
+            "display_name",
+            "process_name",
+            "app_id",
+            "appId",
+            "path",
+        )
+    ).lower()
+    if query_text and query_text in " ".join(identity.split()):
+        score += 50
+    if query_text and query_text == " ".join(identity.split()):
+        score += 50
+    return score
+
+
+def _extract_windows(payload: Any) -> Iterable[Dict[str, Any]]:
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    if not isinstance(payload, dict):
+        return []
+    for key in ("windows", "items"):
+        value = payload.get(key)
+        if isinstance(value, list):
+            return [item for item in value if isinstance(item, dict)]
+    return [payload] if _extract_int(payload, "window_id", "id", "hwnd", "handle") else []
+
+
+def _select_window(windows: list[Dict[str, Any]]) -> Dict[str, Any]:
+    for window in windows:
+        if str(window.get("title") or window.get("name") or "").strip():
+            return window
+    return windows[0]