androidctl 0.1.0__py3-none-any.whl

androidctld/commands/semantic_error_mapping.py

@@ -0,0 +1,93 @@
+"""Central semantic error mapping for semantic command results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from androidctl_contracts.vocabulary import SemanticResultCode
+from androidctld.errors import DaemonError, DaemonErrorCode
+
+_DIRECT_SEMANTIC_CODES: dict[DaemonErrorCode, SemanticResultCode] = {
+    DaemonErrorCode.REF_STALE: SemanticResultCode.REF_STALE,
+    DaemonErrorCode.WAIT_TIMEOUT: SemanticResultCode.WAIT_TIMEOUT,
+    DaemonErrorCode.TARGET_BLOCKED: SemanticResultCode.TARGET_BLOCKED,
+    DaemonErrorCode.TARGET_NOT_ACTIONABLE: SemanticResultCode.TARGET_NOT_ACTIONABLE,
+    DaemonErrorCode.OPEN_FAILED: SemanticResultCode.OPEN_FAILED,
+    DaemonErrorCode.ACTION_NOT_CONFIRMED: SemanticResultCode.ACTION_NOT_CONFIRMED,
+    DaemonErrorCode.TYPE_NOT_CONFIRMED: SemanticResultCode.TYPE_NOT_CONFIRMED,
+    DaemonErrorCode.SUBMIT_NOT_CONFIRMED: SemanticResultCode.SUBMIT_NOT_CONFIRMED,
+}
+
+_DEVICE_UNAVAILABLE_CODES = {
+    DaemonErrorCode.RUNTIME_NOT_CONNECTED,
+    DaemonErrorCode.SCREEN_NOT_READY,
+    DaemonErrorCode.DEVICE_DISCONNECTED,
+    DaemonErrorCode.DEVICE_AGENT_UNAVAILABLE,
+    DaemonErrorCode.DEVICE_AGENT_UNAUTHORIZED,
+    DaemonErrorCode.DEVICE_RPC_FAILED,
+    DaemonErrorCode.DEVICE_RPC_TRANSPORT_RESET,
+}
+
+_MUTATING_COMMANDS = {
+    "open",
+    "tap",
+    "longTap",
+    "long-tap",
+    "focus",
+    "type",
+    "submit",
+    "scroll",
+    "back",
+    "home",
+    "recents",
+    "notifications",
+}
+
+_REF_STALE_PUBLIC_MESSAGE = (
+    "The referenced element is no longer available on the current screen."
+)
+
+
+@dataclass(frozen=True)
+class SemanticFailure:
+    code: SemanticResultCode
+    message: str
+    continuity_status_override: str | None = None
+
+
+def map_daemon_error_to_semantic_failure(
+    *,
+    command_name: str,
+    error: DaemonError,
+    truth_lost_after_dispatch: bool = False,
+) -> SemanticFailure | None:
+    if error.code == DaemonErrorCode.REF_STALE:
+        return SemanticFailure(
+            code=SemanticResultCode.REF_STALE,
+            message=_REF_STALE_PUBLIC_MESSAGE,
+            continuity_status_override="stale",
+        )
+
+    direct_code = _DIRECT_SEMANTIC_CODES.get(error.code)
+    if direct_code is not None:
+        return SemanticFailure(code=direct_code, message=error.message)
+
+    if error.code not in _DEVICE_UNAVAILABLE_CODES:
+        return None
+
+    if command_name in _MUTATING_COMMANDS and truth_lost_after_dispatch:
+        return SemanticFailure(
+            code=SemanticResultCode.POST_ACTION_OBSERVATION_LOST,
+            message=(
+                "Action may have been dispatched, but no current screen truth is "
+                "available."
+            ),
+        )
+
+    return SemanticFailure(
+        code=SemanticResultCode.DEVICE_UNAVAILABLE,
+        message="No current device observation is available.",
+    )
+
+
+__all__ = ["SemanticFailure", "map_daemon_error_to_semantic_failure"]

androidctld/commands/semantic_truth.py

@@ -0,0 +1,135 @@
+"""Shared semantic continuity truth helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime.screen_state import (
+    get_authoritative_current_basis,
+)
+from androidctld.semantics.compiler import CompiledScreen
+from androidctld.semantics.continuity import evaluate_continuity
+from androidctld.semantics.public_models import PublicScreen
+
+
+@dataclass(frozen=True)
+class SemanticContinuityTruth:
+    continuity_status: str
+    changed: bool | None
+
+
+@dataclass(frozen=True)
+class SemanticSourceBasis:
+    source_screen_id: str | None
+    source_compiled_screen: CompiledScreen | None
+
+
+def capture_runtime_source_basis(
+    *,
+    runtime: WorkspaceRuntime,
+) -> SemanticSourceBasis:
+    basis = get_authoritative_current_basis(runtime)
+    return SemanticSourceBasis(
+        source_screen_id=(None if basis is None else basis.screen_id),
+        source_compiled_screen=(None if basis is None else basis.compiled_screen),
+    )
+
+
+def resolve_global_action_source_basis(
+    *,
+    runtime: WorkspaceRuntime,
+    source_screen_id: str | None,
+) -> SemanticSourceBasis:
+    basis = get_authoritative_current_basis(runtime)
+    if source_screen_id is None:
+        return SemanticSourceBasis(
+            source_screen_id=(None if basis is None else basis.screen_id),
+            source_compiled_screen=(None if basis is None else basis.compiled_screen),
+        )
+    if basis is not None and basis.screen_id == source_screen_id:
+        return SemanticSourceBasis(
+            source_screen_id=source_screen_id,
+            source_compiled_screen=basis.compiled_screen,
+        )
+    return SemanticSourceBasis(
+        source_screen_id=source_screen_id,
+        source_compiled_screen=None,
+    )
+
+
+def resolve_screen_continuity(
+    *,
+    source_screen_id: str | None,
+    source_compiled_screen: CompiledScreen | None,
+    current_screen: PublicScreen | None,
+    candidate_compiled_screen: CompiledScreen | None,
+) -> SemanticContinuityTruth:
+    if source_screen_id is None or current_screen is None:
+        return SemanticContinuityTruth("none", None)
+    if (
+        source_compiled_screen is not None
+        and source_compiled_screen.screen_id == source_screen_id
+        and candidate_compiled_screen is not None
+    ):
+        decision = evaluate_continuity(
+            source_screen=source_compiled_screen,
+            candidate_screen=candidate_compiled_screen,
+        )
+        return SemanticContinuityTruth(
+            continuity_status=decision.continuity_status,
+            changed=decision.changed,
+        )
+    continuity_status = (
+        "stable" if source_screen_id == current_screen.screen_id else "stale"
+    )
+    return SemanticContinuityTruth(
+        continuity_status=continuity_status,
+        changed=continuity_status == "stale",
+    )
+
+
+def resolve_runtime_continuity(
+    *,
+    runtime: WorkspaceRuntime,
+    source_screen_id: str | None,
+    source_compiled_screen: CompiledScreen | None,
+) -> SemanticContinuityTruth:
+    basis = get_authoritative_current_basis(runtime)
+    return resolve_screen_continuity(
+        source_screen_id=source_screen_id,
+        source_compiled_screen=source_compiled_screen,
+        current_screen=(None if basis is None else basis.public_screen),
+        candidate_compiled_screen=(None if basis is None else basis.compiled_screen),
+    )
+
+
+def resolve_open_changed(
+    *,
+    runtime: WorkspaceRuntime,
+    source_screen_id: str | None,
+    source_compiled_screen: CompiledScreen | None,
+) -> bool | None:
+    if source_screen_id is None or source_compiled_screen is None:
+        return None
+    if source_compiled_screen.screen_id != source_screen_id:
+        return None
+    basis = get_authoritative_current_basis(runtime)
+    if basis is None:
+        return None
+    decision = evaluate_continuity(
+        source_screen=source_compiled_screen,
+        candidate_screen=basis.compiled_screen,
+    )
+    return decision.changed
+
+
+__all__ = [
+    "SemanticContinuityTruth",
+    "SemanticSourceBasis",
+    "capture_runtime_source_basis",
+    "resolve_global_action_source_basis",
+    "resolve_open_changed",
+    "resolve_runtime_continuity",
+    "resolve_screen_continuity",
+]

