androidctl 0.1.0__py3-none-any.whl

androidctld/snapshots/schema.py

@@ -0,0 +1,74 @@
+"""Boundary DTOs for raw snapshot payloads."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field, StringConstraints
+
+from androidctld.schema import ApiModel
+
+TrimmedString = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+NonNegativeInt = Annotated[int, Field(ge=0)]
+PositiveInt = Annotated[int, Field(ge=1)]
+
+
+class RawDisplayPayload(ApiModel):
+    width_px: PositiveInt
+    height_px: PositiveInt
+    density_dpi: PositiveInt
+    rotation: NonNegativeInt
+
+
+class RawImePayload(ApiModel):
+    visible: bool
+    window_id: str | None
+
+
+class RawWindowPayload(ApiModel):
+    window_id: TrimmedString
+    type: TrimmedString
+    layer: int
+    package_name: TrimmedString | None
+    bounds: list[int]
+    root_rid: TrimmedString
+
+
+class RawNodePayload(ApiModel):
+    rid: TrimmedString
+    window_id: TrimmedString
+    parent_rid: str | None
+    child_rids: list[str]
+    class_name: TrimmedString
+    resource_id: str | None
+    text: str | None
+    content_desc: str | None
+    hint_text: str | None
+    state_description: str | None
+    pane_title: str | None
+    package_name: TrimmedString | None
+    bounds: list[int]
+    visible_to_user: bool
+    important_for_accessibility: bool
+    clickable: bool
+    enabled: bool
+    editable: bool
+    focusable: bool
+    focused: bool
+    checkable: bool
+    checked: bool
+    selected: bool
+    scrollable: bool
+    password: bool
+    actions: list[str]
+
+
+class RawSnapshotPayload(ApiModel):
+    snapshot_id: NonNegativeInt
+    captured_at: TrimmedString
+    package_name: TrimmedString | None
+    activity_name: str | None
+    ime: RawImePayload
+    windows: list[RawWindowPayload]
+    nodes: list[RawNodePayload]
+    display: RawDisplayPayload

androidctld/snapshots/service.py

@@ -0,0 +1,138 @@
+"""Session-level snapshot retrieval."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from androidctld.device.bootstrap import DeviceBootstrapper
+from androidctld.device.rpc import DeviceRpcClient
+from androidctld.device.types import RuntimeTransport
+from androidctld.errors import DaemonError, DaemonErrorCode
+from androidctld.runtime import RuntimeKernel, RuntimeLifecycleLease
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime_policy import (
+    DEVICE_RPC_REQUEST_ID_SNAPSHOT,
+    TRANSIENT_INVALID_SNAPSHOT_RETRY_SECONDS,
+)
+from androidctld.snapshots.models import RawSnapshot
+
+SleepFn = Callable[[float], None]
+TimeFn = Callable[[], float]
+
+
+class SnapshotService:
+    def __init__(
+        self,
+        *,
+        runtime_kernel: RuntimeKernel,
+        bootstrapper: DeviceBootstrapper | None = None,
+    ) -> None:
+        self._bootstrapper = bootstrapper or DeviceBootstrapper()
+        self._runtime_kernel = runtime_kernel
+
+    def fetch(
+        self,
+        session: WorkspaceRuntime,
+        force_refresh: bool,
+        *,
+        lifecycle_lease: RuntimeLifecycleLease | None = None,
+    ) -> RawSnapshot:
+        if not force_refresh and session.latest_snapshot is not None:
+            _raise_if_stale_lifecycle_lease(session, lifecycle_lease)
+            return session.latest_snapshot
+        return self.device_client(
+            session,
+            lifecycle_lease=lifecycle_lease,
+        ).snapshot_get(
+            request_id=DEVICE_RPC_REQUEST_ID_SNAPSHOT,
+        )
+
+    def device_client(
+        self,
+        session: WorkspaceRuntime,
+        *,
+        lifecycle_lease: RuntimeLifecycleLease | None = None,
+    ) -> DeviceRpcClient:
+        if session.connection is None or not session.device_token:
+            raise DaemonError(
+                code=DaemonErrorCode.RUNTIME_NOT_CONNECTED,
+                message="runtime is not connected to a device",
+                retryable=False,
+                details={"workspaceRoot": session.workspace_root.as_posix()},
+                http_status=200,
+            )
+        transport = self.ensure_transport(
+            session,
+            lifecycle_lease=lifecycle_lease,
+        )
+        return DeviceRpcClient(endpoint=transport.endpoint, token=session.device_token)
+
+    def ensure_transport(
+        self,
+        session: WorkspaceRuntime,
+        *,
+        lifecycle_lease: RuntimeLifecycleLease | None = None,
+    ) -> RuntimeTransport:
+        return self._runtime_kernel.rebootstrap_transport(
+            session,
+            bootstrap=self._bootstrapper.bootstrap,
+            lease=lifecycle_lease,
+        )
+
+
+def _raise_if_stale_lifecycle_lease(
+    session: WorkspaceRuntime,
+    lifecycle_lease: RuntimeLifecycleLease | None,
+) -> None:
+    if lifecycle_lease is None:
+        return
+    with session.lock:
+        if lifecycle_lease.is_current(session):
+            return
+    raise DaemonError(
+        code=DaemonErrorCode.RUNTIME_NOT_CONNECTED,
+        message="runtime is not connected to a device",
+        retryable=False,
+        details={"workspaceRoot": session.workspace_root.as_posix()},
+        http_status=200,
+    )
+
+
+def is_transient_invalid_package_snapshot(error: DaemonError) -> bool:
+    return (
+        error.code == DaemonErrorCode.DEVICE_RPC_FAILED
+        and error.details.get("reason") == "invalid_snapshot"
+        and error.details.get("field") == "result.packageName"
+    )
+
+
+def fetch_with_transient_invalid_snapshot_retry(
+    snapshot_service: SnapshotService,
+    *,
+    session: WorkspaceRuntime,
+    force_refresh: bool,
+    lifecycle_lease: RuntimeLifecycleLease | None = None,
+    deadline_at: float,
+    max_retries: int,
+    sleep_fn: SleepFn,
+    time_fn: TimeFn,
+) -> RawSnapshot:
+    attempts = 0
+    while True:
+        try:
+            return snapshot_service.fetch(
+                session,
+                force_refresh=force_refresh,
+                lifecycle_lease=lifecycle_lease,
+            )
+        except DaemonError as error:
+            if not is_transient_invalid_package_snapshot(error):
+                raise
+            now = time_fn()
+            if attempts >= max_retries or now >= deadline_at:
+                raise
+            attempts += 1
+            remaining = max(deadline_at - now, 0.0)
+            sleep_duration = min(remaining, TRANSIENT_INVALID_SNAPSHOT_RETRY_SECONDS)
+            if sleep_duration > 0.0:
+                sleep_fn(sleep_duration)

