agentremote-cli 1.0.0__py3-none-any.whl

remotecli/agent_cache.py

@@ -0,0 +1,274 @@
+"""Persistent window cache for agent-friendly GUI commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import tempfile
+import time
+from typing import Any, Dict, Iterable
+
+from .agent_utils import _coerce_float, _coerce_int
+from .client import RemoteCliClient
+
+
+_WINDOW_CACHE_FILENAME = "remotecli_window_cache.json"
+
+
+@dataclass(frozen=True)
+class WindowRef:
+    pid: int
+    window_id: int
+    title: str
+    app: Dict[str, Any]
+    window: Dict[str, Any]
+    cached: bool = False
+
+
+def _default_window_cache_path() -> Path:
+    return _default_window_cache_paths()[0]
+
+
+def _default_window_cache_paths() -> list[Path]:
+    explicit_path = os.environ.get("REMOTECLI_WINDOW_CACHE", "").strip()
+    if explicit_path:
+        return [Path(explicit_path)]
+
+    candidates: list[Path] = []
+    base_dir = os.environ.get("LOCALAPPDATA", "").strip()
+    if base_dir:
+        candidates.append(Path(base_dir) / "AgentRemote" / _WINDOW_CACHE_FILENAME)
+
+    state_dir = os.environ.get("AGENTREMOTE_STATE_DIR", "").strip()
+    if state_dir:
+        candidates.append(Path(state_dir) / _WINDOW_CACHE_FILENAME)
+
+    runtime_state_dir = Path(__file__).resolve().parents[1] / "client" / "runtime_state"
+    candidates.append(runtime_state_dir / _WINDOW_CACHE_FILENAME)
+    candidates.append(Path.home() / ".agentremote" / _WINDOW_CACHE_FILENAME)
+    candidates.append(Path(tempfile.gettempdir()) / "AgentRemote" / _WINDOW_CACHE_FILENAME)
+    return _dedupe_paths(candidates)
+
+
+def _dedupe_paths(paths: Iterable[Path]) -> list[Path]:
+    result: list[Path] = []
+    seen: set[str] = set()
+    for path in paths:
+        key = os.path.normcase(str(path.expanduser()))
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(path)
+    return result
+
+
+def _session_cache_key(client: RemoteCliClient, session: str) -> str:
+    return "|".join(
+        [
+            str(getattr(client, "middleware_url", "")),
+            str(getattr(client, "tenant_id", "")),
+            str(getattr(client, "node_id", "")),
+            session.strip(),
+        ]
+    )
+
+
+def _normalize_cache_key(value: str) -> str:
+    return " ".join(value.strip().lower().split())
+
+
+class WindowCache:
+    """Persistent session-scoped cache for app pid/window_id lookups."""
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        self._paths = [Path(path)] if path else _default_window_cache_paths()
+        self.path = self._paths[0]
+        self.last_error = ""
+
+    def get(self, client: RemoteCliClient, session: str, app_query: str) -> WindowRef | None:
+        session_data = self._session_data(client, session)
+        apps = session_data.get("apps") if isinstance(session_data, dict) else None
+        if not isinstance(apps, dict):
+            return None
+        value = apps.get(_normalize_cache_key(app_query))
+        if not isinstance(value, dict):
+            return None
+
+        pid = _coerce_int(value.get("pid"))
+        window_id = _coerce_int(value.get("window_id"))
+        if not pid or not window_id:
+            return None
+
+        app = value.get("app") if isinstance(value.get("app"), dict) else {}
+        window = value.get("window") if isinstance(value.get("window"), dict) else {}
+        return WindowRef(
+            pid=pid,
+            window_id=window_id,
+            title=str(value.get("title") or window.get("title") or ""),
+            app=app,
+            window=window,
+            cached=True,
+        )
+
+    def put(
+        self,
+        client: RemoteCliClient,
+        session: str,
+        app_query: str,
+        ref: WindowRef,
+    ) -> None:
+        data = self._read()
+        sessions = data.setdefault("sessions", {})
+        if not isinstance(sessions, dict):
+            sessions = {}
+            data["sessions"] = sessions
+        session_key = _session_cache_key(client, session)
+        session_data = sessions.setdefault(
+            session_key,
+            {
+                "session": session,
+                "middleware_url": str(getattr(client, "middleware_url", "")),
+                "tenant_id": str(getattr(client, "tenant_id", "")),
+                "node_id": str(getattr(client, "node_id", "")),
+                "apps": {},
+            },
+        )
+        if not isinstance(session_data, dict):
+            session_data = {"session": session, "apps": {}}
+            sessions[session_key] = session_data
+        apps = session_data.setdefault("apps", {})
+        if not isinstance(apps, dict):
+            apps = {}
+            session_data["apps"] = apps
+
+        now = time.time()
+        session_data["updated_at"] = now
+        apps[_normalize_cache_key(app_query)] = {
+            "pid": ref.pid,
+            "window_id": ref.window_id,
+            "title": ref.title,
+            "app": ref.app,
+            "window": ref.window,
+            "updated_at": now,
+        }
+        try:
+            self._write(data)
+        except OSError as exc:
+            self.last_error = str(exc)
+
+    def remove_app(self, client: RemoteCliClient, session: str, app_query: str) -> None:
+        data = self._read()
+        session_data = self._session_data(client, session, data=data)
+        apps = session_data.get("apps") if isinstance(session_data, dict) else None
+        if isinstance(apps, dict):
+            apps.pop(_normalize_cache_key(app_query), None)
+            try:
+                self._write(data)
+            except OSError as exc:
+                self.last_error = str(exc)
+
+    def clear_session(self, client: RemoteCliClient, session: str) -> None:
+        data = self._read()
+        sessions = data.get("sessions")
+        if isinstance(sessions, dict):
+            sessions.pop(_session_cache_key(client, session), None)
+            try:
+                self._write(data)
+            except OSError as exc:
+                self.last_error = str(exc)
+
+    def _session_data(
+        self,
+        client: RemoteCliClient,
+        session: str,
+        data: Dict[str, Any] | None = None,
+    ) -> Dict[str, Any]:
+        data = data if data is not None else self._read()
+        sessions = data.get("sessions")
+        if not isinstance(sessions, dict):
+            return {}
+        value = sessions.get(_session_cache_key(client, session))
+        return value if isinstance(value, dict) else {}
+
+    def _read(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = {"version": 1, "sessions": {}}
+        for path in self._read_paths():
+            _merge_window_cache_data(data, self._read_path(path))
+        return data
+
+    def _read_paths(self) -> list[Path]:
+        return self._paths
+
+    def _read_path(self, path: Path) -> Dict[str, Any]:
+        try:
+            if not path.exists():
+                return {"version": 1, "sessions": {}}
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {"version": 1, "sessions": {}}
+        if not isinstance(loaded, dict):
+            return {"version": 1, "sessions": {}}
+        data = dict(loaded)
+        data.setdefault("sessions", {})
+        return data
+
+    def _write(self, data: Dict[str, Any]) -> None:
+        errors: list[str] = []
+        for path in self._paths:
+            try:
+                self._write_to_path(path, data)
+            except OSError as exc:
+                errors.append(f"{path}: {exc}")
+                continue
+            self.path = path
+            self.last_error = ""
+            return
+        raise OSError("; ".join(errors) or "no writable window cache path")
+
+    @staticmethod
+    def _write_to_path(path: Path, data: Dict[str, Any]) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+
+
+def _merge_window_cache_data(target: Dict[str, Any], source: Dict[str, Any]) -> None:
+    source_sessions = source.get("sessions")
+    if not isinstance(source_sessions, dict):
+        return
+
+    target_sessions = target.setdefault("sessions", {})
+    if not isinstance(target_sessions, dict):
+        target_sessions = {}
+        target["sessions"] = target_sessions
+
+    for session_key, source_session in source_sessions.items():
+        if not isinstance(source_session, dict):
+            continue
+        target_session = target_sessions.get(session_key)
+        if not isinstance(target_session, dict):
+            target_sessions[session_key] = source_session
+            continue
+
+        if _coerce_float(source_session.get("updated_at")) >= _coerce_float(target_session.get("updated_at")):
+            for key, value in source_session.items():
+                if key != "apps":
+                    target_session[key] = value
+
+        source_apps = source_session.get("apps")
+        if not isinstance(source_apps, dict):
+            continue
+        target_apps = target_session.setdefault("apps", {})
+        if not isinstance(target_apps, dict):
+            target_apps = {}
+            target_session["apps"] = target_apps
+        for app_key, source_app in source_apps.items():
+            target_app = target_apps.get(app_key)
+            if not isinstance(target_app, dict) or _coerce_float(source_app.get("updated_at")) >= _coerce_float(
+                target_app.get("updated_at")
+            ):
+                target_apps[app_key] = source_app

remotecli/agent_modes.py

@@ -0,0 +1,5 @@
+"""Mode constants for high-level agent wrappers."""
+
+_OBSERVE_MODES = {"uia", "vision", "som-full"}
+_PROBE_MODES = {"smart", "uia", "som"}
+_LOCATE_MODES = {"smart", "uia", "som"}

remotecli/agent_open.py

@@ -0,0 +1,323 @@
+"""Optional fast app-open helper for agent commands."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict
+
+from .agent_cache import WindowCache, WindowRef
+from .agent_result import _error
+from .agent_utils import _extract_int
+from .client import RemoteCliClient
+from .shell import ShellCommands
+
+
+WaitAndUnpack = Callable[[Dict[str, Any], str, float, float], Dict[str, Any]]
+
+_APP_ALIASES: dict[str, tuple[str, ...]] = {
+    "firefox": ("firefox", "mozilla firefox", "火狐", "火狐浏览器"),
+    "chrome": ("chrome", "google chrome", "谷歌", "谷歌浏览器"),
+    "edge": ("edge", "microsoft edge", "msedge", "微软浏览器", "edge浏览器"),
+    "wechat": ("wechat", "weixin", "微信"),
+    "wecom": ("wecom", "wxwork", "企业微信", "企微"),
+    "notepad": ("notepad", "notepad.exe", "记事本"),
+}
+
+
+def open_app_window(
+    client: RemoteCliClient,
+    shell: ShellCommands,
+    window_cache: WindowCache,
+    wait_and_unpack: WaitAndUnpack,
+    app_query: str,
+    *,
+    session_id: str = "",
+    use_window_cache: bool = True,
+    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,
+) -> Dict[str, Any]:
+    app_query = str(app_query or "").strip()
+    if not app_query:
+        return _error("open", "app query is required")
+
+    script = build_open_app_script(
+        app_query,
+        launch_path=launch_path,
+        app_args=app_args,
+        start_if_missing=start_if_missing,
+        foreground=foreground,
+        launch_timeout=launch_timeout,
+    )
+    result = wait_and_unpack(
+        shell.exec_script(script, shell="powershell", timeout_sec=max(60, launch_timeout + 10)),
+        "open",
+        wait_timeout,
+        poll_interval,
+    )
+    payload = result.get("json") if isinstance(result.get("json"), dict) else {}
+    ok = bool(result.get("ok")) and bool(payload.get("ok", True))
+    pid = _extract_int(payload, "pid", "process_id", "processId", "id")
+    window_id = _extract_int(payload, "window_id", "windowId", "hwnd", "handle")
+    title = str(payload.get("title") or payload.get("MainWindowTitle") or "")
+
+    if not ok or not pid or not window_id:
+        return {
+            "ok": False,
+            "action": "open",
+            "app": app_query,
+            "pid": pid,
+            "window_id": window_id,
+            "title": title,
+            "started": bool(payload.get("started")),
+            "source": str(payload.get("source") or ""),
+            "error": str(payload.get("error") or result.get("error") or "open did not return a usable window"),
+            "result": result,
+            **_cache_context(window_cache),
+        }
+
+    app = {
+        "name": app_query,
+        "pid": pid,
+        "running": True,
+        "source": payload.get("source") or "shell_open",
+        "launch_target": payload.get("launch_target") or "",
+    }
+    window = {
+        "window_id": window_id,
+        "title": title,
+        "pid": pid,
+        "source": payload.get("source") or "shell_open",
+    }
+    ref = WindowRef(pid=pid, window_id=window_id, title=title, app=app, window=window)
+    if use_window_cache and session_id:
+        window_cache.put(client, session_id, app_query, ref)
+
+    return {
+        "ok": True,
+        "action": "open",
+        "app": app_query,
+        "started": bool(payload.get("started")),
+        "pid": pid,
+        "window_id": window_id,
+        "title": title,
+        "source": str(payload.get("source") or "shell_open"),
+        "launch_target": str(payload.get("launch_target") or ""),
+        "window_cached": False,
+        "result": result,
+        **_cache_context(window_cache),
+    }
+
+
+def build_open_app_script(
+    app_query: str,
+    *,
+    launch_path: str = "",
+    app_args: str = "",
+    start_if_missing: bool = True,
+    foreground: bool = True,
+    launch_timeout: int = 15,
+) -> str:
+    terms = _search_terms(app_query)
+    terms_literal = ", ".join(_ps_quote(term) for term in terms)
+    return f"""
+$ErrorActionPreference = "SilentlyContinue"
+$query = {_ps_quote(app_query)}
+$launchPath = {_ps_quote(launch_path)}
+$appArgs = {_ps_quote(app_args)}
+$startIfMissing = {_ps_bool(start_if_missing)}
+$foreground = {_ps_bool(foreground)}
+$launchTimeoutSec = {max(1, int(launch_timeout))}
+$terms = @({terms_literal})
+
+function Test-AgentRemoteTextMatch($value) {{
+  $text = [string]$value
+  if ([string]::IsNullOrWhiteSpace($text)) {{ return $false }}
+  $lower = $text.ToLowerInvariant()
+  foreach ($term in $terms) {{
+    if ($lower.Contains(([string]$term).ToLowerInvariant())) {{ return $true }}
+  }}
+  return $false
+}}
+
+function Test-AgentRemoteProcessMatch($proc) {{
+  if (-not $proc) {{ return $false }}
+  if (Test-AgentRemoteTextMatch $proc.ProcessName) {{ return $true }}
+  if (Test-AgentRemoteTextMatch $proc.MainWindowTitle) {{ return $true }}
+  try {{
+    if (Test-AgentRemoteTextMatch $proc.Path) {{ return $true }}
+  }} catch {{}}
+  return $false
+}}
+
+function Find-AgentRemoteWindow() {{
+  Get-Process |
+    Where-Object {{
+      $_.MainWindowTitle -ne "" -and
+      [int64]$_.MainWindowHandle -ne 0 -and
+      (Test-AgentRemoteProcessMatch $_)
+    }} |
+    Select-Object -First 1
+}}
+
+function Set-AgentRemoteForeground($hwnd) {{
+  if (-not $foreground -or -not $hwnd -or [int64]$hwnd -eq 0) {{ return $false }}
+  try {{
+    $type = @"
+using System;
+using System.Runtime.InteropServices;
+public static class AgentRemoteUser32 {{
+  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hWnd);
+  [DllImport("user32.dll")] public static extern bool ShowWindowAsync(IntPtr hWnd, int nCmdShow);
+}}
+"@
+    Add-Type -TypeDefinition $type -ErrorAction SilentlyContinue | Out-Null
+    [AgentRemoteUser32]::ShowWindowAsync([IntPtr][int64]$hwnd, 9) | Out-Null
+    return [AgentRemoteUser32]::SetForegroundWindow([IntPtr][int64]$hwnd)
+  }} catch {{
+    return $false
+  }}
+}}
+
+function Find-AgentRemoteStartApp() {{
+  Get-StartApps |
+    Where-Object {{
+      Test-AgentRemoteTextMatch $_.Name -or Test-AgentRemoteTextMatch $_.AppID
+    }} |
+    Select-Object -First 1
+}}
+
+function Find-AgentRemoteCommand() {{
+  foreach ($term in $terms) {{
+    $clean = ([string]$term).Trim()
+    if (-not $clean -or $clean.Contains(" ")) {{ continue }}
+    $cmd = Get-Command ($clean + ".exe") -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($cmd) {{ return $cmd }}
+    $cmd = Get-Command $clean -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($cmd) {{ return $cmd }}
+  }}
+  return $null
+}}
+
+$started = $false
+$source = "running_process"
+$launchTarget = ""
+$proc = Find-AgentRemoteWindow
+
+if (-not $proc) {{
+  if (-not $startIfMissing) {{
+    [pscustomobject]@{{ ok=$false; app=$query; started=$false; error="window not found"; source="not_started" }} |
+      ConvertTo-Json -Compress
+    exit 0
+  }}
+
+  if ($launchPath) {{
+    if (Test-Path -LiteralPath $launchPath) {{
+      if ($appArgs) {{
+        Start-Process -FilePath $launchPath -ArgumentList $appArgs
+      }} else {{
+        Start-Process -FilePath $launchPath
+      }}
+      $started = $true
+      $source = "path"
+      $launchTarget = $launchPath
+    }}
+  }}
+
+  if (-not $started) {{
+    $startApp = Find-AgentRemoteStartApp
+    if ($startApp) {{
+      $launchTarget = "shell:AppsFolder\\" + $startApp.AppID
+      if ($appArgs) {{
+        Start-Process $launchTarget -ArgumentList $appArgs
+      }} else {{
+        Start-Process $launchTarget
+      }}
+      $started = $true
+      $source = "start_apps"
+    }}
+  }}
+
+  if (-not $started) {{
+    $cmd = Find-AgentRemoteCommand
+    if ($cmd) {{
+      if ($appArgs) {{
+        Start-Process -FilePath $cmd.Source -ArgumentList $appArgs
+      }} else {{
+        Start-Process -FilePath $cmd.Source
+      }}
+      $started = $true
+      $source = "command"
+      $launchTarget = $cmd.Source
+    }}
+  }}
+
+  if (-not $started) {{
+    [pscustomobject]@{{ ok=$false; app=$query; started=$false; error="app launch target not found"; source="not_found" }} |
+      ConvertTo-Json -Compress
+    exit 0
+  }}
+
+  $deadline = (Get-Date).AddSeconds($launchTimeoutSec)
+  do {{
+    Start-Sleep -Milliseconds 100
+    $proc = Find-AgentRemoteWindow
+  }} while (-not $proc -and (Get-Date) -lt $deadline)
+}}
+
+if (-not $proc) {{
+  [pscustomobject]@{{ ok=$false; app=$query; started=$started; error="window not found after launch"; source=$source; launch_target=$launchTarget }} |
+    ConvertTo-Json -Compress
+  exit 0
+}}
+
+$foregrounded = Set-AgentRemoteForeground $proc.MainWindowHandle
+[pscustomobject]@{{
+  ok = $true
+  app = $query
+  started = $started
+  pid = [int]$proc.Id
+  window_id = [int64]$proc.MainWindowHandle
+  title = [string]$proc.MainWindowTitle
+  process = [string]$proc.ProcessName
+  source = $source
+  launch_target = $launchTarget
+  foregrounded = [bool]$foregrounded
+}} | ConvertTo-Json -Compress
+""".strip()
+
+
+def _search_terms(app_query: str) -> list[str]:
+    query = " ".join(str(app_query or "").strip().split())
+    lowered = query.casefold()
+    terms: list[str] = []
+
+    def add(value: str) -> None:
+        text = " ".join(str(value or "").strip().split())
+        if text and text not in terms:
+            terms.append(text)
+
+    add(query)
+    for aliases in _APP_ALIASES.values():
+        normalized_aliases = [alias.casefold() for alias in aliases]
+        if any(lowered == alias or lowered in alias or alias in lowered for alias in normalized_aliases):
+            for alias in aliases:
+                add(alias)
+    return terms
+
+
+def _ps_quote(value: Any) -> str:
+    return "'" + str(value or "").replace("'", "''") + "'"
+
+
+def _ps_bool(value: bool) -> str:
+    return "$true" if value else "$false"
+
+
+def _cache_context(window_cache: WindowCache) -> Dict[str, Any]:
+    if not window_cache.last_error:
+        return {}
+    return {"window_cache_error": window_cache.last_error}