agentremote-cli 1.0.0__py3-none-any.whl

remotecli/agent_projection.py

@@ -0,0 +1,308 @@
+"""Compact observe projection for agent-friendly output."""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any, Dict, Iterable
+
+from .agent_utils import (
+    _extract_int,
+    _first_present,
+    _first_text,
+    _optional_bool,
+    _target_terms,
+    _truncate,
+    _truthy,
+)
+
+
+def _compact_window_state(
+    payload: Any,
+    *,
+    title: str,
+    trace_id: Any,
+    targets: Iterable[str] | str | None,
+    element_limit: int,
+) -> Dict[str, Any]:
+    data = payload if isinstance(payload, dict) else {}
+    raw_elements = _extract_element_list(data)
+    elements = [_compact_element(element, index) for index, element in enumerate(raw_elements)]
+    selected = _select_elements(elements, targets, element_limit)
+    public_items = [_public_element(item) for item in selected]
+    by_role = Counter(str(item.get("role") or "Unknown") for item in elements)
+
+    state: Dict[str, Any] = {
+        "title": title,
+        "blocking": _compact_blocking(data),
+        "focus": _compact_focus(data, elements),
+        "elements": {
+            "total": len(elements),
+            "returned": len(public_items),
+            "truncated": len(public_items) < len(elements),
+            "by_role": dict(by_role),
+            "items": public_items,
+        },
+        "artifacts": _compact_artifacts(data, trace_id),
+    }
+    page = _compact_page(data)
+    if page:
+        state["page"] = page
+    return state
+
+
+def _extract_element_list(payload: Dict[str, Any]) -> list[Dict[str, Any]]:
+    for key in ("elements", "uia_elements", "controls", "items"):
+        value = payload.get(key)
+        if isinstance(value, list):
+            return [item for item in value if isinstance(item, dict)]
+
+    for key in ("state", "window", "data"):
+        value = payload.get(key)
+        if isinstance(value, dict):
+            nested = _extract_element_list(value)
+            if nested:
+                return nested
+    return []
+
+
+def _compact_element(element: Dict[str, Any], index: int) -> Dict[str, Any]:
+    role = _first_text(element, "role", "control_type", "type", "class_name", "localized_control_type") or "Unknown"
+    label = _first_text(element, "label", "name", "text", "title", "automation_id") or ""
+    value = _first_text(element, "value", "current_value", "text_value", "display_value")
+    is_password = _is_password_element(element, role, label)
+    focused = _truthy(_first_present(element, "focused", "is_focused", "has_keyboard_focus", "keyboard_focus"))
+
+    public: Dict[str, Any] = {
+        "id": _element_id(element, index),
+        "role": role,
+    }
+    if label:
+        public["label"] = label
+
+    if value is not None:
+        value_text = str(value)
+        public["filled"] = bool(value_text)
+        if is_password:
+            public["value"] = "***" if value_text else ""
+            public["value_kind"] = "password"
+        else:
+            public["value"] = _truncate(value_text, 80)
+    elif is_password:
+        public["value_kind"] = "password"
+
+    enabled = _optional_bool(element, "enabled", "is_enabled")
+    if enabled is not None:
+        public["enabled"] = enabled
+    visible = _optional_bool(element, "visible", "is_visible", "offscreen")
+    if visible is not None:
+        public["visible"] = visible
+
+    bounds = _compact_bounds(element)
+    if bounds:
+        public["bounds"] = bounds
+
+    public["_index"] = index
+    public["_score"] = _element_score(public, label, role, is_password, focused)
+    public["_focused"] = focused
+    return public
+
+
+def _select_elements(
+    elements: list[Dict[str, Any]],
+    targets: Iterable[str] | str | None,
+    element_limit: int,
+) -> list[Dict[str, Any]]:
+    if element_limit <= 0 or not elements:
+        return []
+
+    target_terms = _target_terms(targets)
+    scored: list[tuple[int, int, Dict[str, Any]]] = []
+    for item in elements:
+        score = int(item.get("_score") or 0)
+        label = str(item.get("label") or "").lower()
+        role = str(item.get("role") or "").lower()
+        haystack = f"{label} {role}".strip()
+        for target in target_terms:
+            if target and target in haystack:
+                score += 5000
+        scored.append((score, -int(item.get("_index") or 0), item))
+
+    selected = [
+        item
+        for score, _negative_index, item in sorted(
+            scored,
+            key=lambda entry: (entry[0], entry[1]),
+            reverse=True,
+        )[:element_limit]
+        if score > 0
+    ]
+    selected.sort(key=lambda item: int(item.get("_index") or 0))
+    return selected
+
+
+def _public_element(item: Dict[str, Any]) -> Dict[str, Any]:
+    return {key: value for key, value in item.items() if not key.startswith("_")}
+
+
+def _element_score(
+    item: Dict[str, Any],
+    label: str,
+    role: str,
+    is_password: bool,
+    focused: bool,
+) -> int:
+    role_text = role.lower()
+    label_text = label.lower()
+    score = 0
+    if focused:
+        score += 900
+    if role_text in {"edit", "textbox", "text box", "document"}:
+        score += 700
+    if is_password:
+        score += 600
+    if role_text in {
+        "button",
+        "hyperlink",
+        "link",
+        "combobox",
+        "combo box",
+        "menuitem",
+        "menu item",
+        "checkbox",
+        "check box",
+        "radiobutton",
+        "radio button",
+        "tabitem",
+        "tab item",
+        "edit",
+        "textbox",
+        "text box",
+    }:
+        score += 400
+    if any(keyword in label_text for keyword in ("sign in", "login", "log in", "submit", "save", "ok", "continue", "next")):
+        score += 150
+    if item.get("enabled") is True:
+        score += 30
+    if item.get("visible") is True:
+        score += 20
+    return score
+
+
+def _compact_focus(payload: Dict[str, Any], elements: list[Dict[str, Any]]) -> Dict[str, Any] | None:
+    focus = payload.get("focus") or payload.get("focused") or payload.get("active_element")
+    if isinstance(focus, dict):
+        return _public_element(_compact_element(focus, -1))
+    for item in elements:
+        if item.get("_focused"):
+            return _public_element(item)
+    return None
+
+
+def _compact_blocking(payload: Dict[str, Any]) -> Dict[str, Any]:
+    top_window = payload.get("top_window") or payload.get("foreground_window") or payload.get("active_window")
+    overlay = payload.get("overlay") or payload.get("modal") or payload.get("dialog")
+    has_overlay = bool(payload.get("has_overlay") or payload.get("blocked") or payload.get("obscured") or overlay)
+    result: Dict[str, Any] = {"has_overlay": has_overlay}
+    if isinstance(top_window, dict):
+        result["top_window"] = _compact_window_like(top_window)
+    elif top_window:
+        result["top_window"] = str(top_window)
+    if isinstance(overlay, dict):
+        result["overlay"] = _compact_window_like(overlay)
+    elif overlay and not isinstance(overlay, bool):
+        result["overlay"] = str(overlay)
+    return result
+
+
+def _compact_page(payload: Dict[str, Any]) -> Dict[str, Any]:
+    page: Dict[str, Any] = {}
+    url = _first_text(payload, "url", "page_url", "browser_url", "address")
+    if url:
+        page["url"] = url
+    page_title = _first_text(payload, "page_title", "document_title")
+    if page_title:
+        page["title"] = page_title
+    loading = _optional_bool(payload, "loading", "is_loading")
+    if loading is not None:
+        page["loading"] = loading
+    return page
+
+
+def _compact_artifacts(payload: Dict[str, Any], trace_id: Any) -> Dict[str, Any]:
+    artifacts: Dict[str, Any] = {}
+    if trace_id:
+        artifacts["snapshot_id"] = str(trace_id)
+
+    screenshot = payload.get("screenshot")
+    if isinstance(screenshot, dict):
+        artifacts["screenshot"] = {
+            key: screenshot[key]
+            for key in ("local_path", "size_bytes", "width", "height")
+            if key in screenshot
+        }
+    elif isinstance(payload.get("screenshot_png_b64"), str):
+        artifacts["screenshot"] = {
+            "inline": True,
+            "size_bytes": len(payload["screenshot_png_b64"]),
+        }
+
+    if payload.get("tree_path"):
+        artifacts["tree_path"] = str(payload["tree_path"])
+    elif payload.get("tree_markdown"):
+        artifacts["tree_available"] = True
+    return artifacts
+
+
+def _compact_window_like(value: Dict[str, Any]) -> Dict[str, Any]:
+    compact: Dict[str, Any] = {}
+    for key in ("pid", "window_id", "title", "name", "class_name"):
+        if value.get(key) not in (None, ""):
+            compact[key] = value[key]
+    return compact
+
+
+def _element_id(element: Dict[str, Any], index: int) -> str:
+    value = _first_present(element, "id", "element_id", "element_index", "index")
+    if value not in (None, ""):
+        text = str(value)
+        return text if text.startswith("e") else f"e{text}"
+    return f"e{index}"
+
+
+def _compact_bounds(element: Dict[str, Any]) -> Dict[str, int]:
+    bounds = element.get("bounds") or element.get("bbox") or element.get("rect")
+    if isinstance(bounds, dict):
+        x = _extract_int(bounds, "x", "left")
+        y = _extract_int(bounds, "y", "top")
+        width = _extract_int(bounds, "width", "w")
+        height = _extract_int(bounds, "height", "h")
+        right = _extract_int(bounds, "right")
+        bottom = _extract_int(bounds, "bottom")
+        if not width and right:
+            width = max(0, right - x)
+        if not height and bottom:
+            height = max(0, bottom - y)
+        result = {"x": x, "y": y}
+        if width:
+            result["width"] = width
+        if height:
+            result["height"] = height
+        return result
+    if isinstance(bounds, (list, tuple)) and len(bounds) >= 4:
+        try:
+            x1, y1, x2, y2 = [int(float(part)) for part in bounds[:4]]
+        except (TypeError, ValueError):
+            return {}
+        return {"x": x1, "y": y1, "width": max(0, x2 - x1), "height": max(0, y2 - y1)}
+    return {}
+
+
+def _is_password_element(element: Dict[str, Any], role: str, label: str) -> bool:
+    if _truthy(_first_present(element, "is_password", "password", "isPassword")):
+        return True
+    role_text = role.lower()
+    input_like = role_text in {"edit", "textbox", "text box"} or "password" in role_text
+    if not input_like:
+        return False
+    text = f"{role} {label} {_first_text(element, 'automation_id', 'name') or ''}".lower()
+    return any(hint in text for hint in ("password", "passwd", "pwd", "pin", "\u5bc6\u7801", "\u53e3\u4ee4"))