androidctld/commands/service.py

@@ -0,0 +1,67 @@
+"""Semantic daemon-boundary command service."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from androidctld.artifacts.writer import ArtifactWriter
+from androidctld.commands.assembly import SleepFn, assemble_command_service
+from androidctld.commands.command_models import InternalCommand
+from androidctld.commands.executor import CommandExecutor
+from androidctld.device.bootstrap import DeviceBootstrapper
+from androidctld.device.interfaces import DeviceClientFactory
+from androidctld.runtime import RuntimeStore
+from androidctld.semantics.compiler import SemanticCompiler
+from androidctld.snapshots.service import SnapshotService
+
+__all__ = ["CommandService"]
+
+
+class CommandService:
+    def __init__(
+        self,
+        runtime_store: RuntimeStore,
+        bootstrapper: DeviceBootstrapper | None = None,
+        snapshot_service: SnapshotService | None = None,
+        semantic_compiler: SemanticCompiler | None = None,
+        artifact_writer: ArtifactWriter | None = None,
+        device_client_factory: DeviceClientFactory | None = None,
+        sleep_fn: SleepFn | None = None,
+        time_fn: Callable[[], float] | None = None,
+        executor: CommandExecutor | None = None,
+    ) -> None:
+        assembly = assemble_command_service(
+            runtime_store=runtime_store,
+            bootstrapper=bootstrapper,
+            snapshot_service=snapshot_service,
+            semantic_compiler=semantic_compiler,
+            artifact_writer=artifact_writer,
+            device_client_factory=device_client_factory,
+            sleep_fn=sleep_fn,
+            time_fn=time_fn,
+        )
+        self._runtime_kernel = assembly.runtime_kernel
+        self._runtime_store = assembly.runtime_store
+        self._orchestrator = assembly.orchestrator
+        self._executor = assembly.executor if executor is None else executor
+
+    def run(
+        self,
+        command: InternalCommand,
+    ) -> dict[str, Any]:
+        runtime = self._runtime_store.ensure_runtime()
+        return self._orchestrator.run(
+            runtime=runtime,
+            command=command,
+            execute=lambda: self._executor.run(
+                command=command,
+            ),
+        )
+
+    def close_runtime(self) -> dict[str, Any]:
+        runtime = self._runtime_store.ensure_runtime()
+        return self._orchestrator.close_runtime(
+            runtime=runtime,
+            close=lambda: self._runtime_kernel.close_runtime(runtime),
+        )

androidctld/config.py

@@ -0,0 +1,75 @@
+"""Shared configuration helpers for androidctld."""
+
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from androidctl_contracts.paths import daemon_state_root
+
+DEFAULT_HOST = "127.0.0.1"
+ACTIVE_FILE_NAME = "active.json"
+ACTIVE_LOCK_FILE_NAME = "active.lock"
+OWNER_LOCK_FILE_NAME = "owner.lock"
+TOKEN_FILE_NAME = "token.json"
+TOKEN_HEADER_NAME = "X-Androidctld-Token"
+
+
+def normalize_loopback_host(host: str) -> str:
+    normalized = host.strip().lower()
+    if not normalized:
+        raise ValueError("daemon host must not be empty")
+    if normalized == "localhost":
+        return DEFAULT_HOST
+    try:
+        parsed = ipaddress.ip_address(normalized)
+    except ValueError as error:
+        raise ValueError("daemon host must be a loopback address") from error
+    if not parsed.is_loopback:
+        raise ValueError("daemon host must be a loopback address")
+    if parsed.version == 6:
+        return "::1"
+    return str(parsed)
+
+
+@dataclass(frozen=True)
+class DaemonConfig:
+    workspace_root: Path
+    owner_id: str
+    host: str = DEFAULT_HOST
+    port: int = 0
+    state_dir: Path = field(init=False)
+
+    def __post_init__(self) -> None:
+        raw_workspace_root = str(self.workspace_root).strip()
+        if not raw_workspace_root:
+            raise ValueError("daemon workspace_root must not be empty")
+        resolved_root = Path(raw_workspace_root).expanduser().resolve()
+        normalized_owner = self.owner_id.strip()
+        if not normalized_owner:
+            raise ValueError("daemon owner_id must not be empty")
+        object.__setattr__(self, "owner_id", normalized_owner)
+        object.__setattr__(self, "workspace_root", resolved_root)
+        object.__setattr__(self, "host", normalize_loopback_host(self.host))
+        object.__setattr__(
+            self,
+            "state_dir",
+            daemon_state_root(resolved_root),
+        )
+
+    @property
+    def active_file_path(self) -> Path:
+        return self.state_dir / ACTIVE_FILE_NAME
+
+    @property
+    def active_lock_path(self) -> Path:
+        return self.state_dir / ACTIVE_LOCK_FILE_NAME
+
+    @property
+    def owner_lock_path(self) -> Path:
+        return self.state_dir / OWNER_LOCK_FILE_NAME
+
+    @property
+    def token_file_path(self) -> Path:
+        return self.state_dir / TOKEN_FILE_NAME

androidctld/daemon/__init__.py

@@ -0,0 +1 @@
+"""Daemon HTTP server package."""

androidctld/daemon/active_slot.py

@@ -0,0 +1,326 @@
+"""Active-slot ownership and publication for androidctld."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from androidctld.auth.active_registry import ActiveDaemonRecord, ActiveDaemonRegistry
+from androidctld.auth.secret_files import write_secret_json_file_atomically
+from androidctld.auth.token_store import DaemonTokenStore
+from androidctld.config import DaemonConfig, normalize_loopback_host
+from androidctld.daemon.ownership_probe import (
+    OwnershipHealthProbe,
+    OwnershipHealthProbeResult,
+    OwnershipHealthStatus,
+)
+
+
+@dataclass(frozen=True)
+class _OwnerLockRecord:
+    pid: int
+    host: str
+    port: int
+    started_at: str
+    workspace_root: str
+    owner_id: str
+
+    @property
+    def identity(self) -> tuple[int, str]:
+        return (self.pid, self.started_at)
+
+
+class ActiveSlotCoordinator:
+    _OWNER_LOCK_STALE_SECONDS = 2.0
+
+    def __init__(
+        self,
+        *,
+        config: DaemonConfig,
+        active_registry: ActiveDaemonRegistry,
+        existing_token_reader: Callable[[], str | None] | None = None,
+        ownership_probe: OwnershipHealthProbe | None = None,
+    ) -> None:
+        self._config = config
+        self._active_registry = active_registry
+        self._existing_token_reader = existing_token_reader or (
+            lambda: DaemonTokenStore.load_existing_token(self._config.token_file_path)
+        )
+        self._ownership_probe = ownership_probe or OwnershipHealthProbe()
+        self._active_record: ActiveDaemonRecord | None = None
+        self._owns_owner_lock = False
+
+    @property
+    def active_record(self) -> ActiveDaemonRecord | None:
+        return self._active_record
+
+    def acquire(self) -> None:
+        lock_path = self._config.owner_lock_path
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        while True:
+            fd: int | None = None
+            try:
+                fd = os.open(
+                    lock_path,
+                    os.O_CREAT | os.O_EXCL | os.O_WRONLY,
+                    0o600,
+                )
+                os.write(fd, str(os.getpid()).encode("utf-8"))
+                os.close(fd)
+                fd = None
+                self._owns_owner_lock = True
+                return
+            except FileExistsError:
+                if self._recover_stale_owner_lock(lock_path):
+                    continue
+                self._restore_active_record_from_owner_lock()
+                raise RuntimeError("live daemon already owns active slot") from None
+            finally:
+                if fd is not None:
+                    os.close(fd)
+
+    def prepare(self, *, host: str, port: int, token: str) -> ActiveDaemonRecord:
+        record = self._active_registry.build_record(host=host, port=port, token=token)
+        self._active_record = record
+        return record
+
+    def publish(self, record: ActiveDaemonRecord | None = None) -> ActiveDaemonRecord:
+        active_record = record or self._active_record
+        if active_record is None:
+            raise RuntimeError("active record is not prepared")
+        self._active_registry.publish(active_record)
+        self._publish_owner_lock_record(active_record)
+        self._active_record = active_record
+        return active_record
+
+    def clear_record(self) -> None:
+        active_record = self._active_record
+        if active_record is not None:
+            self._active_registry.clear(record=active_record)
+        self._active_record = None
+
+    def release_owner(self) -> None:
+        if not self._owns_owner_lock:
+            return
+        self._owns_owner_lock = False
+        try:
+            self._config.owner_lock_path.unlink()
+        except FileNotFoundError:
+            return
+
+    def release(self) -> None:
+        self.clear_record()
+        self.release_owner()
+
+    def _recover_stale_owner_lock(self, lock_path: Path) -> bool:
+        try:
+            lock_age_seconds = time.time() - lock_path.stat().st_mtime
+        except OSError:
+            return False
+        if self._owner_lock_has_live_evidence(lock_path):
+            return False
+        if lock_age_seconds < self._OWNER_LOCK_STALE_SECONDS:
+            pid = self._owner_lock_pid(lock_path)
+            if pid <= 0 or ActiveDaemonRegistry._is_pid_live(pid):
+                return False
+        try:
+            lock_path.unlink()
+        except FileNotFoundError:
+            return True
+        except OSError:
+            return False
+        return True
+
+    def _owner_lock_has_live_evidence(self, lock_path: Path) -> bool:
+        owner_lock = self._read_owner_lock_record(lock_path)
+        if owner_lock is None:
+            return False
+        token_probe = self._probe_owner_lock(owner_lock)
+        return token_probe.is_live
+
+    def _publish_owner_lock_record(self, record: ActiveDaemonRecord) -> None:
+        payload = {
+            "host": normalize_loopback_host(record.host),
+            "ownerId": record.owner_id,
+            "pid": record.pid,
+            "port": record.port,
+            "startedAt": record.started_at,
+            "workspaceRoot": record.workspace_root,
+        }
+        write_secret_json_file_atomically(self._config.owner_lock_path, payload)
+
+    def _owner_lock_pid(self, lock_path: Path) -> int:
+        try:
+            raw = lock_path.read_text(encoding="utf-8").strip()
+        except OSError:
+            return -1
+        if not raw:
+            return -1
+        try:
+            return int(raw)
+        except ValueError:
+            pass
+        try:
+            payload = json.loads(raw)
+        except (ValueError, json.JSONDecodeError):
+            return -1
+        if not isinstance(payload, dict):
+            return -1
+        pid = payload.get("pid")
+        if isinstance(pid, int):
+            return pid
+        return -1
+
+    def _restore_active_record_from_owner_lock(self) -> None:
+        owner_lock = self._read_owner_lock_record(self._config.owner_lock_path)
+        if owner_lock is None:
+            return
+        if not self._owner_lock_matches_current_config(owner_lock):
+            return
+        probe_result = self._probe_owner_lock(owner_lock)
+        if probe_result.status != OwnershipHealthStatus.LIVE_MATCH:
+            return
+        token = probe_result.token
+        if token is None:
+            token = self._first_token_for_owner_lock(owner_lock)
+        if token is None:
+            return
+        record = ActiveDaemonRecord(
+            pid=owner_lock.pid,
+            host=owner_lock.host,
+            port=owner_lock.port,
+            token=token,
+            started_at=owner_lock.started_at,
+            workspace_root=owner_lock.workspace_root,
+            owner_id=owner_lock.owner_id,
+        )
+        try:
+            self._active_registry.restore(record)
+        except ValueError:
+            return
+
+    def _read_owner_lock_record(self, lock_path: Path) -> _OwnerLockRecord | None:
+        try:
+            raw = lock_path.read_text(encoding="utf-8").strip()
+        except OSError:
+            return None
+        if not raw:
+            return None
+        try:
+            payload = json.loads(raw)
+        except (ValueError, json.JSONDecodeError):
+            return None
+        if not isinstance(payload, dict):
+            return None
+        try:
+            pid = self._read_int(payload.get("pid"))
+            host = self._read_str(payload.get("host"))
+            port = self._read_int(payload.get("port"))
+            started_at = self._read_str(payload.get("startedAt"))
+            workspace_root = self._read_str(payload.get("workspaceRoot"))
+            owner_id = self._read_str(payload.get("ownerId"))
+        except ValueError:
+            return None
+        return _OwnerLockRecord(
+            pid=pid,
+            host=host,
+            port=port,
+            started_at=started_at,
+            workspace_root=workspace_root,
+            owner_id=owner_id,
+        )
+
+    @staticmethod
+    def _read_int(value: object) -> int:
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValueError("expected integer")
+        return value
+
+    @staticmethod
+    def _read_str(value: object) -> str:
+        if not isinstance(value, str):
+            raise ValueError("expected string")
+        value = value.strip()
+        if not value:
+            raise ValueError("expected non-empty string")
+        return value
+
+    def _owner_lock_matches_current_config(self, record: _OwnerLockRecord) -> bool:
+        if record.workspace_root != self._config.workspace_root.as_posix():
+            return False
+        if record.owner_id != self._config.owner_id:
+            return False
+        if self._normalize_owner_host(record.host) != self._config.host:
+            return False
+        return self._config.port == 0 or record.port == self._config.port
+
+    def _probe_owner_lock(
+        self,
+        record: _OwnerLockRecord,
+    ) -> OwnershipHealthProbeResult:
+        tokens = self._tokens_for_owner_lock(record)
+        return self._ownership_probe.probe(
+            host=record.host,
+            port=record.port,
+            owner_id=record.owner_id,
+            workspace_root=record.workspace_root,
+            expected_workspace_root=self._config.workspace_root.as_posix(),
+            expected_owner_id=self._config.owner_id,
+            tokens=tokens,
+        )
+
+    def _tokens_for_owner_lock(self, record: _OwnerLockRecord) -> list[str]:
+        tokens: list[str] = []
+        token = self._existing_token_reader()
+        if token is not None:
+            tokens.append(token)
+        active_record = self._active_registry.read()
+        if active_record is not None and self._active_record_matches_owner_lock(
+            active_record,
+            record,
+        ):
+            tokens.append(active_record.token)
+        return self._unique_tokens(tokens)
+
+    def _first_token_for_owner_lock(self, record: _OwnerLockRecord) -> str | None:
+        tokens = self._tokens_for_owner_lock(record)
+        if not tokens:
+            return None
+        return tokens[0]
+
+    @staticmethod
+    def _unique_tokens(tokens: list[str]) -> list[str]:
+        unique: list[str] = []
+        seen: set[str] = set()
+        for token in tokens:
+            token = token.strip()
+            if not token or token in seen:
+                continue
+            unique.append(token)
+            seen.add(token)
+        return unique
+
+    @staticmethod
+    def _normalize_owner_host(host: str) -> str:
+        try:
+            return normalize_loopback_host(host)
+        except ValueError:
+            return host
+
+    @staticmethod
+    def _active_record_matches_owner_lock(
+        active_record: ActiveDaemonRecord,
+        owner_lock: _OwnerLockRecord,
+    ) -> bool:
+        return (
+            active_record.pid == owner_lock.pid
+            and active_record.host == owner_lock.host
+            and active_record.port == owner_lock.port
+            and active_record.started_at == owner_lock.started_at
+            and active_record.workspace_root == owner_lock.workspace_root
+            and active_record.owner_id == owner_lock.owner_id
+        )