androidctl 0.1.0__py3-none-any.whl

androidctld/actions/submit_routing.py

@@ -0,0 +1,311 @@
+"""Submit-only route admission for direct and attributed dispatch."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from androidctl_contracts.command_results import ActionTargetEvidence
+from androidctld.actions.focused_input_admissibility import (
+    keyboard_blocker_allows_submit_subject,
+    public_focused_input_ref,
+    public_node_is_focused_input,
+)
+from androidctld.commands.command_models import SubmitCommand
+from androidctld.errors import DaemonError, DaemonErrorCode
+from androidctld.refs.models import NodeHandle
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime.screen_state import (
+    current_compiled_screen,
+    current_public_screen,
+)
+from androidctld.semantics.compiler import CompiledScreen, SemanticNode
+from androidctld.semantics.public_models import (
+    PublicNode,
+    PublicScreen,
+    iter_public_nodes,
+)
+
+SubmitRouteKind = Literal["direct", "attributed"]
+SubmitRouteFailureCode = Literal["TARGET_NOT_ACTIONABLE", "TARGET_BLOCKED"]
+
+
+@dataclass(frozen=True)
+class SubmitRouteOutcome:
+    route: SubmitRouteKind
+    source_ref: str
+    source_screen_id: str
+    source_evidence: ActionTargetEvidence
+    route_screen_id: str
+    subject_ref: str
+    subject_handle: NodeHandle
+    dispatched_ref: str
+    dispatched_handle: NodeHandle
+
+
+@dataclass(frozen=True)
+class SubmitRouteFailure:
+    code: SubmitRouteFailureCode
+    reason: str
+    ref: str | None
+    action: str | None = None
+    blocking_group: str | None = None
+    focused_input_ref: str | None = None
+
+    def to_error(self) -> DaemonError:
+        details: dict[str, object] = {"reason": self.reason, "ref": self.ref}
+        if self.action is not None:
+            details["action"] = self.action
+        if self.blocking_group is not None:
+            details["blockingGroup"] = self.blocking_group
+        if self.focused_input_ref is not None:
+            details["focusedInputRef"] = self.focused_input_ref
+        if self.code == "TARGET_BLOCKED":
+            return DaemonError(
+                code=DaemonErrorCode.TARGET_BLOCKED,
+                message="target is blocked on the current screen",
+                retryable=False,
+                details=details,
+                http_status=200,
+            )
+        return DaemonError(
+            code=DaemonErrorCode.TARGET_NOT_ACTIONABLE,
+            message="submit is not available for the requested target",
+            retryable=False,
+            details=details,
+            http_status=200,
+        )
+
+
+def resolve_submit_route(
+    session: WorkspaceRuntime,
+    command: SubmitCommand,
+    *,
+    subject_handle: NodeHandle | None,
+    source_evidence: ActionTargetEvidence,
+) -> SubmitRouteOutcome:
+    screen = current_public_screen(session)
+    compiled_screen = current_compiled_screen(session)
+    if (
+        screen is None
+        or compiled_screen is None
+        or session.latest_snapshot is None
+        or subject_handle is None
+    ):
+        raise _failure(
+            "submit_route_unresolved_subject",
+            ref=command.ref,
+        ).to_error()
+    if screen.screen_id != compiled_screen.screen_id:
+        raise _failure(
+            "submit_route_basis_mismatch",
+            ref=command.ref,
+        ).to_error()
+    if subject_handle.snapshot_id != session.latest_snapshot.snapshot_id:
+        raise _failure(
+            "submit_route_stale_subject_handle",
+            ref=command.ref,
+        ).to_error()
+
+    subject_node = _semantic_node_for_handle(compiled_screen, subject_handle)
+    subject_ref = None if subject_node is None else subject_node.ref
+    if subject_node is None or subject_ref is None:
+        raise _failure(
+            "submit_route_unresolved_subject",
+            ref=command.ref,
+        ).to_error()
+    subject_public = _unique_public_node(screen, subject_ref)
+    if subject_public is None:
+        raise _failure(
+            "submit_route_unresolved_subject",
+            ref=subject_ref,
+        ).to_error()
+    _ensure_subject_admissible(screen, compiled_screen, subject_node, subject_public)
+
+    submit_refs = subject_public.submit_refs
+    if len(submit_refs) > 1:
+        raise _failure(
+            "submit_route_ambiguous",
+            ref=subject_ref,
+            action="submit",
+        ).to_error()
+    if len(submit_refs) == 1:
+        dispatched_ref = submit_refs[0]
+        dispatched_public = _unique_public_node(screen, dispatched_ref)
+        dispatched_node = _unique_semantic_node_for_ref(compiled_screen, dispatched_ref)
+        if dispatched_public is None or dispatched_node is None:
+            raise _failure(
+                "submit_route_unresolved_target",
+                ref=dispatched_ref,
+                action="tap",
+            ).to_error()
+        _ensure_unblocked(screen, dispatched_node, ref=dispatched_ref)
+        if (
+            "tap" not in dispatched_public.actions
+            or "tap" not in dispatched_node.actions
+        ):
+            raise _failure(
+                "submit_route_target_not_tap_capable",
+                ref=dispatched_ref,
+                action="tap",
+            ).to_error()
+
+        return SubmitRouteOutcome(
+            route="attributed",
+            source_ref=command.ref,
+            source_screen_id=command.source_screen_id,
+            source_evidence=source_evidence,
+            route_screen_id=screen.screen_id,
+            subject_ref=subject_ref,
+            subject_handle=_current_handle(session, subject_node),
+            dispatched_ref=dispatched_ref,
+            dispatched_handle=_current_handle(session, dispatched_node),
+        )
+
+    if "submit" not in subject_public.actions:
+        raise _failure(
+            "submit_route_missing",
+            ref=subject_ref,
+            action="submit",
+        ).to_error()
+
+    return SubmitRouteOutcome(
+        route="direct",
+        source_ref=command.ref,
+        source_screen_id=command.source_screen_id,
+        source_evidence=source_evidence,
+        route_screen_id=screen.screen_id,
+        subject_ref=subject_ref,
+        subject_handle=_current_handle(session, subject_node),
+        dispatched_ref=subject_ref,
+        dispatched_handle=_current_handle(session, subject_node),
+    )
+
+
+def _ensure_subject_admissible(
+    screen: PublicScreen,
+    compiled_screen: CompiledScreen,
+    subject_node: SemanticNode,
+    subject_public: PublicNode,
+) -> None:
+    _ensure_subject_unblocked(screen, compiled_screen, subject_node, subject_public)
+    if subject_public.role != "input" or subject_node.role != "input":
+        raise _failure(
+            "not_input_capable",
+            ref=subject_public.ref,
+            action="submit",
+        ).to_error()
+    if not public_node_is_focused_input(screen, subject_public):
+        raise _failure(
+            "focus_mismatch",
+            ref=subject_public.ref,
+            focused_input_ref=public_focused_input_ref(screen),
+        ).to_error()
+
+
+def _ensure_subject_unblocked(
+    screen: PublicScreen,
+    compiled_screen: CompiledScreen,
+    subject_node: SemanticNode,
+    subject_public: PublicNode,
+) -> None:
+    blocking_group = screen.surface.blocking_group
+    if blocking_group is None or subject_node.group == blocking_group:
+        return
+    if keyboard_blocker_allows_submit_subject(
+        blocking_group=blocking_group,
+        public_screen=screen,
+        compiled_screen=compiled_screen,
+        public_node=subject_public,
+        semantic_node=subject_node,
+    ):
+        return
+    raise _failure(
+        f"blocked_by_{blocking_group}",
+        code="TARGET_BLOCKED",
+        ref=subject_public.ref,
+        blocking_group=blocking_group,
+    ).to_error()
+
+
+def _ensure_unblocked(
+    screen: PublicScreen,
+    node: SemanticNode,
+    *,
+    ref: str | None,
+) -> None:
+    blocking_group = screen.surface.blocking_group
+    if blocking_group is None or node.group == blocking_group:
+        return
+    raise _failure(
+        f"blocked_by_{blocking_group}",
+        code="TARGET_BLOCKED",
+        ref=ref,
+        blocking_group=blocking_group,
+    ).to_error()
+
+
+def _failure(
+    reason: str,
+    *,
+    ref: str | None,
+    code: SubmitRouteFailureCode = "TARGET_NOT_ACTIONABLE",
+    action: str | None = None,
+    blocking_group: str | None = None,
+    focused_input_ref: str | None = None,
+) -> SubmitRouteFailure:
+    return SubmitRouteFailure(
+        code=code,
+        reason=reason,
+        ref=ref,
+        action=action,
+        blocking_group=blocking_group,
+        focused_input_ref=focused_input_ref,
+    )
+
+
+def _semantic_node_for_handle(
+    screen: CompiledScreen,
+    handle: NodeHandle,
+) -> SemanticNode | None:
+    for node in _compiled_nodes(screen):
+        if node.raw_rid == handle.rid:
+            return node
+    return None
+
+
+def _current_handle(session: WorkspaceRuntime, node: SemanticNode) -> NodeHandle:
+    if session.latest_snapshot is None:
+        raise DaemonError(
+            code=DaemonErrorCode.SCREEN_NOT_READY,
+            message="screen is not ready yet",
+        )
+    return NodeHandle(snapshot_id=session.latest_snapshot.snapshot_id, rid=node.raw_rid)
+
+
+def _unique_semantic_node_for_ref(
+    screen: CompiledScreen,
+    ref: str,
+) -> SemanticNode | None:
+    nodes = [node for node in _compiled_nodes(screen) if node.ref == ref]
+    return nodes[0] if len(nodes) == 1 else None
+
+
+def _unique_public_node(screen: PublicScreen, ref: str) -> PublicNode | None:
+    nodes = [
+        node
+        for group in screen.groups
+        for node in iter_public_nodes(group.nodes)
+        if node.ref == ref
+    ]
+    return nodes[0] if len(nodes) == 1 else None
+
+
+def _compiled_nodes(screen: CompiledScreen) -> tuple[SemanticNode, ...]:
+    return (
+        *screen.targets,
+        *screen.context,
+        *screen.dialog,
+        *screen.keyboard,
+        *screen.system,
+    )

androidctld/actions/type_confirmation.py

@@ -0,0 +1,257 @@
+"""Type confirmation helpers for post-action validation."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+from androidctld.commands.command_models import TypeCommand
+from androidctld.device.types import (
+    ActionPerformResult,
+    ResolvedHandleTarget,
+    ResolvedTarget,
+)
+from androidctld.errors import DaemonError, DaemonErrorCode
+from androidctld.refs.models import NodeHandle, RefBinding
+from androidctld.refs.service import best_candidate_for_binding
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.semantics.compiler import CompiledScreen, SemanticNode
+from androidctld.snapshots.models import RawNode, RawSnapshot
+from androidctld.text_equivalence import (
+    canonical_text_key,
+)
+
+
+@dataclass(frozen=True)
+class TypeConfirmationContext:
+    ref: str | None
+    request_handle: NodeHandle | None
+    binding: RefBinding | None
+
+
+@dataclass(frozen=True)
+class TypeConfirmationCandidate:
+    strategy: str
+    node: RawNode | None
+    target_handle: NodeHandle | None
+
+
+def validate_type_confirmation(
+    session: WorkspaceRuntime,
+    command: TypeCommand,
+    snapshot: RawSnapshot,
+    context: TypeConfirmationContext,
+    action_result: ActionPerformResult,
+) -> TypeConfirmationCandidate:
+    candidates = type_confirmation_candidates(
+        session,
+        snapshot,
+        context,
+        action_result,
+    )
+    for candidate in candidates:
+        if candidate.node is None:
+            raise RuntimeError("type confirmation candidate is missing node")
+        if matches_typed_value(command, observed_input_value(candidate.node)):
+            return candidate
+    raise DaemonError(
+        code=DaemonErrorCode.TYPE_NOT_CONFIRMED,
+        message="typed text was not confirmed on the refreshed screen",
+        retryable=True,
+        details=type_confirmation_error_details(command, context, candidates),
+        http_status=200,
+    )
+
+
+def build_type_confirmation_context(
+    session: WorkspaceRuntime,
+    command: TypeCommand,
+    request_handle: NodeHandle | None,
+) -> TypeConfirmationContext:
+    binding = session.ref_registry.get(command.ref)
+    return TypeConfirmationContext(
+        ref=command.ref,
+        request_handle=request_handle,
+        binding=None if binding is None else deepcopy(binding),
+    )
+
+
+def type_confirmation_candidates(
+    session: WorkspaceRuntime,
+    snapshot: RawSnapshot,
+    context: TypeConfirmationContext,
+    action_result: ActionPerformResult,
+) -> list[TypeConfirmationCandidate]:
+    candidate_nodes: list[TypeConfirmationCandidate] = []
+    seen_rids: set[str] = set()
+
+    def add_candidate(
+        strategy: str,
+        node: RawNode | None,
+        target_handle: NodeHandle | None,
+    ) -> None:
+        if node is None or node.rid in seen_rids:
+            return
+        seen_rids.add(node.rid)
+        candidate_nodes.append(
+            TypeConfirmationCandidate(
+                strategy=strategy,
+                node=node,
+                target_handle=target_handle,
+            )
+        )
+
+    resolved_handle = action_result_target_handle(action_result)
+    add_candidate(
+        "resolvedTarget",
+        snapshot_node_for_handle(snapshot, resolved_handle),
+        resolved_handle,
+    )
+    add_candidate(
+        "requestTarget",
+        snapshot_node_for_handle(snapshot, context.request_handle),
+        context.request_handle,
+    )
+    reused_node = reused_ref_confirmation_node(session, snapshot, context)
+    add_candidate("reusedRef", reused_node, _snapshot_handle(snapshot, reused_node))
+    rematch_node = fingerprint_rematch_confirmation_node(session, snapshot, context)
+    add_candidate(
+        "fingerprintRematch",
+        rematch_node,
+        _snapshot_handle(snapshot, rematch_node),
+    )
+    return candidate_nodes
+
+
+def action_result_target_handle(
+    action_result: ActionPerformResult,
+) -> NodeHandle | None:
+    resolved_target = action_result.resolved_target
+    if resolved_target is None:
+        return None
+    return resolved_target_handle(resolved_target)
+
+
+def resolved_target_handle(target: ResolvedTarget) -> NodeHandle | None:
+    if not isinstance(target, ResolvedHandleTarget):
+        return None
+    return target.handle
+
+
+def snapshot_node_for_handle(
+    snapshot: RawSnapshot, handle: NodeHandle | None
+) -> RawNode | None:
+    if handle is None:
+        return None
+    for node in snapshot.nodes:
+        if node.rid == handle.rid:
+            return node
+    return None
+
+
+def _snapshot_handle(snapshot: RawSnapshot, node: RawNode | None) -> NodeHandle | None:
+    if node is None:
+        return None
+    return NodeHandle(snapshot_id=snapshot.snapshot_id, rid=node.rid)
+
+
+def is_type_confirmation_candidate(node: RawNode) -> bool:
+    return bool(node.visible_to_user and node.editable)
+
+
+def observed_input_value(node: RawNode) -> str:
+    if node.text is None:
+        return ""
+    return str(node.text)
+
+
+def matches_typed_value(command: TypeCommand, actual_value: str) -> bool:
+    return canonical_text_key(actual_value) == canonical_text_key(command.text)
+
+
+def reused_ref_confirmation_node(
+    session: WorkspaceRuntime,
+    snapshot: RawSnapshot,
+    context: TypeConfirmationContext,
+) -> RawNode | None:
+    if context.ref is None:
+        return None
+    binding = session.ref_registry.get(context.ref)
+    if binding is None or not binding.reused:
+        return None
+    node = snapshot_node_for_handle(snapshot, binding.handle)
+    if node is None or not is_type_confirmation_candidate(node):
+        return None
+    return node
+
+
+def fingerprint_rematch_confirmation_node(
+    session: WorkspaceRuntime,
+    snapshot: RawSnapshot,
+    context: TypeConfirmationContext,
+) -> RawNode | None:
+    if context.binding is None or session.screen_state is None:
+        return None
+    compiled_screen = session.screen_state.compiled_screen
+    if compiled_screen is None:
+        return None
+    match = best_candidate_for_binding(
+        context.binding,
+        type_confirmation_semantic_candidates(compiled_screen, snapshot),
+    )
+    if match is None:
+        return None
+    candidate, _ = match
+    return snapshot_node_for_rid(snapshot, candidate.raw_rid)
+
+
+def type_confirmation_semantic_candidates(
+    compiled_screen: CompiledScreen,
+    snapshot: RawSnapshot,
+) -> list[SemanticNode]:
+    nodes_by_rid = {node.rid: node for node in snapshot.nodes}
+    candidates = []
+    for semantic_node in compiled_screen_nodes(compiled_screen):
+        raw_node = nodes_by_rid.get(semantic_node.raw_rid)
+        if raw_node is None or not is_type_confirmation_candidate(raw_node):
+            continue
+        candidates.append(semantic_node)
+    return candidates
+
+
+def snapshot_node_for_rid(snapshot: RawSnapshot, rid: str) -> RawNode | None:
+    for node in snapshot.nodes:
+        if node.rid == rid:
+            return node
+    return None
+
+
+def type_confirmation_error_details(
+    command: TypeCommand,
+    context: TypeConfirmationContext,
+    candidates: list[TypeConfirmationCandidate],
+) -> dict[str, Any]:
+    return {
+        "ref": context.ref,
+        "text": command.text,
+        "replace": True,
+        "candidateCount": len(candidates),
+        "confirmationStrategy": (
+            "resolvedTarget>requestTarget>reusedRef>" + "fingerprintRematch"
+        ),
+        "candidateRids": [
+            None if candidate.node is None else candidate.node.rid
+            for candidate in candidates
+        ],
+    }
+
+
+def compiled_screen_nodes(compiled_screen: CompiledScreen) -> tuple[SemanticNode, ...]:
+    return (
+        *compiled_screen.targets,
+        *compiled_screen.context,
+        *compiled_screen.dialog,
+        *compiled_screen.keyboard,
+        *compiled_screen.system,
+    )

