androidctl 0.1.0__tar.gz → 0.1.1__tar.gz

{androidctl-0.1.0 → androidctl-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: androidctl
-Version: 0.1.0
+Version: 0.1.1
 Summary: A Playwright-like CLI for Android automation, built for AI agents.
 Author: Azure99
 License-Expression: GPL-3.0-or-later
@@ -64,6 +64,14 @@ androidctl observe
 - Android SDK platform tools, especially `adb`.
 - An Android 11+ device or emulator with USB debugging enabled.
 
+## Installing skills
+
+For agents that support skills, ask your agent to install the AndroidCtl skill:
+
+```text
+Install this skill: https://github.com/Azure99/androidctl/tree/main/skills/androidctl
+```
+
 ## Install From PyPI
 
 Install the released host tools with the single public distribution:

{androidctl-0.1.0 → androidctl-0.1.1}/README.md

@@ -28,6 +28,14 @@ androidctl observe
 - Android SDK platform tools, especially `adb`.
 - An Android 11+ device or emulator with USB debugging enabled.
 
+## Installing skills
+
+For agents that support skills, ask your agent to install the AndroidCtl skill:
+
+```text
+Install this skill: https://github.com/Azure99/androidctl/tree/main/skills/androidctl
+```
+
 ## Install From PyPI
 
 Install the released host tools with the single public distribution:

androidctl-0.1.1/VERSION

@@ -0,0 +1 @@
+0.1.1

androidctl-0.1.1/androidctl/src/androidctl/_version.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from androidctl_contracts._version_source import resolve_release_version
+
+__version__ = resolve_release_version()

{androidctl-0.1.0 → androidctl-0.1.1}/androidctl/src/androidctl/daemon/owner.py

@@ -10,6 +10,7 @@ from pathlib import Path
 from typing import Any
 
 OWNER_ENV = "ANDROIDCTL_OWNER_ID"
+WINDOWS_OWNER_ANCHOR_ENV = "ANDROIDCTL_OWNER_ANCHOR_PROCESSES"
 DEFAULT_OWNER_HINT = "Set ANDROIDCTL_OWNER_ID explicitly."
 _MAX_OWNER_PROCESS_HOPS = 64
 _SHELL_PROCESS_NAMES = frozenset(
@@ -18,6 +19,7 @@ _SHELL_PROCESS_NAMES = frozenset(
 _WINDOWS_SHELL_PROCESS_NAMES = frozenset(
     {"bash.exe", "cmd.exe", "powershell.exe", "pwsh.exe", "sh.exe"}
 )
+_DEFAULT_WINDOWS_OWNER_ANCHOR_PROCESS_NAMES = frozenset({"claude.exe", "codex.exe"})
 _TH32CS_SNAPPROCESS = 0x00000002
 _PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
 _ERROR_NO_MORE_FILES = 18
@@ -30,6 +32,19 @@ class _WindowsProcessInfo:
     process_name: str
 
 
+@dataclass(frozen=True)
+class _WindowsAncestorProcess:
+    pid: int
+    process_name: str
+
+
+@dataclass(frozen=True)
+class _WindowsOwnerTarget:
+    kind: str
+    pid: int
+    process_name: str
+
+
 class _WindowsFileTime(ctypes.Structure):
     _fields_ = [
         ("dwLowDateTime", wintypes.DWORD),
@@ -58,8 +73,8 @@ def derive_owner_id(*, env: Mapping[str, str]) -> str:
         candidate = configured.strip()
         if candidate:
             return candidate
-    if sys.platform == "win32":
-        owner_id = _derive_windows_owner_id()
+    if _is_windows_platform():
+        owner_id = _derive_windows_owner_id(env=env)
         if owner_id is None:
             raise ValueError(
                 "Unable to derive a safe owner identity automatically. "
@@ -81,6 +96,10 @@ def derive_owner_id(*, env: Mapping[str, str]) -> str:
     return f"shell:{shell_pid}:{lifetime}"
 
 
+def _is_windows_platform() -> bool:
+    return sys.platform == "win32"
+
+
 def _find_interactive_shell_ancestor_pid(env: Mapping[str, str]) -> int | None:
     del env
     current_pid = os.getpid()
@@ -108,39 +127,112 @@ def _find_interactive_shell_ancestor_pid(env: Mapping[str, str]) -> int | None:
     return None
 
 
-def _derive_windows_owner_id() -> str | None:
-    shell_pid = _find_windows_shell_ancestor_pid()
-    if shell_pid is None:
-        return None
-    lifetime = _read_windows_process_creation_filetime(shell_pid)
-    if lifetime is None:
-        return None
-    return f"shell:win32:{shell_pid}:{lifetime}"
-
-
-def _find_windows_shell_ancestor_pid() -> int | None:
+def _derive_windows_owner_id(*, env: Mapping[str, str]) -> str | None:
     process_table = _read_windows_process_table()
     if process_table is None:
         return None
+    for target in _find_windows_owner_targets(process_table, env=env):
+        lifetime = _read_windows_process_creation_filetime(target.pid)
+        if lifetime is None:
+            continue
+        if target.kind == "agent":
+            return f"agent:win32:{target.process_name}:{target.pid}:{lifetime}"
+        return f"shell:win32:{target.pid}:{lifetime}"
+    return None
+
+
+def _find_windows_owner_targets(
+    process_table: dict[int, _WindowsProcessInfo],
+    *,
+    env: Mapping[str, str],
+) -> list[_WindowsOwnerTarget]:
+    anchor_names = _windows_owner_anchor_process_names(env)
+    agent_targets: list[_WindowsOwnerTarget] = []
+    shell_target: _WindowsOwnerTarget | None = None
+    for ancestor in _windows_ancestor_chain(process_table):
+        if ancestor.process_name in anchor_names:
+            agent_targets.append(
+                _WindowsOwnerTarget(
+                    kind="agent",
+                    pid=ancestor.pid,
+                    process_name=ancestor.process_name,
+                )
+            )
+        if (
+            shell_target is None
+            and ancestor.process_name in _WINDOWS_SHELL_PROCESS_NAMES
+        ):
+            shell_target = _WindowsOwnerTarget(
+                kind="shell",
+                pid=ancestor.pid,
+                process_name=ancestor.process_name,
+            )
+    if shell_target is not None:
+        return [*agent_targets, shell_target]
+    return agent_targets
+
+
+def _windows_ancestor_chain(
+    process_table: dict[int, _WindowsProcessInfo],
+) -> list[_WindowsAncestorProcess]:
     current_pid = os.getpid()
     current = process_table.get(current_pid)
     if current is None:
-        return None
+        return []
     ancestor_pid = current.parent_pid
     seen: set[int] = {current_pid}
+    ancestors: list[_WindowsAncestorProcess] = []
     hops = 0
     while ancestor_pid > 0 and hops < _MAX_OWNER_PROCESS_HOPS:
         if ancestor_pid in seen:
-            return None
+            return []
         seen.add(ancestor_pid)
         ancestor = process_table.get(ancestor_pid)
         if ancestor is None:
-            return None
-        process_name = _normalize_windows_process_name(ancestor.process_name)
-        if process_name in _WINDOWS_SHELL_PROCESS_NAMES:
-            return ancestor_pid
+            break
+        ancestors.append(
+            _WindowsAncestorProcess(
+                pid=ancestor_pid,
+                process_name=_normalize_windows_process_name(ancestor.process_name),
+            )
+        )
         ancestor_pid = ancestor.parent_pid
         hops += 1
+    return ancestors
+
+
+def _windows_owner_anchor_process_names(env: Mapping[str, str]) -> set[str]:
+    process_names = set(_DEFAULT_WINDOWS_OWNER_ANCHOR_PROCESS_NAMES)
+    configured = env.get(WINDOWS_OWNER_ANCHOR_ENV)
+    if configured is None:
+        return process_names
+    for raw_name in configured.replace(";", ",").split(","):
+        normalized = _normalize_windows_process_name(raw_name)
+        if normalized:
+            process_names.add(normalized)
+    return process_names
+
+
+def _find_windows_shell_ancestor_pid() -> int | None:
+    process_table = _read_windows_process_table()
+    if process_table is None:
+        return None
+    target = _find_windows_shell_ancestor(process_table)
+    if target is None:
+        return None
+    return target.pid
+
+
+def _find_windows_shell_ancestor(
+    process_table: dict[int, _WindowsProcessInfo],
+) -> _WindowsOwnerTarget | None:
+    for ancestor in _windows_ancestor_chain(process_table):
+        if ancestor.process_name in _WINDOWS_SHELL_PROCESS_NAMES:
+            return _WindowsOwnerTarget(
+                kind="shell",
+                pid=ancestor.pid,
+                process_name=ancestor.process_name,
+            )
     return None
 
 

{androidctl-0.1.0 → androidctl-0.1.1}/androidctl.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: androidctl
-Version: 0.1.0
+Version: 0.1.1
 Summary: A Playwright-like CLI for Android automation, built for AI agents.
 Author: Azure99
 License-Expression: GPL-3.0-or-later
@@ -64,6 +64,14 @@ androidctl observe
 - Android SDK platform tools, especially `adb`.
 - An Android 11+ device or emulator with USB debugging enabled.
 
+## Installing skills
+
+For agents that support skills, ask your agent to install the AndroidCtl skill:
+
+```text
+Install this skill: https://github.com/Azure99/androidctl/tree/main/skills/androidctl
+```
+
 ## Install From PyPI
 
 Install the released host tools with the single public distribution:

{androidctl-0.1.0 → androidctl-0.1.1}/androidctl.egg-info/SOURCES.txt

@@ -1,5 +1,6 @@
 LICENSE
 README.md
+VERSION
 pyproject.toml
 androidctl.egg-info/PKG-INFO
 androidctl.egg-info/SOURCES.txt
@@ -49,7 +50,7 @@ androidctl/src/androidctl/renderers/_paths.py
 androidctl/src/androidctl/renderers/xml.py
 androidctl/src/androidctl/renderers/xml_projection.py
 androidctl/src/androidctl/resources/__init__.py
-androidctl/src/androidctl/resources/androidctl-agent-0.1.0-release.apk
+androidctl/src/androidctl/resources/androidctl-agent-0.1.1-release.apk
 androidctl/src/androidctl/setup/__init__.py
 androidctl/src/androidctl/setup/accessibility.py
 androidctl/src/androidctl/setup/adb.py
@@ -178,6 +179,7 @@ androidctld/src/androidctld/waits/loop.py
 androidctld/src/androidctld/waits/matcher.py
 contracts/src/androidctl_contracts/__init__.py
 contracts/src/androidctl_contracts/_version.py
+contracts/src/androidctl_contracts/_version_source.py
 contracts/src/androidctl_contracts/_wire_helpers.py
 contracts/src/androidctl_contracts/base.py
 contracts/src/androidctl_contracts/command_catalog.py

androidctl-0.1.1/androidctld/src/androidctld/_version.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from androidctl_contracts._version_source import resolve_release_version
+
+__version__ = resolve_release_version()

{androidctl-0.1.0 → androidctl-0.1.1}/androidctld/src/androidctld/commands/handlers/observe.py

@@ -54,7 +54,6 @@ class ObserveCommandHandler:
                 artifacts=None if source_basis is None else source_basis.artifacts,
             ).model_dump(by_alias=True, mode="json")
         lifecycle_lease = self._runtime_kernel.capture_lifecycle_lease(runtime)
-        force_refresh = source_basis is None
         self._runtime_kernel.acquire_progress_lane(
             runtime,
             occupant_kind=command.kind.value,
@@ -62,7 +61,7 @@ class ObserveCommandHandler:
         try:
             snapshot = self._snapshot_service.fetch(
                 runtime,
-                force_refresh=force_refresh,
+                force_refresh=True,
                 lifecycle_lease=lifecycle_lease,
             )
             previous_screen = (

{androidctl-0.1.0 → androidctl-0.1.1}/androidctld/src/androidctld/daemon/server.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import errno
 import json
 import logging
 import threading
@@ -27,6 +28,18 @@ from androidctld.runtime_policy import (
     DAEMON_HTTP_SOCKET_TIMEOUT_SECONDS,
 )
 
+_CLIENT_DISCONNECT_ERRNOS = {
+    errno.EPIPE,
+    errno.ECONNRESET,
+    errno.ECONNABORTED,
+    errno.ETIMEDOUT,
+}
+_CLIENT_DISCONNECT_WINERRORS = {
+    10053,  # WSAECONNABORTED
+    10054,  # WSAECONNRESET
+    10058,  # WSAESHUTDOWN
+}
+
 
 class AndroidctldHttpServer:
     def __init__(
@@ -84,6 +97,7 @@ class AndroidctldHttpServer:
             and method == "POST"
             and path
             in {
+                "/health",
                 "/runtime/get",
                 "/runtime/close",
                 "/commands/run",
@@ -176,24 +190,31 @@ class AndroidctldHttpServer:
             )
             if result.shutdown_after_write:
                 self._enter_closing_gate()
+                self._retire_active_slot_for_close()
                 try:
-                    self._write_json(
+                    self._try_write_json_response(
                         handler,
                         result.status_code,
                         success_envelope(result.payload),
+                        response_kind="close_success",
                     )
-                except OSError:
-                    self._logger.info("close response write failed", exc_info=True)
                 finally:
                     self._request_shutdown_after_close()
                 return
-            self._write_json(
+            if not self._try_write_json_response(
                 handler,
                 result.status_code,
                 success_envelope(result.payload),
-            )
+                response_kind="success",
+            ):
+                return
         except DaemonError as error:
-            self._write_json(handler, error.http_status, error_envelope(error))
+            self._try_write_json_response(
+                handler,
+                error.http_status,
+                error_envelope(error),
+                response_kind="daemon_error",
+            )
         except Exception:  # pragma: no cover - defensive fallback
             self._logger.exception("unexpected daemon failure")
             daemon_error = DaemonError(
@@ -203,8 +224,11 @@ class AndroidctldHttpServer:
                 details={},
                 http_status=500,
             )
-            self._write_json(
-                handler, daemon_error.http_status, error_envelope(daemon_error)
+            self._try_write_json_response(
+                handler,
+                daemon_error.http_status,
+                error_envelope(daemon_error),
+                response_kind="internal_error",
             )
 
     def _enter_closing_gate(self) -> None:
@@ -212,6 +236,22 @@ class AndroidctldHttpServer:
             return
         self._closing = True
 
+    def _retire_active_slot_for_close(self) -> None:
+        try:
+            self._active_slot.clear_record()
+        except Exception:
+            self._logger.warning(
+                "failed to clear active daemon record while closing",
+                exc_info=True,
+            )
+        try:
+            self._active_slot.release_owner()
+        except Exception:
+            self._logger.warning(
+                "failed to release active daemon owner lock while closing",
+                exc_info=True,
+            )
+
     def _request_shutdown_after_close(self) -> None:
         if self._shutdown_after_close_requested:
             return
@@ -284,3 +324,95 @@ class AndroidctldHttpServer:
         handler.send_header("Content-Length", str(len(body)))
         handler.end_headers()
         handler.wfile.write(body)
+
+    def _try_write_json_response(
+        self,
+        handler: BaseHTTPRequestHandler,
+        status_code: int,
+        payload: dict[str, Any],
+        *,
+        response_kind: str,
+    ) -> bool:
+        try:
+            self._write_json(handler, status_code, payload)
+            return True
+        except OSError as error:
+            if _is_response_write_client_disconnect(error):
+                self._log_client_disconnect(
+                    handler,
+                    status_code=status_code,
+                    response_kind=response_kind,
+                    error=error,
+                )
+                handler.close_connection = True
+                return False
+            self._log_response_write_failure(
+                handler,
+                status_code=status_code,
+                response_kind=response_kind,
+                error=error,
+            )
+            handler.close_connection = True
+            return False
+
+    def _log_client_disconnect(
+        self,
+        handler: BaseHTTPRequestHandler,
+        *,
+        status_code: int,
+        response_kind: str,
+        error: OSError,
+    ) -> None:
+        self._logger.info(
+            "client disconnected before response write completed "
+            "method=%s path=%s status=%s response=%s exception=%s",
+            _handler_method(handler),
+            _handler_path(handler),
+            status_code,
+            response_kind,
+            type(error).__name__,
+        )
+
+    def _log_response_write_failure(
+        self,
+        handler: BaseHTTPRequestHandler,
+        *,
+        status_code: int,
+        response_kind: str,
+        error: OSError,
+    ) -> None:
+        self._logger.warning(
+            "response write failed method=%s path=%s status=%s response=%s "
+            "exception=%s",
+            _handler_method(handler),
+            _handler_path(handler),
+            status_code,
+            response_kind,
+            type(error).__name__,
+            exc_info=True,
+        )
+
+
+def _is_response_write_client_disconnect(error: OSError) -> bool:
+    if isinstance(
+        error,
+        (
+            BrokenPipeError,
+            ConnectionAbortedError,
+            ConnectionResetError,
+            TimeoutError,
+        ),
+    ):
+        return True
+    if error.errno in _CLIENT_DISCONNECT_ERRNOS:
+        return True
+    winerror = getattr(error, "winerror", None)
+    return winerror in _CLIENT_DISCONNECT_WINERRORS
+
+
+def _handler_method(handler: BaseHTTPRequestHandler) -> str:
+    return str(getattr(handler, "command", "<unknown>"))
+
+
+def _handler_path(handler: BaseHTTPRequestHandler) -> str:
+    return str(getattr(handler, "path", "<unknown>"))

androidctl-0.1.1/contracts/src/androidctl_contracts/_version.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from ._version_source import resolve_release_version
+
+__version__ = resolve_release_version()

androidctl-0.1.1/contracts/src/androidctl_contracts/_version_source.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import re
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as distribution_version
+from pathlib import Path
+
+_DISTRIBUTION_NAME = "androidctl"
+_VERSION_FILE_NAME = "VERSION"
+_VERSION_PATTERN = re.compile(r"\d+\.\d+\.\d+\Z")
+
+
+def resolve_release_version() -> str:
+    source_version = _read_source_version()
+    if source_version is not None:
+        return source_version
+    try:
+        return distribution_version(_DISTRIBUTION_NAME)
+    except PackageNotFoundError as error:
+        raise RuntimeError("unable to resolve androidctl release version") from error
+
+
+def _read_source_version() -> str | None:
+    for candidate_root in Path(__file__).resolve().parents:
+        version_path = candidate_root / _VERSION_FILE_NAME
+        if not version_path.is_file() or not _looks_like_repo_root(candidate_root):
+            continue
+        return _parse_version_text(version_path.read_text(encoding="utf-8"))
+    return None
+
+
+def _looks_like_repo_root(path: Path) -> bool:
+    return (
+        (path / "pyproject.toml").is_file()
+        and (path / "androidctl").is_dir()
+        and (path / "androidctld").is_dir()
+        and (path / "contracts").is_dir()
+    )
+
+
+def _parse_version_text(raw_text: str) -> str:
+    if raw_text.endswith("\r\n"):
+        candidate = raw_text.removesuffix("\r\n")
+    elif raw_text.endswith("\n"):
+        candidate = raw_text.removesuffix("\n")
+    else:
+        candidate = raw_text
+    if (
+        "\n" in candidate
+        or "\r" in candidate
+        or _VERSION_PATTERN.fullmatch(candidate) is None
+    ):
+        raise RuntimeError(
+            "canonical VERSION must contain exactly MAJOR.MINOR.PATCH with "
+            "at most one terminating newline"
+        )
+    return candidate

{androidctl-0.1.0 → androidctl-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "androidctl"
-version = "0.1.0"
+dynamic = ["version"]
 description = "A Playwright-like CLI for Android automation, built for AI agents."
 authors = [{ name = "Azure99" }]
 keywords = ["agent", "android", "adb", "automation", "cli", "accessibility"]
@@ -58,6 +58,9 @@ namespaces = false
 [tool.setuptools.package-data]
 "androidctl.resources" = ["*.apk"]
 
+[tool.setuptools.dynamic]
+version = { file = ["VERSION"] }
+
 [tool.pytest.ini_options]
 pythonpath = [
     "contracts/src",

androidctl-0.1.0/androidctl/src/androidctl/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"

androidctl-0.1.0/androidctld/src/androidctld/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"

androidctl-0.1.0/contracts/src/androidctl_contracts/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"