remotecli/agent_result.py

@@ -0,0 +1,81 @@
+"""Result normalization helpers for agent-friendly commands."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict
+
+
+def _normalize_task_result(data: Dict[str, Any], action: str) -> Dict[str, Any]:
+    result = data.get("result") if isinstance(data.get("result"), dict) else {}
+    output = result.get("output") if result else data.get("output")
+    parsed_output = _parse_json_if_possible(output)
+
+    stdout = ""
+    stderr = ""
+    exit_code = None
+    json_payload = None
+    error = ""
+    success_value = None
+
+    if isinstance(parsed_output, dict):
+        stdout = str(parsed_output.get("stdout") or "")
+        stderr = str(parsed_output.get("stderr") or "")
+        exit_code = parsed_output.get("exit_code", parsed_output.get("returncode"))
+        json_payload = parsed_output.get("json")
+        error = str(parsed_output.get("error") or "")
+        success_value = parsed_output.get("success")
+    elif isinstance(parsed_output, (list, dict)):
+        json_payload = parsed_output
+    elif isinstance(parsed_output, str):
+        stdout = parsed_output
+
+    if json_payload is None and stdout:
+        parsed_stdout = _parse_json_if_possible(stdout.strip())
+        if isinstance(parsed_stdout, (dict, list)):
+            json_payload = parsed_stdout
+
+    result_status = result.get("status") if result else data.get("status")
+    ok = data.get("status") == "done" or result_status in {"SUCCESS", "success", "ok"}
+    if result_status and str(result_status).upper() not in {"SUCCESS", "DONE", "OK"}:
+        ok = False
+    if success_value is False:
+        ok = False
+    if exit_code is not None:
+        try:
+            ok = ok and int(exit_code) == 0
+        except (TypeError, ValueError):
+            ok = False
+    if data.get("status") in {"failed", "timeout", "rejected"}:
+        ok = False
+
+    return {
+        "ok": bool(ok),
+        "action": action,
+        "trace_id": data.get("trace_id"),
+        "status": data.get("status"),
+        "result_status": result_status,
+        "stdout": stdout,
+        "stderr": stderr,
+        "exit_code": exit_code,
+        "json": json_payload,
+        "output": parsed_output,
+        "error": error or str(data.get("error") or data.get("reason") or ""),
+        "raw": data,
+    }
+
+
+def _parse_json_if_possible(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    text = value.strip()
+    if not text:
+        return value
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return value
+
+
+def _error(action: str, message: str, **extra: Any) -> Dict[str, Any]:
+    return {"ok": False, "action": action, "error": message, **extra}

remotecli/agent_utils.py

@@ -0,0 +1,113 @@
+"""Shared helpers for agent-friendly remotecli wrappers."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+
+def _coerce_int(value: Any) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _coerce_float(value: Any) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _normalize_mode(value: str, *, default: str) -> str:
+    mode = str(value or "").strip().lower()
+    return mode or default
+
+
+def _normalize_scroll_direction(value: str) -> str:
+    direction = str(value or "down").strip().lower()
+    return direction if direction in {"up", "down", "left", "right"} else "down"
+
+
+def _normalize_scroll_amount(value: Any) -> int:
+    try:
+        amount = int(value)
+    except (TypeError, ValueError):
+        amount = 3
+    return max(1, min(50, amount))
+
+
+def _normalize_scroll_by(value: str) -> str:
+    by = str(value or "line").strip().lower()
+    return by if by in {"line", "page"} else "line"
+
+
+def _extract_int(item: dict[str, Any], *keys: str) -> int:
+    for key in keys:
+        value = item.get(key)
+        if value in (None, ""):
+            continue
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            continue
+    return 0
+
+
+def _target_terms(targets: Iterable[str] | str | None) -> list[str]:
+    if targets is None:
+        return []
+    if isinstance(targets, str):
+        raw_terms = targets.split(",")
+    else:
+        raw_terms = [str(term) for term in targets]
+    return [term.strip().lower() for term in raw_terms if term.strip()]
+
+
+def _target_texts(targets: Iterable[str] | str | None) -> list[str]:
+    if targets is None:
+        return []
+    if isinstance(targets, str):
+        raw_terms = targets.split(",")
+    else:
+        raw_terms = [str(term) for term in targets]
+    return [term.strip() for term in raw_terms if term.strip()]
+
+
+def _first_text(item: dict[str, Any], *keys: str) -> str | None:
+    value = _first_present(item, *keys)
+    if value in (None, ""):
+        return None
+    return str(value)
+
+
+def _first_present(item: dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if key in item:
+            return item[key]
+    return None
+
+
+def _optional_bool(item: dict[str, Any], *keys: str) -> bool | None:
+    for key in keys:
+        if key not in item:
+            continue
+        value = _truthy(item[key])
+        return not value if key == "offscreen" else value
+    return None
+
+
+def _truthy(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return value != 0
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "y", "on"}
+    return bool(value)
+
+
+def _truncate(value: str, max_length: int) -> str:
+    if len(value) <= max_length:
+        return value
+    return value[: max_length - 3] + "..."