androidctl 0.1.0__py3-none-any.whl

androidctld/device/types.py

@@ -0,0 +1,161 @@
+"""Shared device-facing types."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from androidctld.config import DEFAULT_HOST
+from androidctld.protocol import ConnectionMode
+from androidctld.refs.models import NodeHandle
+from androidctld.runtime_policy import DEFAULT_DEVICE_PORT
+
+
+@dataclass(frozen=True)
+class ConnectionConfig:
+    mode: ConnectionMode
+    token: str
+    serial: str | None = None
+    host: str | None = None
+    port: int = DEFAULT_DEVICE_PORT
+
+
+@dataclass(frozen=True)
+class ConnectionSpec:
+    mode: ConnectionMode
+    port: int = DEFAULT_DEVICE_PORT
+    serial: str | None = None
+    host: str | None = None
+
+    @classmethod
+    def from_config(cls, config: ConnectionConfig) -> ConnectionSpec:
+        if config.mode is ConnectionMode.ADB:
+            return cls(
+                mode=config.mode,
+                port=config.port,
+                serial=config.serial,
+                host=None,
+            )
+        return cls(
+            mode=config.mode,
+            port=config.port,
+            serial=config.serial,
+            host=config.host,
+        )
+
+    def to_connection_config(self, token: str) -> ConnectionConfig:
+        return ConnectionConfig(
+            mode=self.mode,
+            token=token,
+            serial=self.serial,
+            host=self.host,
+            port=self.port,
+        )
+
+
+@dataclass(frozen=True)
+class DeviceEndpoint:
+    host: str = DEFAULT_HOST
+    port: int = DEFAULT_DEVICE_PORT
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+
+@dataclass
+class DeviceCapabilities:
+    supports_events_poll: bool
+    supports_screenshot: bool
+    action_kinds: list[str] = field(default_factory=list)
+
+    def supports_action(self, action_kind: str) -> bool:
+        return action_kind in self.action_kinds
+
+
+@dataclass
+class MetaInfo:
+    service: str
+    version: str
+    capabilities: DeviceCapabilities
+
+
+class ActionStatus(str, Enum):
+    DONE = "done"
+    PARTIAL = "partial"
+    TIMEOUT = "timeout"
+
+
+@dataclass(frozen=True)
+class ObservedApp:
+    package_name: str | None = None
+    activity_name: str | None = None
+
+
+@dataclass(frozen=True)
+class ResolvedHandleTarget:
+    handle: NodeHandle
+    kind: str = "handle"
+
+
+@dataclass(frozen=True)
+class ResolvedCoordinatesTarget:
+    x: float
+    y: float
+    kind: str = "coordinates"
+
+
+@dataclass(frozen=True)
+class ResolvedNoneTarget:
+    kind: str = "none"
+
+
+ResolvedTarget = ResolvedHandleTarget | ResolvedCoordinatesTarget | ResolvedNoneTarget
+
+
+@dataclass(frozen=True)
+class ActionPerformResult:
+    action_id: str
+    status: ActionStatus
+    duration_ms: int | None = None
+    resolved_target: ResolvedTarget | None = None
+    observed: ObservedApp | None = None
+
+
+@dataclass(frozen=True)
+class DeviceEvent:
+    seq: int
+    type: str
+    timestamp: str
+    data: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class EventsPollResult:
+    events: tuple[DeviceEvent, ...]
+    latest_seq: int
+    need_resync: bool
+    timed_out: bool
+
+
+@dataclass(frozen=True)
+class ScreenshotCaptureResult:
+    content_type: str
+    width_px: int
+    height_px: int
+    body_base64: str
+
+
+@dataclass
+class RuntimeTransport:
+    endpoint: DeviceEndpoint
+    close: Callable[[], None]
+
+
+@dataclass
+class BootstrapResult:
+    connection: ConnectionSpec
+    transport: RuntimeTransport
+    meta: MetaInfo

androidctld/errors/__init__.py

@@ -0,0 +1,94 @@
+"""Error models and helpers for androidctld."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from androidctl_contracts.errors import (
+    DaemonError as ContractDaemonError,
+)
+from androidctl_contracts.errors import DaemonErrorCode as ContractDaemonErrorCode
+
+
+class DaemonErrorCode(str, Enum):
+    DAEMON_BAD_REQUEST = "DAEMON_BAD_REQUEST"
+    DAEMON_UNAUTHORIZED = "DAEMON_UNAUTHORIZED"
+    WORKSPACE_BUSY = "WORKSPACE_BUSY"
+    RUNTIME_BUSY = "RUNTIME_BUSY"
+    RUNTIME_NOT_CONNECTED = "RUNTIME_NOT_CONNECTED"
+    SCREEN_NOT_READY = "SCREEN_NOT_READY"
+    COMMAND_NOT_FOUND = "COMMAND_NOT_FOUND"
+    COMMAND_CANCELLED = "COMMAND_CANCELLED"
+    REF_RESOLUTION_FAILED = "REF_RESOLUTION_FAILED"
+    REF_STALE = "REF_STALE"
+    TARGET_BLOCKED = "TARGET_BLOCKED"
+    TARGET_NOT_ACTIONABLE = "TARGET_NOT_ACTIONABLE"
+    WAIT_TIMEOUT = "WAIT_TIMEOUT"
+    DEVICE_RPC_FAILED = "DEVICE_RPC_FAILED"
+    DEVICE_DISCONNECTED = "DEVICE_DISCONNECTED"
+    DEVICE_AGENT_UNAVAILABLE = "DEVICE_AGENT_UNAVAILABLE"
+    DEVICE_AGENT_UNAUTHORIZED = "DEVICE_AGENT_UNAUTHORIZED"
+    DEVICE_AGENT_VERSION_MISMATCH = "DEVICE_AGENT_VERSION_MISMATCH"
+    DEVICE_AGENT_CAPABILITY_MISMATCH = "DEVICE_AGENT_CAPABILITY_MISMATCH"
+    ACCESSIBILITY_NOT_READY = "ACCESSIBILITY_NOT_READY"
+    OPEN_FAILED = "OPEN_FAILED"
+    ACTION_NOT_CONFIRMED = "ACTION_NOT_CONFIRMED"
+    TYPE_NOT_CONFIRMED = "TYPE_NOT_CONFIRMED"
+    SUBMIT_NOT_CONFIRMED = "SUBMIT_NOT_CONFIRMED"
+    DEVICE_RPC_TRANSPORT_RESET = "DEVICE_RPC_TRANSPORT_RESET"
+    INTERNAL_COMMAND_FAILURE = "INTERNAL_COMMAND_FAILURE"
+    WORKSPACE_UNAVAILABLE = "WORKSPACE_UNAVAILABLE"
+    ARTIFACT_ROOT_UNWRITABLE = "ARTIFACT_ROOT_UNWRITABLE"
+    ARTIFACT_WRITE_FAILED = "ARTIFACT_WRITE_FAILED"
+
+
+_WIRE_CODE_BY_VALUE = {code.value: code for code in ContractDaemonErrorCode}
+
+
+@dataclass
+class DaemonError(Exception):
+    code: DaemonErrorCode
+    message: str
+    retryable: bool = False
+    details: dict[str, Any] = field(default_factory=dict)
+    http_status: int = 200
+
+    def __post_init__(self) -> None:
+        self.code = DaemonErrorCode(self.code)
+
+    def to_contract_error(self) -> ContractDaemonError:
+        return ContractDaemonError(
+            code=_to_contract_code(self.code),
+            message=self.message,
+            retryable=self.retryable,
+            details=dict(self.details),
+        )
+
+
+def bad_request(message: str, details: dict[str, Any] | None = None) -> DaemonError:
+    return DaemonError(
+        code=DaemonErrorCode.DAEMON_BAD_REQUEST,
+        message=message,
+        retryable=False,
+        details=details or {},
+        http_status=400,
+    )
+
+
+def unauthorized(message: str = "missing or invalid daemon token") -> DaemonError:
+    return DaemonError(
+        code=DaemonErrorCode.DAEMON_UNAUTHORIZED,
+        message=message,
+        retryable=False,
+        details={},
+        http_status=401,
+    )
+
+
+def _to_contract_code(code: DaemonErrorCode) -> ContractDaemonErrorCode:
+    try:
+        return _WIRE_CODE_BY_VALUE[code.value]
+    except KeyError as error:
+        raise ValueError(f"{code.value} is not legal in DaemonErrorEnvelope") from error

