androidctl 0.1.0__py3-none-any.whl

androidctld/actions/request_builder.py

@@ -0,0 +1,204 @@
+"""Helpers for building device action requests and resolving ref targets."""
+
+from __future__ import annotations
+
+from androidctld.actions.submit_routing import SubmitRouteOutcome
+from androidctld.commands.command_models import (
+    ActionCommand,
+    FocusCommand,
+    GlobalCommand,
+    LongTapCommand,
+    OpenCommand,
+    RefBoundActionCommand,
+    ScrollCommand,
+    SubmitCommand,
+    TapCommand,
+    TypeCommand,
+    is_ref_bound_action_command,
+)
+from androidctld.commands.open_targets import (
+    OpenAppTarget,
+    OpenUrlTarget,
+    validate_open_target,
+)
+from androidctld.device.action_models import (
+    BuiltDeviceActionRequest,
+    GlobalActionRequest,
+    HandleTarget,
+    LaunchAppActionRequest,
+    LongTapActionRequest,
+    NodeActionRequest,
+    NoneTarget,
+    OpenUrlActionRequest,
+    ScrollActionRequest,
+    TapActionRequest,
+    TypeActionRequest,
+)
+from androidctld.errors import DaemonError, DaemonErrorCode, bad_request
+from androidctld.protocol import CommandKind
+from androidctld.refs.models import NodeHandle
+from androidctld.refs.repair import (
+    ref_repair_error,
+    resolve_ref_decision,
+)
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime.screen_state import (
+    current_artifacts,
+    current_public_screen,
+)
+from androidctld.runtime_policy import action_timeout_ms
+
+
+def build_action_request(
+    session: WorkspaceRuntime, command: ActionCommand
+) -> BuiltDeviceActionRequest:
+    if isinstance(command, OpenCommand):
+        return build_open_action_request(command)
+    if isinstance(command, GlobalCommand):
+        return BuiltDeviceActionRequest(
+            payload=GlobalActionRequest(
+                target=NoneTarget(),
+                action=command.action,
+                timeout_ms=action_timeout_ms(command.kind),
+            )
+        )
+    if is_ref_bound_action_command(command):
+        handle = resolve_ref_target(session, command.ref, command.source_screen_id)
+        return build_action_request_for_binding(handle, command)
+    raise bad_request("unsupported action kind", {"kind": command.kind.value})
+
+
+def build_action_request_for_binding(
+    handle: NodeHandle, command: RefBoundActionCommand
+) -> BuiltDeviceActionRequest:
+    if isinstance(command, TapCommand):
+        return BuiltDeviceActionRequest(
+            payload=TapActionRequest(
+                target=HandleTarget(handle),
+                timeout_ms=action_timeout_ms(command.kind),
+            ),
+            request_handle=handle,
+        )
+    if isinstance(command, LongTapCommand):
+        return BuiltDeviceActionRequest(
+            payload=LongTapActionRequest(
+                target=HandleTarget(handle),
+                timeout_ms=action_timeout_ms(command.kind),
+            ),
+            request_handle=handle,
+        )
+    if isinstance(command, TypeCommand):
+        return BuiltDeviceActionRequest(
+            payload=TypeActionRequest(
+                target=HandleTarget(handle),
+                text=command.text,
+                timeout_ms=action_timeout_ms(command.kind),
+            ),
+            request_handle=handle,
+        )
+    if isinstance(command, FocusCommand):
+        return BuiltDeviceActionRequest(
+            payload=NodeActionRequest(
+                target=HandleTarget(handle),
+                action=command.kind.value,
+                timeout_ms=action_timeout_ms(command.kind),
+            ),
+            request_handle=handle,
+        )
+    if isinstance(command, SubmitCommand):
+        return BuiltDeviceActionRequest(
+            payload=NodeActionRequest(
+                target=HandleTarget(handle),
+                action=command.kind.value,
+                timeout_ms=action_timeout_ms(command.kind),
+            ),
+            request_handle=handle,
+        )
+    if isinstance(command, ScrollCommand):
+        return BuiltDeviceActionRequest(
+            payload=ScrollActionRequest(
+                target=HandleTarget(handle),
+                direction=command.direction,
+                timeout_ms=action_timeout_ms(command.kind),
+            ),
+            request_handle=handle,
+        )
+    raise bad_request("unsupported action kind", {"kind": command.kind.value})
+
+
+def build_submit_action_request_for_route(
+    route: SubmitRouteOutcome,
+) -> BuiltDeviceActionRequest:
+    if route.route == "direct":
+        return BuiltDeviceActionRequest(
+            payload=NodeActionRequest(
+                target=HandleTarget(route.subject_handle),
+                action=CommandKind.SUBMIT.value,
+                timeout_ms=action_timeout_ms(CommandKind.SUBMIT),
+            ),
+            request_handle=route.subject_handle,
+            dispatched_handle=route.dispatched_handle,
+            submit_route=route.route,
+        )
+    return BuiltDeviceActionRequest(
+        payload=TapActionRequest(
+            target=HandleTarget(route.dispatched_handle),
+            timeout_ms=action_timeout_ms(CommandKind.SUBMIT),
+        ),
+        request_handle=route.subject_handle,
+        dispatched_handle=route.dispatched_handle,
+        submit_route=route.route,
+    )
+
+
+def build_open_action_request(command: ActionCommand) -> BuiltDeviceActionRequest:
+    if not isinstance(command, OpenCommand):
+        raise bad_request("open action request requires an open command")
+    target = validate_open_target(command.target)
+    if isinstance(target, OpenAppTarget):
+        return BuiltDeviceActionRequest(
+            payload=LaunchAppActionRequest(
+                target=NoneTarget(),
+                package_name=target.package_name,
+                timeout_ms=action_timeout_ms(CommandKind.OPEN),
+            )
+        )
+    if isinstance(target, OpenUrlTarget):
+        return BuiltDeviceActionRequest(
+            payload=OpenUrlActionRequest(
+                target=NoneTarget(),
+                url=target.url,
+                timeout_ms=action_timeout_ms(CommandKind.OPEN),
+            )
+        )
+    raise bad_request("open requires target.kind app|url and target.value")
+
+
+def resolve_ref_target(
+    session: WorkspaceRuntime,
+    ref: str,
+    source_screen_id: str,
+) -> NodeHandle:
+    ensure_screen_ready(session)
+    decision = resolve_ref_decision(session, ref, source_screen_id)
+    if not decision.is_resolved:
+        raise ref_repair_error(
+            decision,
+            public_screen=current_public_screen(session),
+            artifacts=current_artifacts(session),
+        )
+    binding = decision.binding
+    if binding is None:
+        raise RuntimeError("resolved ref decision is missing its binding")
+    return binding.handle
+
+
+def ensure_screen_ready(session: WorkspaceRuntime) -> None:
+    if session.screen_state is None or session.latest_snapshot is None:
+        raise DaemonError(
+            code=DaemonErrorCode.SCREEN_NOT_READY,
+            message="screen is not ready yet",
+            retryable=False,
+            details={"workspaceRoot": session.workspace_root.as_posix()},
+            http_status=200,
+        )

