agentremote-cli 1.0.0__py3-none-any.whl

remotecli/agent.py

@@ -0,0 +1,673 @@
+"""
+Agent-friendly remotecli wrappers.
+
+These commands hide mechanical details that models frequently get wrong:
+waiting, result.output decoding, and pid/window_id discovery.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Iterable
+
+from .agent_cache import WindowCache, WindowRef
+from .agent_modes import _LOCATE_MODES, _OBSERVE_MODES, _PROBE_MODES
+from .agent_open import open_app_window
+from .agent_projection import _compact_window_state
+from .agent_result import _error, _normalize_task_result
+from .agent_utils import (
+    _normalize_mode,
+    _normalize_scroll_amount,
+    _normalize_scroll_by,
+    _normalize_scroll_direction,
+    _target_texts,
+)
+from .agent_window import WindowResolver
+from .client import RemoteCliClient
+from .cua import CuaCommands
+from .shell import ShellCommands
+
+__all__ = ["AgentCommands", "WindowCache", "WindowRef"]
+
+
+class AgentCommands:
+    """High-level commands intended for AI agents."""
+
+    def __init__(
+        self,
+        client: RemoteCliClient,
+        window_cache_path: str | Path | None = None,
+        default_session_id: str = "",
+    ) -> None:
+        self._client = client
+        self._shell = ShellCommands(client)
+        self._cua = CuaCommands(client)
+        self._window_cache = WindowCache(window_cache_path)
+        self._window_resolver = WindowResolver(
+            client,
+            self._cua,
+            self._window_cache,
+            self._wait_and_unpack,
+            default_session_id=default_session_id,
+        )
+
+    def ps(
+        self,
+        script: str,
+        cwd: str = "",
+        timeout_sec: int = 60,
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+    ) -> Dict[str, Any]:
+        submitted = self._shell.exec_script(
+            script,
+            shell="powershell",
+            cwd=cwd,
+            timeout_sec=timeout_sec,
+        )
+        return self._wait_and_unpack(submitted, "ps", wait_timeout, poll_interval)
+
+    def cmd(
+        self,
+        command: str,
+        cwd: str = "",
+        timeout_sec: int = 60,
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+    ) -> Dict[str, Any]:
+        submitted = self._shell.exec(command, cwd=cwd, timeout_sec=timeout_sec)
+        return self._wait_and_unpack(submitted, "cmd", wait_timeout, poll_interval)
+
+    def open(
+        self,
+        app_query: str,
+        launch_path: str = "",
+        app_args: str = "",
+        start_if_missing: bool = True,
+        foreground: bool = True,
+        launch_timeout: int = 15,
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+        session_id: str = "",
+        use_window_cache: bool = True,
+    ) -> Dict[str, Any]:
+        return open_app_window(
+            self._client,
+            self._shell,
+            self._window_cache,
+            self._wait_and_unpack,
+            app_query,
+            session_id=self._resolve_session_id(session_id),
+            use_window_cache=use_window_cache,
+            launch_path=launch_path,
+            app_args=app_args,
+            start_if_missing=start_if_missing,
+            foreground=foreground,
+            launch_timeout=launch_timeout,
+            wait_timeout=wait_timeout,
+            poll_interval=poll_interval,
+        )
+
+    def observe(
+        self,
+        app_query: str,
+        mode: str = "uia",
+        output_format: str = "compact",
+        element_limit: int = 20,
+        targets: Iterable[str] | str | None = None,
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+        session_id: str = "",
+        use_window_cache: bool = True,
+        refresh_window: bool = False,
+    ) -> Dict[str, Any]:
+        output_format = output_format.strip().lower()
+        if output_format not in {"compact", "full"}:
+            return _error(
+                "observe",
+                f"unsupported observe format: {output_format}",
+                supported_formats=["compact", "full"],
+            )
+
+        mode = _normalize_mode(mode, default="uia")
+        if mode not in _OBSERVE_MODES:
+            return _error(
+                "observe",
+                f"unsupported observe mode: {mode}",
+                supported_modes=sorted(_OBSERVE_MODES),
+            )
+
+        ref, error = self._resolve_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id=session_id,
+            use_window_cache=use_window_cache,
+            refresh_window=refresh_window,
+        )
+        if error:
+            return error
+
+        assert ref is not None
+        self._foreground_window(ref, wait_timeout, poll_interval)
+        state = self._wait_and_unpack(
+            self._cua.get_window_state(ref.pid, ref.window_id, mode),
+            "observe",
+            wait_timeout,
+            poll_interval,
+        )
+        if self._should_refresh_cached_window(ref, state, session_id, use_window_cache):
+            ref, error = self._refresh_window(app_query, wait_timeout, poll_interval, session_id)
+            if error:
+                return error
+            assert ref is not None
+            self._foreground_window(ref, wait_timeout, poll_interval)
+            state = self._wait_and_unpack(
+                self._cua.get_window_state(ref.pid, ref.window_id, mode),
+                "observe",
+                wait_timeout,
+                poll_interval,
+            )
+        payload = state.get("json")
+        title = self._state_title(payload) or ref.title
+        if output_format == "full":
+            return {
+                "ok": bool(state.get("ok")),
+                "action": "observe",
+                "format": "full",
+                "mode": mode,
+                "app": app_query,
+                "pid": ref.pid,
+                "window_id": ref.window_id,
+                "title": title,
+                "window_cached": ref.cached,
+                "state": payload,
+                "result": state,
+                **self._window_cache_context(),
+            }
+
+        compact_state = _compact_window_state(
+            payload,
+            title=title,
+            trace_id=state.get("trace_id"),
+            targets=targets,
+            element_limit=element_limit,
+        )
+        return {
+            "ok": bool(state.get("ok")),
+            "action": "observe",
+            "format": "compact",
+            "mode": mode,
+            "app": app_query,
+            "pid": ref.pid,
+            "window_id": ref.window_id,
+            "title": title,
+            "window": {
+                "pid": ref.pid,
+                "window_id": ref.window_id,
+                "title": title,
+            },
+            "window_cached": ref.cached,
+            "state": compact_state,
+            "trace_id": state.get("trace_id"),
+            "status": state.get("status"),
+            "result_status": state.get("result_status"),
+            "error": state.get("error") or "",
+            **self._window_cache_context(),
+        }
+
+    def click(
+        self,
+        app_query: str,
+        target: str,
+        locate_mode: str = "smart",
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+        session_id: str = "",
+        use_window_cache: bool = True,
+        refresh_window: bool = False,
+    ) -> Dict[str, Any]:
+        locate_mode = _normalize_mode(locate_mode, default="smart")
+        if locate_mode not in _LOCATE_MODES:
+            return _error(
+                "click",
+                f"unsupported locate mode: {locate_mode}",
+                supported_modes=sorted(_LOCATE_MODES),
+            )
+        ref, error = self._resolve_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id=session_id,
+            use_window_cache=use_window_cache,
+            refresh_window=refresh_window,
+        )
+        if error:
+            return error
+
+        assert ref is not None
+        result = self._wait_and_unpack(
+            self._cua.click(ref.pid, ref.window_id, target=target, locate_mode=locate_mode),
+            "click",
+            wait_timeout,
+            poll_interval,
+        )
+        if self._should_refresh_cached_window(ref, result, session_id, use_window_cache):
+            ref, error = self._refresh_window(app_query, wait_timeout, poll_interval, session_id)
+            if error:
+                return error
+            assert ref is not None
+            result = self._wait_and_unpack(
+                self._cua.click(ref.pid, ref.window_id, target=target, locate_mode=locate_mode),
+                "click",
+                wait_timeout,
+                poll_interval,
+            )
+        extra = {"locate_mode": locate_mode} if locate_mode else {}
+        return self._with_window_context(result, "click", ref, target=target, **extra)
+
+    def probe(
+        self,
+        app_query: str,
+        targets: Iterable[str] | str,
+        mode: str = "smart",
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+        session_id: str = "",
+        use_window_cache: bool = True,
+        refresh_window: bool = False,
+    ) -> Dict[str, Any]:
+        mode = _normalize_mode(mode, default="smart")
+        if mode not in _PROBE_MODES:
+            return _error(
+                "probe",
+                f"unsupported probe mode: {mode}",
+                supported_modes=sorted(_PROBE_MODES),
+            )
+        target_list = _target_texts(targets)
+        if not target_list:
+            return _error("probe", "probe requires at least one target")
+
+        ref, error = self._resolve_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id=session_id,
+            use_window_cache=use_window_cache,
+            refresh_window=refresh_window,
+        )
+        if error:
+            return error
+
+        assert ref is not None
+        if mode != "uia":
+            self._foreground_window(ref, wait_timeout, poll_interval)
+        result = self._wait_and_unpack(
+            self._cua.probe_window(ref.pid, ref.window_id, target_list, mode=mode),
+            "probe",
+            wait_timeout,
+            poll_interval,
+        )
+        if self._should_refresh_cached_window(ref, result, session_id, use_window_cache):
+            ref, error = self._refresh_window(app_query, wait_timeout, poll_interval, session_id)
+            if error:
+                return error
+            assert ref is not None
+            if mode != "uia":
+                self._foreground_window(ref, wait_timeout, poll_interval)
+            result = self._wait_and_unpack(
+                self._cua.probe_window(ref.pid, ref.window_id, target_list, mode=mode),
+                "probe",
+                wait_timeout,
+                poll_interval,
+            )
+        payload = result.get("json")
+        if not isinstance(payload, dict):
+            payload = result.get("output") if isinstance(result.get("output"), dict) else {}
+        matches = payload.get("matches", []) if isinstance(payload.get("matches"), list) else []
+        missing = payload.get("missing", target_list) if isinstance(payload.get("missing"), list) else target_list
+        return {
+            "ok": bool(result.get("ok")),
+            "action": "probe",
+            "app": app_query,
+            "pid": ref.pid,
+            "window_id": ref.window_id,
+            "title": ref.title,
+            "window_cached": ref.cached,
+            "mode": payload.get("mode", mode),
+            "targets": payload.get("targets", target_list),
+            "matches": matches,
+            "missing": missing,
+            "any_found": bool(payload.get("any_found", bool(matches))),
+            "all_found": bool(payload.get("all_found", not missing)),
+            "probes": payload.get("probes", []),
+            "trace_id": result.get("trace_id"),
+            "status": result.get("status"),
+            "result_status": result.get("result_status"),
+            "error": result.get("error") or "",
+            **self._window_cache_context(),
+        }
+
+    def type_text(
+        self,
+        app_query: str,
+        target: str,
+        text: str,
+        locate_mode: str = "smart",
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+        session_id: str = "",
+        use_window_cache: bool = True,
+        refresh_window: bool = False,
+    ) -> Dict[str, Any]:
+        locate_mode = _normalize_mode(locate_mode, default="smart")
+        if locate_mode not in _LOCATE_MODES:
+            return _error(
+                "type",
+                f"unsupported locate mode: {locate_mode}",
+                supported_modes=sorted(_LOCATE_MODES),
+            )
+        ref, error = self._resolve_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id=session_id,
+            use_window_cache=use_window_cache,
+            refresh_window=refresh_window,
+        )
+        if error:
+            return error
+
+        assert ref is not None
+        result = self._wait_and_unpack(
+            self._cua.type_text(
+                ref.pid,
+                target,
+                text,
+                window_id=ref.window_id,
+                locate_mode=locate_mode,
+            ),
+            "type",
+            wait_timeout,
+            poll_interval,
+        )
+        if self._should_refresh_cached_window(ref, result, session_id, use_window_cache):
+            ref, error = self._refresh_window(app_query, wait_timeout, poll_interval, session_id)
+            if error:
+                return error
+            assert ref is not None
+            result = self._wait_and_unpack(
+                self._cua.type_text(
+                    ref.pid,
+                    target,
+                    text,
+                    window_id=ref.window_id,
+                    locate_mode=locate_mode,
+                ),
+                "type",
+                wait_timeout,
+                poll_interval,
+            )
+        extra = {"locate_mode": locate_mode} if locate_mode else {}
+        return self._with_window_context(result, "type", ref, target=target, **extra)
+
+    def key(
+        self,
+        app_query: str,
+        key: str,
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+        session_id: str = "",
+        use_window_cache: bool = True,
+        refresh_window: bool = False,
+    ) -> Dict[str, Any]:
+        ref, error = self._resolve_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id=session_id,
+            use_window_cache=use_window_cache,
+            refresh_window=refresh_window,
+        )
+        if error:
+            return error
+
+        assert ref is not None
+        result = self._wait_and_unpack(
+            self._cua.press_key(ref.pid, key, window_id=ref.window_id),
+            "key",
+            wait_timeout,
+            poll_interval,
+        )
+        if self._should_refresh_cached_window(ref, result, session_id, use_window_cache):
+            ref, error = self._refresh_window(app_query, wait_timeout, poll_interval, session_id)
+            if error:
+                return error
+            assert ref is not None
+            result = self._wait_and_unpack(
+                self._cua.press_key(ref.pid, key, window_id=ref.window_id),
+                "key",
+                wait_timeout,
+                poll_interval,
+            )
+        return self._with_window_context(result, "key", ref, key=key)
+
+    def hotkey(
+        self,
+        app_query: str,
+        keys: str,
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+        session_id: str = "",
+        use_window_cache: bool = True,
+        refresh_window: bool = False,
+    ) -> Dict[str, Any]:
+        ref, error = self._resolve_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id=session_id,
+            use_window_cache=use_window_cache,
+            refresh_window=refresh_window,
+        )
+        if error:
+            return error
+
+        assert ref is not None
+        result = self._wait_and_unpack(
+            self._cua.hotkey(ref.pid, keys, window_id=ref.window_id),
+            "hotkey",
+            wait_timeout,
+            poll_interval,
+        )
+        if self._should_refresh_cached_window(ref, result, session_id, use_window_cache):
+            ref, error = self._refresh_window(app_query, wait_timeout, poll_interval, session_id)
+            if error:
+                return error
+            assert ref is not None
+            result = self._wait_and_unpack(
+                self._cua.hotkey(ref.pid, keys, window_id=ref.window_id),
+                "hotkey",
+                wait_timeout,
+                poll_interval,
+            )
+        return self._with_window_context(result, "hotkey", ref, keys=keys)
+
+    def scroll(
+        self,
+        app_query: str,
+        direction: str = "down",
+        amount: int = 3,
+        by: str = "line",
+        dispatch: str = "",
+        wait_timeout: float = 30.0,
+        poll_interval: float = 0.1,
+        session_id: str = "",
+        use_window_cache: bool = True,
+        refresh_window: bool = False,
+    ) -> Dict[str, Any]:
+        ref, error = self._resolve_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id=session_id,
+            use_window_cache=use_window_cache,
+            refresh_window=refresh_window,
+        )
+        if error:
+            return error
+
+        assert ref is not None
+        direction = _normalize_scroll_direction(direction)
+        amount = _normalize_scroll_amount(amount)
+        by = _normalize_scroll_by(by)
+        result = self._wait_and_unpack(
+            self._cua.scroll(
+                ref.pid,
+                ref.window_id,
+                direction=direction,
+                amount=amount,
+                by=by,
+                dispatch=dispatch,
+            ),
+            "scroll",
+            wait_timeout,
+            poll_interval,
+        )
+        if self._should_refresh_cached_window(ref, result, session_id, use_window_cache):
+            ref, error = self._refresh_window(app_query, wait_timeout, poll_interval, session_id)
+            if error:
+                return error
+            assert ref is not None
+            result = self._wait_and_unpack(
+                self._cua.scroll(
+                    ref.pid,
+                    ref.window_id,
+                    direction=direction,
+                    amount=amount,
+                    by=by,
+                    dispatch=dispatch,
+                ),
+                "scroll",
+                wait_timeout,
+                poll_interval,
+            )
+        return self._with_window_context(
+            result,
+            "scroll",
+            ref,
+            direction=direction,
+            amount=amount,
+            by=by,
+            **({"dispatch": dispatch} if dispatch else {}),
+        )
+
+    def clear_session(self, session_id: str = "") -> Dict[str, Any]:
+        session = self._resolve_session_id(session_id)
+        if not session:
+            return _error("session-clear", "session is required")
+        self._window_cache.clear_session(self._client, session)
+        return {
+            "ok": True,
+            "action": "session-clear",
+            "session": session,
+            **self._window_cache_context(),
+        }
+
+    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]:
+        return self._window_resolver.resolve_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id=session_id,
+            use_window_cache=use_window_cache,
+            refresh_window=refresh_window,
+        )
+
+    def _foreground_window(
+        self,
+        ref: WindowRef,
+        wait_timeout: float,
+        poll_interval: float,
+    ) -> None:
+        self._window_resolver.foreground_window(ref, 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]:
+        return self._window_resolver.refresh_window(
+            app_query,
+            wait_timeout,
+            poll_interval,
+            session_id,
+        )
+
+    def _should_refresh_cached_window(
+        self,
+        ref: WindowRef,
+        result: Dict[str, Any],
+        session_id: str,
+        use_window_cache: bool,
+    ) -> bool:
+        return self._window_resolver.should_refresh_cached_window(
+            ref,
+            result,
+            session_id,
+            use_window_cache,
+        )
+
+    def _resolve_session_id(self, session_id: str = "") -> str:
+        return self._window_resolver.resolve_session_id(session_id)
+
+    def _window_cache_context(self) -> Dict[str, Any]:
+        return self._window_resolver.cache_context()
+
+    def _wait_and_unpack(
+        self,
+        submitted: Dict[str, Any],
+        action: str,
+        wait_timeout: float,
+        poll_interval: float,
+    ) -> Dict[str, Any]:
+        trace_id = submitted.get("trace_id")
+        if not trace_id:
+            return _normalize_task_result(submitted, action)
+        data = self._client.poll_result(trace_id, timeout_sec=wait_timeout, interval=poll_interval)
+        return _normalize_task_result(data, action)
+
+    @staticmethod
+    def _state_title(payload: Any) -> str:
+        if isinstance(payload, dict):
+            return str(payload.get("title") or payload.get("window_title") or "")
+        return ""
+
+    def _with_window_context(
+        self,
+        result: Dict[str, Any],
+        action: str,
+        ref: WindowRef,
+        **extra: Any,
+    ) -> Dict[str, Any]:
+        return {
+            "ok": bool(result.get("ok")),
+            "action": action,
+            "pid": ref.pid,
+            "window_id": ref.window_id,
+            "title": ref.title,
+            "window_cached": ref.cached,
+            **extra,
+            "result": result,
+            **self._window_cache_context(),
+        }