androidctld/logging/__init__.py

@@ -0,0 +1,22 @@
+"""Logging configuration for androidctld."""
+
+from __future__ import annotations
+
+import logging
+
+LOGGER_NAME = "androidctld"
+
+
+def configure_logging(level: int = logging.INFO) -> logging.Logger:
+    logger = logging.getLogger(LOGGER_NAME)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            fmt="%(asctime)s %(levelname)s %(name)s %(message)s",
+            datefmt="%Y-%m-%dT%H:%M:%S",
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    logger.setLevel(level)
+    logger.propagate = False
+    return logger

androidctld/observation.py

@@ -0,0 +1,98 @@
+"""Shared observation-loop timing and cursor bookkeeping."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from androidctld.device.types import EventsPollResult
+
+
+@dataclass(frozen=True)
+class ObservationPolicy:
+    min_grace_ms: int
+    snapshot_max_interval_ms: int
+    stable_window_ms: int
+    max_total_ms: int
+    poll_slice_ms: int
+
+
+@dataclass(frozen=True)
+class ObservationPollOutcome:
+    saw_events: bool
+    need_resync: bool
+    latest_seq: int
+
+
+@dataclass
+class ObservationLoop:
+    policy: ObservationPolicy
+    started_at: float
+    after_seq: int = 0
+    last_refresh_at: float | None = None
+    stable_since: float | None = None
+
+    @classmethod
+    def begin(cls, policy: ObservationPolicy, started_at: float) -> ObservationLoop:
+        return cls(policy=policy, started_at=started_at)
+
+    @property
+    def grace_deadline_at(self) -> float:
+        return self.started_at + (self.policy.min_grace_ms / 1000.0)
+
+    @property
+    def deadline_at(self) -> float:
+        return self.started_at + (self.policy.max_total_ms / 1000.0)
+
+    def timed_out(self, now: float) -> bool:
+        return now >= self.deadline_at
+
+    def remaining_ms(self, now: float) -> int:
+        return max(int((self.deadline_at - now) * 1000), 0)
+
+    def poll_wait_ms(self, now: float) -> int:
+        return min(self.policy.poll_slice_ms, self.remaining_ms(now))
+
+    def grace_elapsed(self, now: float) -> bool:
+        return now >= self.grace_deadline_at
+
+    def apply_poll_result(self, result: EventsPollResult) -> ObservationPollOutcome:
+        saw_events = bool(result.events)
+        need_resync = bool(result.need_resync)
+        latest_seq = int(result.latest_seq)
+        if need_resync:
+            self.after_seq = 0
+            self.stable_since = None
+            self.last_refresh_at = None
+        else:
+            self.after_seq = latest_seq
+        return ObservationPollOutcome(
+            saw_events=saw_events,
+            need_resync=need_resync,
+            latest_seq=latest_seq,
+        )
+
+    def should_refresh(
+        self, now: float, *, saw_events: bool, need_resync: bool
+    ) -> bool:
+        if need_resync:
+            return True
+        if self.last_refresh_at is None:
+            return True
+        if saw_events:
+            return True
+        return (
+            now - self.last_refresh_at
+        ) * 1000 >= self.policy.snapshot_max_interval_ms
+
+    def mark_refreshed(self, now: float) -> None:
+        self.last_refresh_at = now
+
+    def observe_stability(self, now: float, *, changed: bool) -> bool:
+        if changed:
+            self.stable_since = None
+            return False
+        if self.stable_since is None:
+            self.stable_since = now
+        if not self.grace_elapsed(now):
+            return False
+        return (now - self.stable_since) * 1000 >= self.policy.stable_window_ms

androidctld/protocol.py

@@ -0,0 +1,53 @@
+"""Centralized protocol enums for androidctld runtime."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class RuntimeStatus(str, Enum):
+    NEW = "new"
+    BOOTSTRAPPING = "bootstrapping"
+    CONNECTED = "connected"
+    READY = "ready"
+    BROKEN = "broken"
+    CLOSED = "closed"
+
+
+class ConnectionMode(str, Enum):
+    ADB = "adb"
+    LAN = "lan"
+
+
+class CommandKind(str, Enum):
+    CONNECT = "connect"
+    OBSERVE = "observe"
+    LIST_APPS = "listApps"
+    OPEN = "open"
+    TAP = "tap"
+    LONG_TAP = "longTap"
+    TYPE = "type"
+    FOCUS = "focus"
+    SUBMIT = "submit"
+    SCROLL = "scroll"
+    GLOBAL = "global"
+    WAIT = "wait"
+    SCREENSHOT = "screenshot"
+    CLOSE = "close"
+
+
+class DeviceRpcMethod(str, Enum):
+    META_GET = "meta.get"
+    SNAPSHOT_GET = "snapshot.get"
+    EVENTS_POLL = "events.poll"
+    ACTION_PERFORM = "action.perform"
+    SCREENSHOT_CAPTURE = "screenshot.capture"
+
+
+class DeviceRpcErrorCode(str, Enum):
+    STALE_TARGET = "STALE_TARGET"
+    TARGET_NOT_ACTIONABLE = "TARGET_NOT_ACTIONABLE"
+    ACTION_FAILED = "ACTION_FAILED"
+    ACTION_TIMEOUT = "ACTION_TIMEOUT"
+    RUNTIME_NOT_READY = "RUNTIME_NOT_READY"
+    ACCESSIBILITY_DISABLED = "ACCESSIBILITY_DISABLED"