androidctld/actions/settle.py

@@ -0,0 +1,146 @@
+"""Action settle loop for post-mutation stabilization."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from androidctld.device.interfaces import EventPollingClient
+from androidctld.errors import DaemonError
+from androidctld.observation import (
+    ObservationLoop,
+    ObservationPolicy,
+    ObservationPollOutcome,
+)
+from androidctld.protocol import CommandKind
+from androidctld.runtime import RuntimeLifecycleLease
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime_policy import (
+    DEVICE_RPC_REQUEST_ID_SETTLE,
+    SETTLE_POLL_SLICE_MS,
+    TRANSIENT_INVALID_SNAPSHOT_MAX_RETRIES,
+    settle_max_total_ms,
+    settle_min_grace_ms,
+    settle_snapshot_max_interval_ms,
+    settle_stable_window_ms,
+)
+from androidctld.semantics.compiler import SemanticCompiler
+from androidctld.snapshots.models import RawSnapshot
+from androidctld.snapshots.refresh import settle_screen_signature
+from androidctld.snapshots.service import (
+    SnapshotService,
+    fetch_with_transient_invalid_snapshot_retry,
+)
+
+SleepFn = Callable[[float], None]
+TimeFn = Callable[[], float]
+
+
+@dataclass(frozen=True)
+class SettledSnapshot:
+    snapshot: RawSnapshot
+    timed_out: bool
+
+
+class ActionSettler:
+    def __init__(
+        self,
+        snapshot_service: SnapshotService,
+        semantic_compiler: SemanticCompiler,
+        sleep_fn: SleepFn,
+        time_fn: TimeFn,
+    ) -> None:
+        self._snapshot_service = snapshot_service
+        self._semantic_compiler = semantic_compiler
+        self._sleep_fn = sleep_fn
+        self._time_fn = time_fn
+
+    def settle(
+        self,
+        session: WorkspaceRuntime,
+        client: EventPollingClient,
+        kind: CommandKind,
+        baseline_signature: tuple[object, ...],
+        *,
+        lifecycle_lease: RuntimeLifecycleLease,
+    ) -> SettledSnapshot:
+        observation = ObservationLoop.begin(
+            ObservationPolicy(
+                min_grace_ms=settle_min_grace_ms(kind),
+                snapshot_max_interval_ms=settle_snapshot_max_interval_ms(kind),
+                stable_window_ms=settle_stable_window_ms(kind),
+                max_total_ms=settle_max_total_ms(kind),
+                poll_slice_ms=SETTLE_POLL_SLICE_MS,
+            ),
+            started_at=self._time_fn(),
+        )
+        latest_snapshot: RawSnapshot | None = None
+        latest_signature = baseline_signature
+        while True:
+            now = self._time_fn()
+            poll_wait_ms = observation.poll_wait_ms(now)
+            poll_outcome = ObservationPollOutcome(
+                saw_events=False,
+                need_resync=False,
+                latest_seq=observation.after_seq,
+            )
+            if poll_wait_ms > 0:
+                polled_at = self._time_fn()
+                try:
+                    poll_result = client.events_poll(
+                        after_seq=observation.after_seq,
+                        wait_ms=poll_wait_ms,
+                        limit=1,
+                        request_id=DEVICE_RPC_REQUEST_ID_SETTLE,
+                    )
+                    poll_outcome = observation.apply_poll_result(poll_result)
+                except DaemonError:
+                    self._sleep_fn(poll_wait_ms / 1000.0)
+                else:
+                    if not poll_outcome.saw_events and self._time_fn() <= polled_at:
+                        self._sleep_fn(poll_wait_ms / 1000.0)
+            now = self._time_fn()
+            if not observation.should_refresh(
+                now,
+                saw_events=poll_outcome.saw_events,
+                need_resync=poll_outcome.need_resync,
+            ):
+                if observation.timed_out(now) and latest_snapshot is not None:
+                    return SettledSnapshot(
+                        snapshot=latest_snapshot,
+                        timed_out=True,
+                    )
+                continue
+
+            snapshot = fetch_with_transient_invalid_snapshot_retry(
+                self._snapshot_service,
+                session=session,
+                force_refresh=True,
+                lifecycle_lease=lifecycle_lease,
+                deadline_at=observation.deadline_at,
+                max_retries=TRANSIENT_INVALID_SNAPSHOT_MAX_RETRIES,
+                sleep_fn=self._sleep_fn,
+                time_fn=self._time_fn,
+            )
+            observation.mark_refreshed(self._time_fn())
+            compiled_screen = self._semantic_compiler.compile(
+                session.screen_sequence + 1,
+                snapshot,
+            )
+            signature = settle_screen_signature(compiled_screen, snapshot)
+            latest_snapshot = snapshot
+            is_stable = observation.observe_stability(
+                self._time_fn(),
+                changed=signature != latest_signature,
+            )
+            latest_signature = signature
+            if is_stable:
+                return SettledSnapshot(
+                    snapshot=snapshot,
+                    timed_out=False,
+                )
+            if observation.timed_out(self._time_fn()):
+                return SettledSnapshot(
+                    snapshot=snapshot,
+                    timed_out=True,
+                )

androidctld/actions/submit_confirmation.py

@@ -0,0 +1,211 @@
+"""Shared submit confirmation helpers for standalone submit commands."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Literal
+
+from androidctld.actions.type_confirmation import (
+    TypeConfirmationContext,
+    fingerprint_rematch_confirmation_node,
+    reused_ref_confirmation_node,
+    snapshot_node_for_handle,
+)
+from androidctld.commands.command_models import SubmitCommand
+from androidctld.device.types import ActionPerformResult, ActionStatus
+from androidctld.errors import DaemonError, DaemonErrorCode
+from androidctld.refs.models import NodeHandle, RefBinding
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.semantics.public_models import (
+    PublicNode,
+    PublicScreen,
+    public_group_nodes,
+)
+from androidctld.snapshots.models import RawNode, RawSnapshot
+
+
+@dataclass(frozen=True)
+class SubmitConfirmationContext:
+    ref: str | None
+    request_handle: NodeHandle | None
+    binding: RefBinding | None
+
+
+@dataclass(frozen=True)
+class SubmitConfirmationOutcome:
+    status: Literal["sameTarget", "targetGone", "publicChange", "unconfirmed"]
+    node: RawNode | None
+    target_handle: NodeHandle
+
+
+def build_submit_confirmation_context(
+    session: WorkspaceRuntime,
+    command: SubmitCommand,
+    request_handle: NodeHandle | None,
+) -> SubmitConfirmationContext:
+    binding = session.ref_registry.get(command.ref)
+    return SubmitConfirmationContext(
+        ref=command.ref,
+        request_handle=request_handle,
+        binding=None if binding is None else deepcopy(binding),
+    )
+
+
+def submit_confirmation_node(
+    *,
+    session: WorkspaceRuntime | None,
+    snapshot: RawSnapshot,
+    context: SubmitConfirmationContext | None,
+    command_target_handle: NodeHandle,
+) -> RawNode | None:
+    direct_node = snapshot_node_for_handle(snapshot, command_target_handle)
+    if direct_node is not None:
+        return direct_node
+    if session is None or context is None:
+        return None
+    if (
+        context.request_handle is not None
+        and command_target_handle != context.request_handle
+    ):
+        return None
+    type_context = TypeConfirmationContext(
+        ref=context.ref,
+        request_handle=context.request_handle,
+        binding=context.binding,
+    )
+    for node in (
+        reused_ref_confirmation_node(session, snapshot, type_context),
+        fingerprint_rematch_confirmation_node(session, snapshot, type_context),
+    ):
+        if node is not None:
+            return node
+    return None
+
+
+def submit_public_change_is_attributable(
+    previous_screen: PublicScreen | None,
+    public_screen: PublicScreen,
+) -> bool:
+    if previous_screen is None:
+        return False
+
+    def structural_groups(
+        screen: PublicScreen,
+    ) -> tuple[tuple[tuple[object, ...], ...], ...]:
+        return (
+            _structural_node_signatures(public_group_nodes(screen, "targets")),
+            _structural_node_signatures(public_group_nodes(screen, "context")),
+            _structural_node_signatures(public_group_nodes(screen, "dialog")),
+        )
+
+    return structural_groups(previous_screen) != structural_groups(public_screen)
+
+
+def _structural_node_signatures(
+    nodes: tuple[PublicNode, ...],
+) -> tuple[tuple[object, ...], ...]:
+    return tuple(_structural_node_signature(node) for node in nodes)
+
+
+def _structural_node_signature(node: PublicNode) -> tuple[object, ...]:
+    return (
+        node.kind,
+        node.role,
+        node.label,
+        node.text,
+        tuple(_structural_node_signature(child) for child in node.children),
+        tuple(node.scroll_directions),
+        (
+            None
+            if node.meta is None
+            else (
+                node.meta.resource_id,
+                node.meta.class_name,
+            )
+        ),
+    )
+
+
+def validate_submit_confirmation(
+    *,
+    session: WorkspaceRuntime | None = None,
+    route_kind: Literal["direct", "attributed"],
+    action_result: ActionPerformResult,
+    previous_snapshot: RawSnapshot | None,
+    snapshot: RawSnapshot,
+    previous_screen: PublicScreen | None,
+    public_screen: PublicScreen,
+    context: SubmitConfirmationContext | None = None,
+    command_target_handle: NodeHandle | None,
+) -> SubmitConfirmationOutcome:
+    if command_target_handle is None:
+        raise DaemonError(
+            code=DaemonErrorCode.SUBMIT_NOT_CONFIRMED,
+            message="submit effect could not be confirmed",
+            retryable=True,
+            details={"reason": "missing_command_target_identity"},
+            http_status=200,
+        )
+    if action_result.status is not ActionStatus.DONE:
+        raise DaemonError(
+            code=DaemonErrorCode.SUBMIT_NOT_CONFIRMED,
+            message="submit effect could not be confirmed",
+            retryable=True,
+            details={
+                "reason": "device_submit_not_accepted",
+                "status": action_result.status.value,
+            },
+            http_status=200,
+        )
+    if previous_snapshot is not None and (
+        snapshot.package_name != previous_snapshot.package_name
+        or snapshot.activity_name != previous_snapshot.activity_name
+    ):
+        return SubmitConfirmationOutcome(
+            status="unconfirmed",
+            node=None,
+            target_handle=command_target_handle,
+        )
+    confirmation_node = submit_confirmation_node(
+        session=session,
+        snapshot=snapshot,
+        context=context,
+        command_target_handle=command_target_handle,
+    )
+    if confirmation_node is None:
+        return SubmitConfirmationOutcome(
+            status="targetGone",
+            node=None,
+            target_handle=command_target_handle,
+        )
+    if submit_public_change_is_attributable(
+        previous_screen,
+        public_screen,
+    ):
+        return SubmitConfirmationOutcome(
+            status="publicChange",
+            node=confirmation_node,
+            target_handle=command_target_handle,
+        )
+    if not confirmation_node.focused or not confirmation_node.editable:
+        if route_kind == "attributed":
+            raise DaemonError(
+                code=DaemonErrorCode.SUBMIT_NOT_CONFIRMED,
+                message="submit effect could not be confirmed",
+                retryable=True,
+                details={"reason": "attributed_submit_blur_only"},
+                http_status=200,
+            )
+        return SubmitConfirmationOutcome(
+            status="sameTarget",
+            node=confirmation_node,
+            target_handle=command_target_handle,
+        )
+    raise DaemonError(
+        code=DaemonErrorCode.SUBMIT_NOT_CONFIRMED,
+        message="submit effect could not be confirmed",
+        retryable=True,
+        details={"reason": "target_still_focused_editable"},
+        http_status=200,
+    )