gemini-computer-use 0.2.4 → 0.4.2

package/core/termux.py

@@ -0,0 +1,916 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""core/termux.py - the one place in the node that runs ``termux-*`` commands.
+
+Termux:API is a two-part install: the ``termux-api`` package supplies the shell
+commands, and the Termux:API **app** answers them over an Android binder. Either
+half missing produces the same silent nothing from the phone, so every
+``termux-*`` call in this project goes through this module and every failure
+comes back as a dict a model can act on instead of an exception nobody catches:
+
+* ``missing`` - the command is not on ``PATH`` (the package or the app is absent);
+* ``denied``  - Android refused the permission behind the call;
+* ``timeout`` - Android froze the Termux:API app, which is the *normal* failure
+  mode once the screen has been off for a while;
+* ``refused`` - the caller asked for something that is not a ``termux-*``
+  command, which must never reach an exec.
+
+Contract:
+
+* **nothing raises** - a public function always returns a dict;
+* **no shell, ever** - every command is an argv list under a hard timeout, so a
+  string that arrived from a model can never become shell syntax;
+* **cheap** - a missing command is answered from ``shutil.which`` without
+  starting a process, and the command inventory is cached for a minute;
+* **one root cause, said once** - when every command hangs because the
+  Termux:API *app* is missing, that is remembered (for a short while) instead of
+  making each telemetry section report its own timeout;
+* **silent** - no printing, no logging, no progress output.
+
+The wake lock lives here for the same reason the rest does: Android freezes
+background processes when the screen goes off, and the node's own boot script
+takes the lock exactly once at boot with nobody left to release it.
+"""
+
+from __future__ import annotations
+
+import json
+import locale as _locale
+import os
+import shutil
+import subprocess
+import threading
+import time
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+#: The one sentence a user needs when a ``termux-*`` command is missing. Both
+#: halves matter: an app from a *different* store than the package fails to bind,
+#: which looks exactly like "the command is not installed".
+TERMUX_API_FIX = ("install the Termux:API app from the SAME store as Termux "
+                  "(F-Droid or GitHub, never mixed) and run `pkg install termux-api`")
+
+#: Told whenever a command exists but never answers. Android freezes the
+#: Termux:API app in the background, and the binder call then waits forever.
+TERMUX_TIMEOUT_FIX = ("open the Termux:API app once after installing it, and disable "
+                      "battery optimisation for Termux and Termux:API")
+
+#: Told when ``~/storage/shared`` is missing: that symlink is the only reason the
+#: node can read or write the phone's own storage.
+TERMUX_STORAGE_FIX = ("run `termux-setup-storage` in Termux and grant the storage "
+                      "permission it asks for")
+
+#: Every Termux:API command this project may use. Kept in one tuple so the
+#: inventory a model receives and the allowlist the runner enforces cannot drift.
+REQUIRED_COMMANDS: Tuple[str, ...] = (
+    "termux-battery-status",
+    "termux-brightness",
+    "termux-call-log",
+    "termux-camera-info",
+    "termux-camera-photo",
+    "termux-clipboard-get",
+    "termux-clipboard-set",
+    "termux-contact-list",
+    "termux-dialog",
+    "termux-download",
+    "termux-fingerprint",
+    "termux-infrared-frequencies",
+    "termux-infrared-transmit",
+    "termux-job-scheduler",
+    "termux-location",
+    "termux-media-player",
+    "termux-media-scan",
+    "termux-microphone-record",
+    "termux-notification",
+    "termux-notification-list",
+    "termux-notification-remove",
+    "termux-open",
+    "termux-open-url",
+    "termux-sensor",
+    "termux-share",
+    "termux-sms-list",
+    "termux-sms-send",
+    "termux-storage-get",
+    "termux-telephony-call",
+    "termux-telephony-cellinfo",
+    "termux-telephony-deviceinfo",
+    "termux-toast",
+    "termux-torch",
+    "termux-tts-engines",
+    "termux-tts-speak",
+    "termux-usb",
+    "termux-vibrate",
+    "termux-volume",
+    "termux-wallpaper",
+    "termux-wake-lock",
+    "termux-wake-unlock",
+    "termux-wifi-connectioninfo",
+    "termux-wifi-enable",
+    "termux-wifi-scaninfo",
+)
+
+#: Without these three a phone cannot even be described: battery, clipboard and
+#: the notification channel. Their absence is what "the API is not installed"
+#: means to a user, so a partial install is reported as not installed.
+MANDATORY_COMMANDS: Tuple[str, ...] = (
+    "termux-battery-status",
+    "termux-clipboard-get",
+    "termux-notification",
+)
+
+#: The Android permission groups behind the commands above. They start as
+#: "unknown" and are only ever changed by a real observation - probing the camera
+#: or the microphone just to learn a state would open hardware the caller never
+#: asked for, which is a side effect a status call must not have.
+PERMISSION_APIS: Tuple[str, ...] = (
+    "biometric",
+    "call_log",
+    "camera",
+    "clipboard",
+    "contacts",
+    "location",
+    "microphone",
+    "notification",
+    "sensors",
+    "sms",
+    "storage",
+    "telephony",
+    "usb",
+    "wifi",
+)
+
+#: Which permission a failing command was exercising. A command missing from this
+#: map still reports ``denied``; it just cannot name the permission to remember.
+_COMMAND_API: Dict[str, str] = {
+    "termux-call-log": "call_log",
+    "termux-camera-info": "camera",
+    "termux-camera-photo": "camera",
+    "termux-clipboard-get": "clipboard",
+    "termux-clipboard-set": "clipboard",
+    "termux-contact-list": "contacts",
+    "termux-fingerprint": "biometric",
+    "termux-location": "location",
+    "termux-microphone-record": "microphone",
+    "termux-notification": "notification",
+    "termux-notification-list": "notification",
+    "termux-notification-remove": "notification",
+    "termux-sensor": "sensors",
+    "termux-sms-list": "sms",
+    "termux-sms-send": "sms",
+    "termux-storage-get": "storage",
+    "termux-telephony-call": "telephony",
+    "termux-telephony-cellinfo": "telephony",
+    "termux-telephony-deviceinfo": "telephony",
+    "termux-usb": "usb",
+    "termux-wifi-connectioninfo": "wifi",
+    "termux-wifi-enable": "wifi",
+    "termux-wifi-scaninfo": "wifi",
+}
+
+#: Failure text from the Termux:API app that always means "Android refused this
+#: call", whichever API is behind it.
+_PERMISSION_PHRASES: Tuple[str, ...] = (
+    "permission denied",
+    "not granted",
+    "requires permission",
+    "securityexception",
+    "location services",
+    "user denied",
+    "no such file or directory: /dev/video",
+    # The wording a real phone used (OPPO PHY110, Android 16), delivered as JSON on
+    # stdout with exit code 0: {"error": "Please grant the following permission to
+    # use this command: android.permission.ACCESS_COARSE_LOCATION"}.
+    "please grant",
+)
+
+#: Words that turn a plain noun ("camera", "microphone") into a permission
+#: failure. The nouns alone are not enough: "no camera found" is a hardware
+#: answer, not a permission one, and must not be reported as "grant this".
+_PERMISSION_CONTEXT: Tuple[str, ...] = (
+    "permission",
+    "denied",
+    "not granted",
+    "securityexception",
+    "security exception",
+    "not allowed",
+    "forbidden",
+    "unauthorized",
+    "requires",
+)
+
+#: Where Termux really lives. ``$PREFIX`` is not trusted on its own - many build
+#: systems export it - so the application data path is an independent signal.
+_TERMUX_BIN_DIR = "/data/data/com.termux/files/usr/bin"
+
+#: Default budget for one ``termux-*`` command, in seconds.
+DEFAULT_TIMEOUT = 6.0
+
+#: Wake-lock calls do not return data, so they get the same budget as anything else.
+WAKE_LOCK_TIMEOUT = 6.0
+
+#: The command inventory is a property of the install, not of the moment: a minute
+#: of caching keeps a chatty model from running 44 PATH lookups per tool call.
+_CACHE_TTL = 60.0
+
+#: How long one timeout counts as evidence that the Termux:API **app** is
+#: unreachable. Short on purpose: the operator may install the app, or Android may
+#: unfreeze it, at any moment, and stale evidence is worse than no evidence.
+APP_EVIDENCE_TTL = 120.0
+
+_ACQUIRE = "termux-wake-lock"
+_RELEASE = "termux-wake-unlock"
+_WAKE_ACTIONS: Dict[str, str] = {"acquire": _ACQUIRE, "release": _RELEASE}
+
+#: Windows: keep a console window from flashing for a phone command that cannot
+#: exist there anyway (the flag is 0 everywhere else).
+_POPEN_FLAGS = 0x08000000 if os.name == "nt" else 0
+
+_CACHE: Dict[str, Tuple[float, Dict[str, Any]]] = {}
+_CACHE_LOCK = threading.RLock()
+
+#: ``api_installed``/``capabilities`` caches and the observation-backed permission
+#: map are separate locks: a status call must not wait on a camera probe.
+_PERMISSIONS: Dict[str, str] = {name: "unknown" for name in PERMISSION_APIS}
+_PERMISSION_LOCK = threading.RLock()
+
+#: Is the Termux:API *app* answering? The commands can all exist while the app is
+#: missing, and then every one of them hangs: on a real phone that cost one
+#: timeout per telemetry section, so the node has to remember the shared cause
+#: instead of reporting five unrelated "timed out" blocks. Guarded by ``_CACHE_LOCK``
+#: because it is capability evidence, exactly like the cached blocks beside it.
+_APP_SUCCESS = False          #: a call has been answered since the last reset
+_APP_TIMEOUT_COMMAND = ""     #: which command last hung (kept for diagnostics)
+_APP_TIMEOUT_AT = 0.0         #: ``time.monotonic()`` of that hang
+
+#: How many times *this process* has taken the wake lock. Held across the command
+#: itself, because "exactly one acquire and one release" is the invariant Android
+#: cares about and a race between two threads would break it.
+_WAKE_COUNT = 0
+_WAKE_LOCK = threading.RLock()
+
+
+# ---------------------------------------------------------------------------
+# Seams: the two things tests replace, plus decoding
+# ---------------------------------------------------------------------------
+
+_DECODINGS: Optional[List[str]] = None
+
+
+def _windows_code_pages() -> List[str]:
+    """Code pages a Windows child may write with: OEM console CP first, then ANSI."""
+    pages: List[str] = []
+    try:
+        import ctypes
+
+        for getter in ("GetOEMCP", "GetACP"):
+            try:
+                code_page = int(getattr(ctypes.windll.kernel32, getter)())
+            except Exception:
+                continue
+            if code_page > 0:
+                pages.append("cp%d" % code_page)
+    except Exception:
+        pass
+    return pages
+
+
+def _decodings() -> List[str]:
+    """Encodings to try for captured child output, most likely first.
+
+    Order matters: every single-byte code page "succeeds" at decoding anything, so
+    UTF-8 (what Termux writes) has to be tried before the Windows OEM page (what
+    cmd.exe and the native console tools write) and before ANSI, the last resort.
+    """
+    global _DECODINGS
+    if _DECODINGS is not None:
+        return _DECODINGS
+    candidates = ["utf-8"]
+    if os.name == "nt":
+        candidates.extend(_windows_code_pages())
+    else:
+        try:
+            candidates.append(_locale.getpreferredencoding(False))
+        except Exception:
+            pass
+    candidates.append("cp1252")
+    unique: List[str] = []
+    seen = set()
+    for name in candidates:
+        if not name:
+            continue
+        key = name.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(name)
+    _DECODINGS = unique
+    return unique
+
+
+def _decode(data: Any) -> str:
+    """Decode captured bytes without mojibake, with line endings normalised.
+
+    A stray ``\\r`` would end up inside a path or a JSON key on the way back to a
+    model, so ``\\r\\n`` and lone ``\\r`` both become ``\\n`` here rather than in
+    every reader.
+    """
+    if data is None:
+        return ""
+    if isinstance(data, str):
+        return data.replace("\r\n", "\n").replace("\r", "\n").strip()
+    if isinstance(data, (bytes, bytearray)):
+        for encoding in _decodings():
+            try:
+                return (bytes(data).decode(encoding).replace("\r\n", "\n")
+                        .replace("\r", "\n").strip())
+            except (UnicodeDecodeError, LookupError):
+                continue
+        return bytes(data).decode("utf-8", "replace").replace("\r\n", "\n").replace("\r", "\n").strip()
+    return str(data).strip()
+
+
+def _which(name: str) -> Optional[str]:
+    """``shutil.which`` behind a seam, so tests never need a PATH shim."""
+    try:
+        return shutil.which(name)
+    except Exception:
+        return None
+
+
+def _run(argv: Sequence[str], timeout: float) -> Tuple[int, str]:
+    """Run one argv list: no shell, no stdin, and a hard timeout.
+
+    ``subprocess.TimeoutExpired`` is deliberately **not** swallowed here: this
+    module exists to explain a frozen Termux:API app, so the caller has to turn
+    that exception into a timeout answer instead of a silent empty result. Any
+    other failure to start the process is ``(-1, "")``, which the caller reports
+    as a reason.
+    """
+    try:
+        proc = subprocess.run(
+            list(argv),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=max(0.2, float(timeout)),
+            creationflags=_POPEN_FLAGS,
+        )
+    except subprocess.TimeoutExpired:
+        raise
+    except Exception:
+        return -1, ""
+    out = _decode(proc.stdout)
+    if proc.returncode != 0:
+        # A failing Termux:API command explains itself on stderr. On success stdout
+        # is the answer - and an empty stdout is a legitimate empty clipboard, so
+        # stderr is never substituted there.
+        return int(proc.returncode), (_decode(proc.stderr) or out)
+    return int(proc.returncode), out
+
+
+# ---------------------------------------------------------------------------
+# Platform detection and the command inventory
+# ---------------------------------------------------------------------------
+
+def is_android() -> bool:
+    """True only inside Termux on Android.
+
+    Three independent signals, any of which is enough: Termux exports
+    ``TERMUX_VERSION``, its ``$PREFIX`` points inside ``com.termux``, and its
+    application data directory has a fixed path. A generic ``PREFIX`` such as
+    ``/usr/local`` is not a signal - build systems export it everywhere.
+    """
+    try:
+        if os.environ.get("TERMUX_VERSION"):
+            return True
+        if "com.termux" in os.environ.get("PREFIX", ""):
+            return True
+        return os.path.isdir(_TERMUX_BIN_DIR)
+    except Exception:
+        return False
+
+
+def api_installed(refresh: bool = False) -> Dict[str, Any]:
+    """Which Termux:API commands this phone actually has, cached for a minute.
+
+    ``installed`` answers the only question a user asks ("is the API working?"),
+    which needs the mandatory trio; ``commands`` answers the one a model asks
+    ("may I try termux-sensor?"). ``refresh=True`` is for the moment right after
+    the installer ran ``pkg install termux-api``.
+    """
+    now = time.monotonic()
+    if not refresh:
+        with _CACHE_LOCK:
+            hit = _CACHE.get("api_installed")
+        if hit and hit[0] > now:
+            return hit[1]
+    try:
+        commands = {name: bool(_which(name)) for name in REQUIRED_COMMANDS}
+        missing = [name for name in REQUIRED_COMMANDS if not commands[name]]
+        report: Dict[str, Any] = {
+            "installed": all(commands.get(name, False) for name in MANDATORY_COMMANDS),
+            "commands": commands,
+            "missing": missing,
+            "fix": TERMUX_API_FIX,
+            "source": "shutil.which",
+        }
+    except Exception as exc:                     # a probe must never escape
+        report = {
+            "installed": False,
+            "commands": {name: False for name in REQUIRED_COMMANDS},
+            "missing": list(REQUIRED_COMMANDS),
+            "fix": TERMUX_API_FIX,
+            "source": "shutil.which",
+            "error": "%s: %s" % (type(exc).__name__, exc),
+        }
+    with _CACHE_LOCK:
+        _CACHE["api_installed"] = (now + _CACHE_TTL, report)
+    return report
+
+
+def _permission_snapshot() -> Dict[str, str]:
+    """A copy of the permission map: a caller must not be able to edit our state."""
+    with _PERMISSION_LOCK:
+        return {name: _PERMISSIONS.get(name, "unknown") for name in sorted(_PERMISSIONS)}
+
+
+def _command_exists(name: str) -> bool:
+    try:
+        return bool(_which(name))
+    except Exception:
+        return False
+
+
+def _wake_state() -> Dict[str, Any]:
+    """The in-process half of the wake-lock answer (``capabilities`` needs it)."""
+    available = _command_exists(_ACQUIRE)
+    with _WAKE_LOCK:
+        return {"command": available,
+                # None while the command is missing: a phone without the API
+                # cannot tell us whether a lock is held, and guessing would be
+                # worse than saying "unknown".
+                "held": (bool(_WAKE_COUNT > 0) if available else None),
+                "count": int(_WAKE_COUNT)}
+
+
+def _record_app_timeout(command: str) -> None:
+    """Remember that a ``termux-*`` call hung, which points at the app, not the package.
+
+    The cached capabilities block is dropped with it: a reader that still sees
+    ``app_reachable: True`` (or "unknown") would hide the observation that was just
+    made, and telling the operator once is the whole point of remembering it.
+    """
+    global _APP_TIMEOUT_AT, _APP_TIMEOUT_COMMAND
+    with _CACHE_LOCK:
+        _APP_TIMEOUT_COMMAND = str(command)
+        _APP_TIMEOUT_AT = time.monotonic()
+        _CACHE.pop("capabilities", None)
+
+
+def _record_app_success() -> None:
+    """An answered call disproves every earlier timeout, so drop that evidence."""
+    global _APP_SUCCESS, _APP_TIMEOUT_AT, _APP_TIMEOUT_COMMAND
+    with _CACHE_LOCK:
+        changed = (not _APP_SUCCESS) or bool(_APP_TIMEOUT_COMMAND)
+        _APP_SUCCESS = True
+        _APP_TIMEOUT_COMMAND = ""
+        _APP_TIMEOUT_AT = 0.0
+        if changed:
+            # Only when the answer actually changes: a working phone must not
+            # rebuild the capabilities block on every single successful call.
+            _CACHE.pop("capabilities", None)
+
+
+def _app_reachable() -> Optional[bool]:
+    """Is the Termux:API app answering? ``None`` means "no evidence either way".
+
+    A fresh node must not claim the app is broken, so the answer only becomes
+    ``False`` when the newest evidence is a *recent* hang. A record older than
+    :data:`APP_EVIDENCE_TTL` is no evidence at all, because the operator may have
+    installed or opened the app in the meantime.
+    """
+    now = time.monotonic()
+    with _CACHE_LOCK:
+        succeeded = _APP_SUCCESS
+        hung = bool(_APP_TIMEOUT_COMMAND)
+        hung_at = _APP_TIMEOUT_AT
+    if hung and (now - hung_at) <= APP_EVIDENCE_TTL:
+        return False
+    if succeeded:
+        return True
+    return None
+
+
+def capabilities(refresh: bool = False) -> Dict[str, Any]:
+    """A mergeable block for :mod:`core.device`'s capabilities section.
+
+    It answers what a model needs before it tries something: is the API there,
+    can the node reach shared storage, is a wake lock held, which permission a
+    *previous* call proved to be missing, and - the one shared cause behind a
+    phone whose every command hangs - whether the Termux:API **app** is
+    answering at all (``app_reachable``: ``True``/``False``/``None`` for "no
+    evidence", with ``app_fix`` present only when it is ``False``). Permission
+    states are reported, never probed - opening the camera to learn whether the
+    camera is allowed would be an unwanted side effect of a status call.
+    """
+    now = time.monotonic()
+    if not refresh:
+        with _CACHE_LOCK:
+            hit = _CACHE.get("capabilities")
+        if hit and hit[0] > now:
+            return hit[1]
+    value = _build_capabilities(refresh)
+    with _CACHE_LOCK:
+        _CACHE["capabilities"] = (now + _CACHE_TTL, value)
+    return value
+
+
+def _build_capabilities(refresh: bool) -> Dict[str, Any]:
+    fixes: List[str] = []
+    try:
+        api = api_installed(refresh=refresh)
+    except Exception as exc:
+        api = {"installed": False, "commands": {}, "missing": list(REQUIRED_COMMANDS),
+               "fix": TERMUX_API_FIX, "source": "shutil.which",
+               "error": "%s: %s" % (type(exc).__name__, exc)}
+    if not api.get("installed"):
+        fixes.append(TERMUX_API_FIX)
+
+    try:
+        storage_permission = bool(os.path.isdir(os.path.expanduser("~/storage/shared")))
+    except Exception:
+        storage_permission = False
+    if not storage_permission:
+        fixes.append(TERMUX_STORAGE_FIX)
+
+    wake = _wake_state()
+    if wake.get("command") is not True:
+        fixes.append(TERMUX_API_FIX)
+
+    permissions = _permission_snapshot()
+    for api_name in permissions:
+        if permissions[api_name] == "denied":
+            fixes.append(_permission_fix(api_name))
+
+    unique: List[str] = []
+    for fix in fixes:
+        if fix and fix not in unique:
+            unique.append(fix)
+    app_reachable = _app_reachable()
+    block: Dict[str, Any] = {
+        "api": api,
+        "storage_permission": storage_permission,
+        "wake_lock": wake,
+        "permissions": permissions,
+        "fixes": unique,
+        "app_reachable": app_reachable,
+    }
+    if app_reachable is False:
+        # Deliberately a key of its own rather than another entry in "fixes": the
+        # timeout fix is about the app, and a consumer merging this block into a
+        # device report has to be able to tell the two kinds of fix apart.
+        block["app_fix"] = TERMUX_TIMEOUT_FIX
+    return block
+
+
+# ---------------------------------------------------------------------------
+# Running one command
+# ---------------------------------------------------------------------------
+
+def _elapsed_ms(started: float) -> int:
+    return int(round((time.monotonic() - started) * 1000.0))
+
+
+def _failure(command: str, argv: Sequence[str], started: float, reason: str,
+             **fields: Any) -> Dict[str, Any]:
+    result: Dict[str, Any] = {
+        "ok": False,
+        "reason": reason,
+        "command": command,
+        "argv": list(argv),
+        "duration_ms": _elapsed_ms(started),
+    }
+    result.update(fields)
+    return result
+
+
+def _allowed(name: str) -> bool:
+    """The security guard: only bare ``termux-*`` command names may be executed.
+
+    A caller must never be able to turn a tool argument into an arbitrary
+    execution, so the prefix is checked *and* a path separator is refused -
+    ``termux-../../bin/sh`` satisfies the prefix while escaping the allowlist.
+    """
+    if not name.startswith("termux-"):
+        return False
+    return not any(separator in name for separator in ("/", "\\"))
+
+
+def _bounded(timeout: Any) -> float:
+    """A timeout that is always usable, whatever the caller passed."""
+    try:
+        return max(0.2, float(timeout))
+    except Exception:
+        return DEFAULT_TIMEOUT
+
+
+def _seconds(value: Any) -> float:
+    try:
+        return float(value)
+    except Exception:
+        return 0.0
+
+
+def run_json(command: str, args: Sequence[str] = (),
+             timeout: float = DEFAULT_TIMEOUT) -> Dict[str, Any]:
+    """Run one ``termux-*`` command and return its JSON answer as ``value``.
+
+    Non-JSON stdout is **not** an error: several commands (``termux-open``,
+    ``termux-toast``) answer with a sentence or with nothing at all, and a model
+    is better served by the text plus ``parsed: False`` than by a failure.
+    """
+    return _execute(command, args, timeout, parse=True)
+
+
+def run_text(command: str, args: Sequence[str] = (),
+             timeout: float = DEFAULT_TIMEOUT) -> Dict[str, Any]:
+    """Run one ``termux-*`` command and return its stdout as ``value``."""
+    return _execute(command, args, timeout, parse=False)
+
+
+def _execute(command: str, args: Sequence[str], timeout: float, parse: bool) -> Dict[str, Any]:
+    started = time.monotonic()
+    name = str(command or "")
+    if isinstance(args, (str, bytes)):
+        # A bare string is one argument, never a split on spaces: splitting is
+        # exactly the step that would turn caller text into extra options.
+        extra = [args if isinstance(args, str) else _decode(args)]
+    else:
+        try:
+            extra = [str(item) for item in (args or ())]
+        except Exception:
+            extra = []
+    argv = [name] + extra
+
+    if not _allowed(name):
+        return _failure(name, argv, started,
+                        "refused: %r is not a termux-* command" % name)
+
+    if not _command_exists(name):
+        # Nothing is executed when the command is absent: the failure itself is
+        # the answer, and running a "help" invocation would just be noise.
+        return _failure(name, argv, started,
+                        "the %s command is not installed" % name,
+                        missing=True, fix=TERMUX_API_FIX)
+
+    try:
+        rc, text = _run(argv, _bounded(timeout))
+    except subprocess.TimeoutExpired as exc:
+        # One hang is evidence about the app, not about this command: record it so
+        # the next capabilities() call can explain the whole phone at once.
+        _record_app_timeout(name)
+        fields: Dict[str, Any] = {"timeout": True, "fix": TERMUX_TIMEOUT_FIX}
+        partial = _decode(getattr(exc, "stdout", None) or getattr(exc, "stderr", None))
+        if partial:
+            fields["raw"] = partial
+        seconds = _seconds(getattr(exc, "timeout", None)) or _seconds(timeout)
+        return _failure(name, argv, started,
+                        "%s timed out after %gs" % (name, seconds), **fields)
+    except Exception as exc:
+        return _failure(name, argv, started,
+                        "%s could not be run: %s" % (name, exc))
+
+    # The seam may hand back text or bytes; normalising here keeps the contract of
+    # the result dict the same whichever way it arrived.
+    raw = _decode(text)
+    if rc != 0:
+        reason = raw.strip() or "%s exited with %d" % (name, rc)
+        fields = _diagnose(raw, name)
+        fields["raw"] = raw
+        return _failure(name, argv, started, reason, **fields)
+
+    value: Any = raw
+    extra_fields: Dict[str, Any] = {}
+    if parse:
+        try:
+            value = json.loads(raw)
+        except Exception:
+            value = raw
+            extra_fields["parsed"] = False
+    # A refused permission arrives as a SUCCESSFUL call: the app prints
+    # {"error": "Please grant the following permission to use this command: ..."}
+    # on stdout and exits 0. Reading only the exit code therefore turned "Android
+    # said no" into an empty answer - the model saw a phone with no cell data
+    # instead of a phone that needs one permission granted.
+    if isinstance(value, dict):
+        message = value.get("error")
+        if isinstance(message, str) and message.strip():
+            fields = _diagnose(message, name)
+            fields["raw"] = raw
+            return _failure(name, argv, started, message.strip(), **fields)
+    # Only an answered call counts. A non-zero exit is not proof that the app is
+    # alive - the honest reading of "the app is unreachable" is the one that
+    # requires positive evidence before it is cleared.
+    _record_app_success()
+    result: Dict[str, Any] = {
+        "ok": True,
+        "value": value,
+        "raw": raw,
+        "command": name,
+        "argv": argv,
+        "duration_ms": _elapsed_ms(started),
+    }
+    result.update(extra_fields)
+    return result
+
+
+def sensor_sample(name: str, timeout: float = 8.0) -> Dict[str, Any]:
+    """One value from one named sensor.
+
+    ``-n 1`` is built here and can never come from the caller: without it
+    ``termux-sensor`` streams samples until it is killed, so a model asking for a
+    single reading would hold the tool open until its own timeout expires.
+    """
+    sensor = str(name or "").strip()
+    return run_json("termux-sensor", ["-s", sensor, "-n", "1"], timeout)
+
+
+# ---------------------------------------------------------------------------
+# Failure text -> a fix and a remembered permission
+# ---------------------------------------------------------------------------
+
+def _permission_fix(api: str) -> str:
+    return ("grant the %s permission to Termux:API in Android Settings > Apps > "
+            "Termux:API > Permissions" % api)
+
+
+def _api_name(api: str) -> str:
+    """Normalise a permission name, accepting a command name as a shorthand."""
+    name = str(api or "").strip().lower()
+    if not name:
+        return ""
+    return _COMMAND_API.get(name, name)
+
+
+def record_permission_state(api: str, state: str) -> None:
+    """Remember what a real call proved about one Android permission.
+
+    Only an observed call may call this: asking Android up front would mean
+    opening the camera or the microphone to read a state, which is the side
+    effect this module refuses to have. The cached capabilities block is dropped
+    with it, so the next reader sees the new fact instead of a stale "unknown".
+    """
+    name = _api_name(api)
+    wanted = str(state or "").strip().lower()
+    if not name or wanted not in ("granted", "denied", "unknown"):
+        return
+    with _PERMISSION_LOCK:
+        _PERMISSIONS[name] = wanted
+    with _CACHE_LOCK:
+        _CACHE.pop("capabilities", None)
+
+
+def _diagnose(text: str, command: str = "") -> Dict[str, Any]:
+    """Map a failing command's output to ``denied``/``fix`` and remember it.
+
+    All of the "Android said no" vocabulary lives in this one function, so a new
+    permission-backed command only has to be added to ``_COMMAND_API`` to be
+    explained properly. An empty dict means "no permission story here" and lets
+    the caller report the raw text unchanged.
+    """
+    lowered = (text or "").lower()
+    if not lowered:
+        return {}
+    denied = any(phrase in lowered for phrase in _PERMISSION_PHRASES)
+    if not denied and "camera" in lowered:
+        denied = any(word in lowered for word in _PERMISSION_CONTEXT)
+    if not denied and any(word in lowered for word in ("microphone", "audio record", "recording")):
+        denied = any(word in lowered for word in _PERMISSION_CONTEXT)
+    if not denied:
+        return {}
+    # The text is the more specific evidence, so it is read first: a command that
+    # names a permission in its own message is believed over the command map.
+    api = ""
+    if "camera" in lowered or "/dev/video" in lowered:
+        api = "camera"
+    elif any(word in lowered for word in ("microphone", "audio record", "recording")):
+        api = "microphone"
+    elif "location" in lowered:
+        api = "location"
+    if not api:
+        api = _COMMAND_API.get(str(command or ""), "")
+    fields: Dict[str, Any] = {"denied": True, "fix": _permission_fix(api or "requested")}
+    if api:
+        record_permission_state(api, "denied")
+    return fields
+
+
+# ---------------------------------------------------------------------------
+# Wake lock
+# ---------------------------------------------------------------------------
+
+def _wake_report(command: str, available: bool, reason: str = "",
+                 **fields: Any) -> Dict[str, Any]:
+    report: Dict[str, Any] = {
+        "available": bool(available),
+        # ``held`` is None while the command is missing: the honest answer is
+        # "unknown", because a phone without the API cannot tell us either way.
+        "held": (bool(_WAKE_COUNT > 0) if available else None),
+        "count": int(_WAKE_COUNT),
+        "command": command,
+    }
+    if reason:
+        report["reason"] = reason
+    report.update(fields)
+    return report
+
+
+def wake_lock(action: str = "status") -> Dict[str, Any]:
+    """Take, drop or report the Android wake lock, reference counted in process.
+
+    Android freezes a background process once the screen goes off, and the node's
+    install-time boot script takes the lock exactly once with nobody left to
+    release it. Counting the lock here means the system command runs only when the
+    lock really changes state - once on the way up (0 -> 1) and once on the way
+    down (1 -> 0) - so ``acquire`` twice and ``release`` twice still touch Android
+    once each, and the count can never go below zero. There is no "is a lock
+    held?" command in Termux:API, so ``held`` describes *this process's* count -
+    the only truth available without root.
+    """
+    global _WAKE_COUNT
+    wanted = str(action or "status").strip().lower()
+    if wanted not in _WAKE_ACTIONS and wanted != "status":
+        with _WAKE_LOCK:
+            count = _WAKE_COUNT
+        return {"available": False, "held": None, "count": int(count), "command": "",
+                "reason": "refused: %r is not a wake-lock action" % (str(action),)}
+
+    with _WAKE_LOCK:
+        if wanted == "status":
+            # No status command exists, so nothing may be executed here - running
+            # the lock command to "check" would change the state it reports.
+            return _wake_report(_ACQUIRE, _command_exists(_ACQUIRE))
+
+        command = _WAKE_ACTIONS[wanted]
+        if wanted == "acquire" and _WAKE_COUNT > 0:
+            # Already held by this process: Android counts the lock, not the calls,
+            # so a second acquire only moves our own counter.
+            _WAKE_COUNT += 1
+            return _wake_report(command, True)
+        if wanted == "release":
+            if _WAKE_COUNT == 0:
+                # Nothing of ours is held: unlocking now would drop a lock some
+                # other app took, and the ref-count is the only thing that can know.
+                return _wake_report(command, _command_exists(command))
+            if _WAKE_COUNT > 1:
+                # Other holders remain, so the system lock must stay taken.
+                _WAKE_COUNT -= 1
+                return _wake_report(command, True)
+
+        if not _command_exists(command):
+            return _wake_report(command, False,
+                                "the %s command is not installed" % command,
+                                missing=True, fix=TERMUX_API_FIX)
+
+        try:
+            rc, text = _run([command], WAKE_LOCK_TIMEOUT)
+        except subprocess.TimeoutExpired as exc:
+            seconds = _seconds(getattr(exc, "timeout", None)) or WAKE_LOCK_TIMEOUT
+            return _wake_report(command, True,
+                                "%s timed out after %gs" % (command, seconds),
+                                timeout=True, fix=TERMUX_TIMEOUT_FIX)
+        except Exception as exc:
+            return _wake_report(command, True, "%s could not be run: %s" % (command, exc))
+
+        if rc != 0:
+            fields = _diagnose(text, command)
+            reason = (text or "").strip() or "%s exited with %d" % (command, rc)
+            return _wake_report(command, True, reason, **fields)
+
+        if wanted == "acquire":
+            _WAKE_COUNT += 1
+        else:
+            # Only a command that really ran gives the count back; a failed unlock
+            # leaves the lock held, which is what the phone still believes.
+            _WAKE_COUNT = max(0, _WAKE_COUNT - 1)
+        return _wake_report(command, True)
+
+
+# ---------------------------------------------------------------------------
+# Test seam
+# ---------------------------------------------------------------------------
+
+def reset_state() -> None:
+    """Drop every in-process cache: the inventory, capabilities, the lock count,
+    the permission map and the app evidence, as if this module had just been
+    imported."""
+    global _WAKE_COUNT, _APP_SUCCESS, _APP_TIMEOUT_AT, _APP_TIMEOUT_COMMAND
+    with _CACHE_LOCK:
+        _CACHE.clear()
+        _APP_SUCCESS = False
+        _APP_TIMEOUT_COMMAND = ""
+        _APP_TIMEOUT_AT = 0.0
+    with _PERMISSION_LOCK:
+        _PERMISSIONS.clear()
+        _PERMISSIONS.update({name: "unknown" for name in PERMISSION_APIS})
+    with _WAKE_LOCK:
+        _WAKE_COUNT = 0