androidctld/app_targets.py

@@ -0,0 +1,71 @@
+"""Shared app-target matching for open/wait surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from androidctld.errors import DaemonError, DaemonErrorCode
+
+
+@dataclass(frozen=True)
+class AppTargetMatch:
+    requested_package_name: str
+    resolved_package_name: str
+    match_type: Literal["exact", "alias"]
+
+
+APP_TARGET_ALIASES: frozenset[tuple[str, str]] = frozenset(
+    {
+        ("com.android.settings", "com.android.settings.intelligence"),
+        ("com.android.settings", "com.google.android.settings.intelligence"),
+        (
+            "com.android.settings.intelligence",
+            "com.google.android.settings.intelligence",
+        ),
+        (
+            "com.google.android.settings.intelligence",
+            "com.android.settings.intelligence",
+        ),
+    }
+)
+
+
+def match_app_target(
+    requested_package_name: str,
+    actual_package_name: str | None,
+) -> AppTargetMatch | None:
+    if actual_package_name is None:
+        return None
+    if actual_package_name == requested_package_name:
+        return AppTargetMatch(
+            requested_package_name=requested_package_name,
+            resolved_package_name=actual_package_name,
+            match_type="exact",
+        )
+    if (requested_package_name, actual_package_name) in APP_TARGET_ALIASES:
+        return AppTargetMatch(
+            requested_package_name=requested_package_name,
+            resolved_package_name=actual_package_name,
+            match_type="alias",
+        )
+    return None
+
+
+def require_app_target_match(
+    requested_package_name: str,
+    actual_package_name: str | None,
+) -> AppTargetMatch:
+    match = match_app_target(requested_package_name, actual_package_name)
+    if match is not None:
+        return match
+    raise DaemonError(
+        code=DaemonErrorCode.OPEN_FAILED,
+        message="open did not reach the requested application",
+        retryable=True,
+        details={
+            "expectedPackageName": requested_package_name,
+            "actualPackageName": actual_package_name,
+        },
+        http_status=200,
+    )

androidctld/artifacts/__init__.py

@@ -0,0 +1 @@
+"""Artifact writers for androidctld."""

androidctld/artifacts/models.py

@@ -0,0 +1,26 @@
+"""Typed artifact models."""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict
+
+from androidctld.schema import ApiModel
+
+
+class ScreenArtifacts(ApiModel):
+    model_config = ConfigDict(
+        strict=True,
+        extra="forbid",
+        alias_generator=ApiModel.model_config["alias_generator"],
+        validate_by_alias=True,
+        validate_by_name=True,
+        use_enum_values=False,
+        frozen=True,
+    )
+
+    screen_json: str | None = None
+    screen_xml: str | None = None
+    screenshot_png: str | None = None
+
+    def with_screenshot(self, screenshot_png: str) -> ScreenArtifacts:
+        return self.model_copy(update={"screenshot_png": screenshot_png})