androidctld/text_equivalence.py

@@ -0,0 +1,67 @@
+"""Shared internal text normalization and searchable-text helpers."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Any
+
+from androidctld.snapshots.models import RawNode
+
+_WHITESPACE_RE = re.compile(r"\s+")
+_STATE_DESCRIPTION_SPLIT_RE = re.compile(r"[,;/]+")
+_STATE_ONLY_TOKENS = {
+    "on",
+    "off",
+    "checked",
+    "unchecked",
+    "not checked",
+    "selected",
+    "disabled",
+    "focused",
+    "expanded",
+    "collapsed",
+    "password",
+}
+
+
+def normalized_text_surface(value: Any) -> str:
+    if value is None:
+        return ""
+    text = unicodedata.normalize("NFKC", str(value))
+    return _WHITESPACE_RE.sub(" ", text).strip()
+
+
+def canonical_text_key(value: Any) -> str:
+    return normalized_text_surface(value).casefold()
+
+
+def semantic_state_description_remainder(value: Any) -> str:
+    normalized = normalized_text_surface(value)
+    if not normalized:
+        return ""
+    parts = [
+        part.strip()
+        for part in _STATE_DESCRIPTION_SPLIT_RE.split(normalized)
+        if part.strip()
+    ]
+    if not parts:
+        return normalized
+    semantic_parts = [
+        part for part in parts if canonical_text_key(part) not in _STATE_ONLY_TOKENS
+    ]
+    return " ".join(semantic_parts)
+
+
+def searchable_raw_node_texts(raw_node: RawNode) -> tuple[str, ...]:
+    candidates: list[str] = []
+    for value in (
+        raw_node.text,
+        raw_node.content_desc,
+        raw_node.hint_text,
+        semantic_state_description_remainder(raw_node.state_description),
+    ):
+        normalized = normalized_text_surface(value)
+        if normalized:
+            candidates.append(normalized)
+    return tuple(candidates)

androidctld/waits/__init__.py

@@ -0,0 +1 @@
+"""Wait helpers for androidctld."""

androidctld/waits/evaluators.py

@@ -0,0 +1,216 @@
+"""Wait evaluation helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, TypeAlias
+
+from androidctld.app_targets import AppTargetMatch, match_app_target
+from androidctld.commands.command_models import (
+    AppWaitPredicate,
+    GoneWaitPredicate,
+    IdleWaitPredicate,
+    ScreenChangeWaitPredicate,
+    TextWaitPredicate,
+    WaitCommand,
+)
+from androidctld.protocol import CommandKind
+from androidctld.runtime_policy import WAIT_IDLE_STABLE_WINDOW_MS
+from androidctld.semantics.compiler import CompiledScreen
+from androidctld.semantics.public_models import (
+    PublicNode,
+    PublicScreen,
+    public_group_nodes,
+)
+from androidctld.snapshots.models import RawSnapshot
+from androidctld.snapshots.refresh import compiled_screen_signature
+from androidctld.waits.matcher import matches_text
+
+
+@dataclass(frozen=True, slots=True)
+class WaitReadyContext:
+    snapshot: RawSnapshot
+    public_screen: PublicScreen
+    compiled_screen: CompiledScreen | None
+
+
+@dataclass(frozen=True, slots=True)
+class WaitIdleEvaluationState:
+    idle_signature: tuple[Any, ...] | None = None
+    idle_stable_since: float | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class WaitMatchData:
+    snapshot: RawSnapshot
+    app_match: AppTargetMatch | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class WaitMatched:
+    match: WaitMatchData
+
+
+@dataclass(frozen=True, slots=True)
+class WaitNoMatch:
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class WaitIdleTracking:
+    idle_state: WaitIdleEvaluationState
+
+
+WaitEvaluationOutcome: TypeAlias = WaitMatched | WaitNoMatch | WaitIdleTracking
+
+
+def _evaluate_text_wait(
+    *,
+    text: str,
+    snapshot: RawSnapshot,
+    compiled_screen: CompiledScreen | None,
+) -> WaitEvaluationOutcome:
+    if compiled_screen is None:
+        return WaitNoMatch()
+    if matches_text(snapshot, text):
+        return WaitMatched(WaitMatchData(snapshot=snapshot))
+    return WaitNoMatch()
+
+
+def _evaluate_screen_change_wait(
+    *,
+    source_screen_id: str,
+    snapshot: RawSnapshot,
+    public_screen: PublicScreen,
+) -> WaitEvaluationOutcome:
+    if public_screen.screen_id != source_screen_id:
+        return WaitMatched(WaitMatchData(snapshot=snapshot))
+    return WaitNoMatch()
+
+
+def _screen_contains_ref(screen: PublicScreen, ref: str) -> bool:
+    nodes = (
+        *public_group_nodes(screen, "targets"),
+        *public_group_nodes(screen, "context"),
+        *public_group_nodes(screen, "dialog"),
+        *public_group_nodes(screen, "keyboard"),
+        *public_group_nodes(screen, "system"),
+    )
+    return any(_node_has_ref(node, ref) for node in nodes)
+
+
+def _node_has_ref(node: PublicNode, ref: str) -> bool:
+    return node.ref == ref
+
+
+def _evaluate_gone_wait(
+    *,
+    ref: str,
+    snapshot: RawSnapshot,
+    public_screen: PublicScreen,
+) -> WaitEvaluationOutcome:
+    if not _screen_contains_ref(public_screen, ref):
+        return WaitMatched(WaitMatchData(snapshot=snapshot))
+    return WaitNoMatch()
+
+
+def _evaluate_app_wait(
+    *,
+    package_name: str,
+    snapshot: RawSnapshot,
+) -> WaitEvaluationOutcome:
+    app_match = match_app_target(package_name, snapshot.package_name)
+    if app_match is not None:
+        return WaitMatched(WaitMatchData(snapshot=snapshot, app_match=app_match))
+    return WaitNoMatch()
+
+
+def _evaluate_idle_wait(
+    *,
+    snapshot: RawSnapshot,
+    compiled_screen: CompiledScreen | None,
+    idle_state: WaitIdleEvaluationState,
+    now: float,
+) -> WaitEvaluationOutcome:
+    if compiled_screen is None:
+        return WaitIdleTracking(WaitIdleEvaluationState())
+    current_signature = compiled_screen_signature(compiled_screen, snapshot)
+    if current_signature == idle_state.idle_signature:
+        stable_since = (
+            idle_state.idle_stable_since
+            if idle_state.idle_stable_since is not None
+            else now
+        )
+        if (now - stable_since) * 1000 >= WAIT_IDLE_STABLE_WINDOW_MS:
+            return WaitMatched(
+                WaitMatchData(
+                    snapshot=snapshot,
+                )
+            )
+        return WaitIdleTracking(
+            WaitIdleEvaluationState(
+                idle_signature=current_signature,
+                idle_stable_since=stable_since,
+            )
+        )
+    return WaitIdleTracking(
+        WaitIdleEvaluationState(
+            idle_signature=current_signature,
+            idle_stable_since=now,
+        )
+    )
+
+
+def evaluate_ready_wait_match(
+    *,
+    command: WaitCommand,
+    ready: WaitReadyContext,
+    idle_state: WaitIdleEvaluationState,
+    now: float,
+) -> WaitEvaluationOutcome:
+    if command.kind is not CommandKind.WAIT:
+        raise TypeError("wait evaluation kind must be canonical wait")
+    predicate = command.predicate
+    if isinstance(predicate, TextWaitPredicate):
+        return _evaluate_text_wait(
+            text=predicate.text,
+            snapshot=ready.snapshot,
+            compiled_screen=ready.compiled_screen,
+        )
+    if isinstance(predicate, ScreenChangeWaitPredicate):
+        return _evaluate_screen_change_wait(
+            source_screen_id=predicate.source_screen_id,
+            snapshot=ready.snapshot,
+            public_screen=ready.public_screen,
+        )
+    if isinstance(predicate, GoneWaitPredicate):
+        return _evaluate_gone_wait(
+            ref=predicate.ref,
+            snapshot=ready.snapshot,
+            public_screen=ready.public_screen,
+        )
+    if isinstance(predicate, AppWaitPredicate):
+        return _evaluate_app_wait(
+            package_name=predicate.package_name,
+            snapshot=ready.snapshot,
+        )
+    if isinstance(predicate, IdleWaitPredicate):
+        return _evaluate_idle_wait(
+            snapshot=ready.snapshot,
+            compiled_screen=ready.compiled_screen,
+            idle_state=idle_state,
+            now=now,
+        )
+    raise TypeError(f"unsupported wait evaluator kind: {command.wait_kind.value!r}")
+
+
+__all__ = [
+    "WaitEvaluationOutcome",
+    "WaitIdleEvaluationState",
+    "WaitIdleTracking",
+    "WaitMatchData",
+    "WaitMatched",
+    "WaitNoMatch",
+    "WaitReadyContext",
+    "evaluate_ready_wait_match",
+]