androidctld/refs/__init__.py

@@ -0,0 +1 @@
+"""Ref helpers for semantic targets."""

androidctld/refs/models.py

@@ -0,0 +1,54 @@
+"""Runtime ref registry models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class RefFingerprint:
+    role: str
+    normalized_label: str
+    resource_id: str
+    class_name: str
+    parent_role: str
+    parent_label: str
+    sibling_labels: tuple[str, ...]
+    relative_bounds: tuple[int, int, int, int]
+
+
+@dataclass(frozen=True)
+class NodeHandle:
+    snapshot_id: int
+    rid: str
+
+
+@dataclass(frozen=True)
+class SemanticProfile:
+    state: tuple[str, ...]
+    actions: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class RefRepairSourceSignature:
+    ref: str
+    fingerprint: RefFingerprint
+    state: tuple[str, ...]
+    actions: tuple[str, ...]
+
+
+@dataclass
+class RefBinding:
+    ref: str
+    handle: NodeHandle
+    fingerprint: RefFingerprint
+    semantic_profile: SemanticProfile
+    reused: bool = False
+
+
+@dataclass
+class RefRegistry:
+    bindings: dict[str, RefBinding] = field(default_factory=dict)
+
+    def get(self, ref: str) -> RefBinding | None:
+        return self.bindings.get(ref)