nexus-android 0.4.1__py3-none-any.whl

nexus_android/__init__.py

@@ -0,0 +1,3 @@
+"""nexus-android : computer use du téléphone Android de l'utilisateur, partagé par ses agents."""
+
+__version__ = "0.4.1"

nexus_android/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

nexus_android/adb.py

@@ -0,0 +1,323 @@
+"""Liaison ADB avec le téléphone : choix de l'appareil (USB d'abord, puis Wi-Fi jumelé), commandes shell, captures."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class PhoneError(RuntimeError):
+    """Erreur à rapporter telle quelle à l'agent (message en français, sans pile)."""
+
+
+class LinkError(PhoneError):
+    """Liaison perdue en cours de commande (délai dépassé, téléphone parti) : la commande a pu s'exécuter ou non.
+    Un geste ainsi interrompu a un effet inconnu ; il se relit avant d'être refait, jamais répété à l'aveugle."""
+
+
+# Erreurs d'adb sur l'appareil lui-même, pas sur la commande (« sh: foo: not found » n'en est pas une).
+_LINK_LOST = re.compile(r"^(?:adb(?:\.exe)?: )?(?:error: )?(?:device .*not found|device offline|no devices|closed|"
+                        r"protocol fault)", re.I | re.M)
+
+def _find_adb() -> str:
+    explicit = os.environ.get("NEXUS_ANDROID_ADB")
+    if explicit and Path(explicit).is_file():
+        return explicit
+    found = shutil.which("adb")
+    if found:
+        return found
+    winget = Path(os.environ.get("LOCALAPPDATA", "")) / "Microsoft" / "WinGet" / "Packages"
+    for candidate in winget.glob("Google.PlatformTools_*/platform-tools/adb.exe"):
+        return str(candidate)
+    raise PhoneError("adb introuvable : installer les Platform Tools (winget install Google.PlatformTools).")
+
+
+@dataclass(frozen=True)
+class Device:
+    serial: str
+    state: str
+    model: str
+    transport: str  # "usb" ou "wifi"
+
+
+def parse_devices(output: str) -> list[Device]:
+    devices = []
+    for line in output.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        serial, state = parts[0], parts[1]
+        model = next((p.split(":", 1)[1] for p in parts[2:] if p.startswith("model:")), "")
+        wifi = ":" in serial or "._adb-tls-connect." in serial
+        devices.append(Device(serial, state, model.replace("_", "-"), "wifi" if wifi else "usb"))
+    return devices
+
+
+def parse_mdns(output: str) -> list[str]:
+    """Adresses ip:port des téléphones jumelés annoncés sur le Wi-Fi (débogage sans fil)."""
+    return re.findall(r"_adb-tls-connect\._tcp\.?\s+(\d+\.\d+\.\d+\.\d+:\d+)", output)
+
+
+def parse_adbd_port(proc_net: str) -> int | None:
+    """Port TCP en écoute d'adbd (utilisateur shell, uid 2000) dans /proc/net/tcp6 et /proc/net/tcp."""
+    for line in proc_net.splitlines():
+        fields = line.split()
+        if len(fields) > 7 and fields[3] == "0A" and fields[7] == "2000":
+            port = int(fields[1].rsplit(":", 1)[1], 16)
+            if port != 5037:
+                return port
+    return None
+
+
+WIFI_STATE = Path.home() / ".nexus" / "nexus-android" / "wifi.json"
+TLS_PORTS = range(30000, 50000)  # plage des ports aléatoires du débogage sans fil
+
+
+def open_ports(host: str, ports: range = TLS_PORTS, timeout: float = 0.4) -> list[int]:
+    """Ports TCP ouverts sur le téléphone : le port du débogage sans fil change quand adbd redémarre (câble
+    retiré, veille), et One UI ne l'annonce pas en mDNS."""
+
+    async def scan() -> list[int]:
+        gate = asyncio.Semaphore(800)
+        found: list[int] = []
+
+        async def probe(port: int) -> None:
+            async with gate:
+                try:
+                    _, writer = await asyncio.wait_for(asyncio.open_connection(host, port), timeout)
+                    found.append(port)
+                    writer.close()
+                except (OSError, TimeoutError):
+                    pass
+
+        await asyncio.gather(*(probe(p) for p in ports))
+        return sorted(found)
+
+    return asyncio.run(scan())
+
+
+class Adb:
+    def __init__(self) -> None:
+        self.path = _find_adb()
+        self.forced: str | None = os.environ.get("NEXUS_ANDROID_SERIAL") or None  # appareil imposé à l'installation
+        self.serial: str | None = self.forced
+        self._ids: dict[str, str] = {}  # numéro adb → ro.serialno (identité réelle de l'appareil)
+        self.rebooted = False  # le téléphone a redémarré depuis le dernier contact (à dire une fois, puis False)
+
+    def _raw(self, args: list[str], timeout: float = 30.0, serial: bool = True) -> subprocess.CompletedProcess[bytes]:
+        cmd = [self.path]
+        if serial and self.serial:
+            cmd += ["-s", self.serial]
+        try:
+            return subprocess.run(cmd + args, capture_output=True, timeout=timeout,
+                                  creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
+        except subprocess.TimeoutExpired as e:
+            raise LinkError(f"adb {' '.join(args[:2])} : pas de réponse après {timeout:.0f} s.") from e
+
+    def devices(self) -> list[Device]:
+        return parse_devices(self._raw(["devices", "-l"], serial=False).stdout.decode("utf-8", "replace"))
+
+    def _online(self) -> list[Device]:
+        """Appareils prêts, émulateurs exclus (jamais pris pour le téléphone de l'utilisateur)."""
+        return [d for d in self.devices() if d.state == "device" and not d.serial.startswith("emulator-")]
+
+    def _remembered(self) -> dict:
+        try:
+            return json.loads(WIFI_STATE.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+
+    def _save(self, state: dict) -> None:
+        WIFI_STATE.parent.mkdir(parents=True, exist_ok=True)
+        WIFI_STATE.write_text(json.dumps(state), encoding="utf-8")
+
+    def identity(self, serial: str) -> str:
+        """Numéro de série matériel (ro.serialno) de l'appareil joint sous ce numéro adb ; "" s'il ne répond pas."""
+        if serial not in self._ids:
+            try:
+                out = self._raw(["-s", serial, "shell", "getprop", "ro.serialno"], timeout=8, serial=False)
+            except PhoneError:
+                return ""
+            ident = out.stdout.decode("utf-8", "replace").strip() if not out.returncode else ""
+            if not ident:
+                return ""
+            self._ids[serial] = ident
+        return self._ids[serial]
+
+    def _remember_wifi(self, serial: str, ident: str) -> None:
+        """Branché en USB : note l'identité du téléphone, son adresse Wi-Fi et le port TLS d'adbd, que le téléphone
+        (One UI) n'annonce pas en mDNS. Le port ne change qu'au redémarrage du débogage sans fil (reboot, autre
+        réseau). Appelé seulement pour le téléphone de l'utilisateur, identité vérifiée."""
+        run = lambda *a: self._raw(["-s", serial, "shell", *a], serial=False).stdout.decode("utf-8", "replace")  # noqa: E731
+        before = self._remembered()
+        state = {**before, "serialno": ident, "usb": serial}
+        ip = re.search(r"inet (\d+\.\d+\.\d+\.\d+)/", run("ip", "-4", "addr", "show", "wlan0"))
+        port = parse_adbd_port(run("cat", "/proc/net/tcp6", "/proc/net/tcp"))
+        if ip and port:
+            state["address"] = f"{ip.group(1)}:{port}"
+        if state != before:
+            self._save(state)
+
+    def _try_wifi(self, address: str, known: str) -> bool:
+        """Se connecte à une adresse Wi-Fi ; garde la liaison seulement si c'est le téléphone de l'utilisateur."""
+        try:
+            out = self._raw(["connect", address], timeout=8, serial=False).stdout
+        except PhoneError:  # adresse périmée (port changé) : ne pas empêcher d'essayer les suivantes
+            self._raw(["disconnect", address], timeout=5, serial=False)
+            return False
+        if b"connected to" not in out:
+            return False
+        if self.identity(address) == known:
+            return True
+        self._raw(["disconnect", address], timeout=5, serial=False)  # autre appareil du réseau (box TV…)
+        return False
+
+    def connect(self) -> Device:
+        """Choisit le téléphone de l'utilisateur : celui imposé, sinon USB, sinon Wi-Fi ; tente les téléphones jumelés du
+        Wi-Fi (annonce mDNS, puis dernière adresse notée lors d'un branchement USB). Seul l'appareil dont le numéro
+        de série matériel est celui noté au premier branchement USB est accepté ; émulateurs et autres appareils
+        du réseau sont écartés, et wifi.json n'est jamais réécrit avec un autre appareil."""
+        if self.forced:
+            return self._connect_forced(self.forced)
+        remembered = self._remembered()
+        known = remembered.get("serialno") or remembered.get("usb") or ""  # "usb" : fichier d'avant l'identité
+        mine = self._mine(self._online(), known)
+        if not mine and any(d.state == "offline" for d in self.devices()):
+            # Liaison Wi-Fi endormie (« device offline », vu sur le Fold) : la relancer avant de chercher ailleurs.
+            self._raw(["reconnect", "offline"], timeout=10, serial=False)
+            for _ in range(10):
+                time.sleep(0.5)
+                if mine := self._mine(self._online(), known):
+                    break
+        if not mine and known:
+            mdns =self._raw(["mdns", "services"], timeout=10, serial=False).stdout.decode("utf-8", "replace")
+            for address in dict.fromkeys(parse_mdns(mdns) + ([remembered["address"]] if remembered.get("address") else [])):
+                if self._try_wifi(address, known):
+                    break
+            mine = self._mine(self._online(), known)
+            if not mine and remembered.get("address"):
+                host = remembered["address"].rsplit(":", 1)[0]
+                for port in open_ports(host):
+                    if self._try_wifi(f"{host}:{port}", known):
+                        break
+                mine = self._mine(self._online(), known)
+        if not mine:
+            self.serial = None
+            raise PhoneError(self._missing(known))
+        chosen = sorted(mine, key=lambda d: d.transport != "usb")[0]
+        ident = self.identity(chosen.serial)
+        if chosen.transport == "usb":
+            try:
+                self._remember_wifi(chosen.serial, ident)
+            except (OSError, PhoneError):
+                pass
+        elif re.fullmatch(r"\d+\.\d+\.\d+\.\d+:\d+", chosen.serial) and chosen.serial != remembered.get("address"):
+            self._save({**remembered, "serialno": ident, "address": chosen.serial})  # port du débogage sans fil changé
+        self.serial = chosen.serial
+        self._note_boot()
+        return chosen
+
+    def _note_boot(self) -> None:
+        """Redémarrage du téléphone depuis le dernier contact de ce PC : signalé une fois (rebooted)."""
+        try:
+            boot = self.boot_id()
+        except PhoneError:
+            return
+        state = self._remembered()
+        if not re.fullmatch(r"[0-9a-f-]{36}", boot) or boot == state.get("boot_id"):
+            return
+        self.rebooted = bool(state.get("boot_id"))
+        self._save({**state, "boot_id": boot})
+
+    def _mine(self, devices: list[Device], known: str) -> list[Device]:
+        if known:
+            return [d for d in devices if self.identity(d.serial) == known]
+        # Jamais branché : le téléphone en USB devient celui de l'utilisateur (le câble est un geste volontaire).
+        usb = [d for d in devices if d.transport == "usb" and self.identity(d.serial)]
+        if len(usb) > 1:
+            raise PhoneError("Plusieurs appareils en USB (" + ", ".join(d.model or d.serial for d in usb) + ") et aucun "
+                             "téléphone encore enregistré : ne laisser branché que le téléphone de l'utilisateur.")
+        return usb
+
+    def _missing(self, known: str) -> str:
+        visible = self.devices()
+        if any(d.state == "unauthorized" for d in visible):
+            return "Téléphone branché mais non autorisé : accepter « Autoriser le débogage » sur l'écran."
+        others = [d.model or d.serial for d in visible if d.state == "device"]
+        ignored = f" Appareils visibles écartés (pas le téléphone de l'utilisateur) : {', '.join(others)}." if others else ""
+        if not known:
+            return ("Téléphone de l'utilisateur pas encore enregistré sur ce PC : le brancher une fois en USB (débogage USB "
+                    "autorisé) ; il sera ensuite retrouvé aussi en Wi-Fi." + ignored)
+        return (f"Téléphone de l'utilisateur (n° de série {known}) introuvable : brancher le câble USB, ou activer le débogage "
+                "sans fil (téléphone jumelé à ce PC et sur le même Wi-Fi). Après un redémarrage du téléphone ou un "
+                "changement de réseau, Android coupe le débogage sans fil : le rallumer (Options de développement) "
+                "ou brancher le câble une fois." + ignored)
+
+    def _connect_forced(self, serial: str) -> Device:
+        """NEXUS_ANDROID_SERIAL : appareil choisi explicitement à l'installation, pris tel quel."""
+        devices = [d for d in self.devices() if d.state == "device"]
+        if ":" in serial and all(d.serial != serial for d in devices):
+            self._raw(["connect", serial], timeout=8, serial=False)  # adresse Wi-Fi imposée
+            devices = [d for d in self.devices() if d.state == "device"]
+        chosen = next((d for d in devices if d.serial == serial), None)
+        if not chosen:
+            raise PhoneError(f"Appareil imposé par NEXUS_ANDROID_SERIAL ({serial}) injoignable.")
+        self.serial = serial
+        return chosen
+
+    def run(self, *argv: str, timeout: float = 30.0) -> tuple[int, str, str]:
+        """Commande shell Android : (code, sortie, erreurs). Chaque argument est protégé (texte libre, accents)."""
+        if not self.serial:
+            self.connect()
+        command = " ".join(shlex.quote(a) for a in argv)
+        result = self._raw(["shell", command], timeout=timeout)
+        out = result.stdout.decode("utf-8", "replace").replace("\r\n", "\n")
+        err = result.stderr.decode("utf-8", "replace").strip()
+        if result.returncode and _LINK_LOST.search(err):
+            self.serial = self.forced  # téléphone perdu : le rechercher au prochain appel
+            raise LinkError(f"liaison perdue avec le téléphone ({err.splitlines()[0][:120]})")
+        return result.returncode, out, err
+
+    def host(self, *args: str, timeout: float = 60.0) -> str:
+        """Commande adb côté PC sur le téléphone choisi (push, pull, forward) ; erreur → PhoneError."""
+        if not self.serial:
+            self.connect()
+        result = self._raw(list(args), timeout=timeout)
+        out = (result.stdout + result.stderr).decode("utf-8", "replace").strip()
+        if result.returncode:
+            if _LINK_LOST.search(out):
+                self.serial = self.forced
+                raise LinkError(f"liaison perdue avec le téléphone ({out.splitlines()[0][:120]})")
+            raise PhoneError(f"adb {args[0]} : {out[:300]}")
+        return out
+
+    def boot_id(self) -> str:
+        """Identifiant du démarrage en cours du téléphone (change à chaque redémarrage)."""
+        return self.shell("cat", "/proc/sys/kernel/random/boot_id", check=False).strip()
+
+    def shell(self, *argv: str, timeout: float = 30.0, check: bool = True) -> str:
+        """Commande shell Android ; chaque argument est protégé (texte libre, accents, retours à la ligne)."""
+        code, out, err = self.run(*argv, timeout=timeout)
+        if code and check:
+            raise PhoneError(f"{argv[0]} : {(err or out).strip()[:300]}")
+        return out
+
+    def exec_out(self, *argv: str, timeout: float = 30.0) -> bytes:
+        if not self.serial:
+            self.connect()
+        result = self._raw(["exec-out", " ".join(shlex.quote(a) for a in argv)], timeout=timeout)
+        if result.returncode:
+            err = result.stderr.decode("utf-8", "replace").strip()
+            if _LINK_LOST.search(err):
+                self.serial = self.forced
+                raise LinkError(f"liaison perdue avec le téléphone ({err.splitlines()[0][:120]})")
+            raise PhoneError(err[:300] or "exec-out a échoué")
+        return result.stdout

nexus_android/awake.py

@@ -0,0 +1,128 @@
+"""Écran gardé allumé pendant le pilotage : au premier geste sur un téléphone déverrouillé, la mise en veille
+(screen_off_timeout) est montée à 30 min ; après IDLE secondes sans geste d'aucun agent, la valeur d'origine est
+remise et l'écran éteint (ce qui reverrouille). Jamais de déverrouillage : c'est toujours l'utilisateur qui le fait.
+
+L'état est commun aux serveurs des trois agents (AWAKE_STATE, hors des sources) et ne se lit ni ne s'écrit que sous
+PhoneLock : une seule sauvegarde de la valeur d'origine, une seule restauration. Après un plantage, le prochain serveur
+qui démarre restaure la valeur d'origine dès que la session a expiré."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from pathlib import Path
+
+from .adb import Adb, PhoneError
+
+AWAKE_STATE = Path.home() / ".nexus" / "nexus-android" / "awake.json"
+RAISED = 30 * 60 * 1000  # ms : écran gardé allumé pendant le travail de l'agent
+IDLE = float(os.environ.get("NEXUS_ANDROID_AWAKE_IDLE") or 120)  # secondes sans geste avant de rendre la main
+ENABLED = os.environ.get("NEXUS_ANDROID_KEEP_AWAKE", "1") != "0"
+OWNER_MARGIN = 5.0  # s : activité plus récente que le dernier geste de l'agent = l'utilisateur utilise le téléphone
+
+
+def _load(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _save(path: Path, state: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(state), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _timeout(adb: Adb) -> int | None:
+    value = adb.shell("settings", "get", "system", "screen_off_timeout", check=False).strip()
+    return int(value) if value.isdigit() else None
+
+
+def idle_on_phone(adb: Adb) -> float | None:
+    """Secondes depuis la dernière activité sur le téléphone (toucher de l'utilisateur ou geste injecté), d'après dumpsys."""
+    match = re.search(r"^\s*lastUserActivityTime=\d+ \((\d+) ms ago\)", adb.shell("dumpsys", "power", check=False), re.M)
+    return int(match.group(1)) / 1000 if match else None
+
+
+class KeepAwake:
+    """À appeler sous PhoneLock (état partagé entre processus)."""
+
+    def __init__(self, adb: Adb, path: Path | None = None, idle: float | None = None,
+                 clock=time.time) -> None:
+        self.adb = adb
+        self.path = path or AWAKE_STATE
+        self.idle = IDLE if idle is None else idle
+        self.clock = clock
+
+    def state(self) -> dict:
+        return _load(self.path)
+
+    def active_until(self) -> float | None:
+        """Heure (epoch) à laquelle l'écran sera rendu, si une session est en cours."""
+        state = self.state()
+        return state["last"] + self.idle if state.get("active") else None
+
+    def _phone(self) -> str:
+        serial = getattr(self.adb, "serial", None)
+        return self.adb.identity(serial) if serial else ""
+
+    def touch(self) -> None:
+        """Geste sur un téléphone déverrouillé : ouvre la session (sauvegarde puis montée) ou la prolonge."""
+        state = self.state()
+        now = self.clock()
+        if state.get("active"):
+            if _timeout(self.adb) != RAISED:  # remise à zéro entre-temps (utilisateur, redémarrage) : la remonter
+                self.adb.shell("settings", "put", "system", "screen_off_timeout", str(RAISED))
+            _save(self.path, {**state, "last": now, "pid": os.getpid()})
+            return
+        current = _timeout(self.adb)
+        if current is None:
+            raise PhoneError("mise en veille illisible (settings) : écran non gardé allumé")
+        # Jamais la valeur montée prise pour l'origine (session perdue) : dernière origine connue, sinon 30 s.
+        original = current if current != RAISED else int(state.get("original") or 30000)
+        _save(self.path, {"active": True, "original": original, "phone": self._phone(), "start": now, "last": now,
+                          "pid": os.getpid()})
+        self.adb.shell("settings", "put", "system", "screen_off_timeout", str(RAISED))
+
+    def extend(self) -> None:
+        """Lecture de l'écran (look) pendant une session : la prolonge sans en ouvrir une."""
+        state = self.state()
+        if state.get("active"):
+            _save(self.path, {**state, "last": self.clock()})
+
+    def due(self) -> float | None:
+        """Secondes avant la restauration (0 : à faire maintenant) ; None : aucune session."""
+        until = self.active_until()
+        return None if until is None else max(0.0, until - self.clock())
+
+    def restore(self, force: bool = False) -> str | None:
+        """Session expirée (ou force) : remet la valeur d'origine puis éteint l'écran, sauf si l'utilisateur utilise le
+        téléphone. Renvoie ce qui a été fait, None si rien à faire."""
+        state = self.state()
+        if not state.get("active"):
+            return None
+        idle_for = self.clock() - state["last"]
+        if not force and idle_for < self.idle:
+            return None
+        if state.get("phone") and self._phone() and state["phone"] != self._phone():
+            return None  # autre appareil joint : rien à toucher sur celui-ci
+        current = _timeout(self.adb)
+        done = []
+        if current == RAISED:
+            self.adb.shell("settings", "put", "system", "screen_off_timeout", str(state["original"]))
+            done.append(f"mise en veille remise à {state['original'] // 1000} s")
+        else:
+            done.append("mise en veille déjà changée sur le téléphone, laissée telle quelle")
+        _save(self.path, {"active": False, "original": state["original"], "phone": state.get("phone", ""),
+                          "restored": self.clock()})
+        phone_idle = idle_on_phone(self.adb)
+        if current == RAISED and (phone_idle is None or phone_idle >= idle_for - OWNER_MARGIN):
+            self.adb.shell("input", "keyevent", "KEYCODE_SLEEP")
+            done.append("écran éteint")
+        else:
+            done.append("écran laissé à l'utilisateur (il s'en sert)")
+        return ", ".join(done)

nexus_android/clip.py

@@ -0,0 +1,152 @@
+"""Saisie de tout texte (accents, emoji) par le presse-papiers : `input text` d'Android n'accepte que l'ASCII.
+
+Le serveur de scrcpy (Genymobile, Apache 2.0) tourne le temps de la saisie sous l'identité shell, sans vidéo ni son,
+avec son seul canal de contrôle : il lit le presse-papiers de l'utilisateur, y met le texte et le colle dans le champ actif,
+puis remet l'ancien contenu (vide s'il était vide). Méthode vérifiée sur un Galaxy Fold.
+Le serveur s'arrête à la fin de chaque saisie : aucun programme d'aide ne reste sur le téléphone."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import random
+import socket
+import struct
+import subprocess
+import time
+from pathlib import Path
+
+from .adb import Adb, LinkError, PhoneError
+
+VERSION = "5.0.1"
+SHA256 = "764eb6f79811d5211fe9df341120882ba9994c7a61b897d7bf3fb662e53bc536"  # digest publié par GitHub pour la v5.0.1
+LOCAL = Path.home() / ".nexus" / "nexus-android" / "tools" / f"scrcpy-server-v{VERSION}"  # posé par install.ps1
+REMOTE = "/data/local/tmp/nexus-scrcpy.jar"
+GET_CLIPBOARD, SET_CLIPBOARD = 8, 9  # messages de contrôle (ControlMessage.java)
+CLIPBOARD, ACK_CLIPBOARD = 0, 1  # messages du téléphone (DeviceMessage.java)
+MAX_BYTES = 256 * 1024 - 14  # CLIPBOARD_TEXT_MAX_LENGTH du serveur
+
+
+def set_message(sequence: int, text: str, paste: bool) -> bytes:
+    data = text.encode("utf-8")
+    return struct.pack(">BQBI", SET_CLIPBOARD, sequence, int(paste), len(data)) + data
+
+
+class Channel:
+    """Canal de contrôle d'un serveur scrcpy (socket déjà connecté)."""
+
+    def __init__(self, sock: socket.socket) -> None:
+        self.sock = sock
+
+    def _read(self, n: int) -> bytes:
+        data = b""
+        while len(data) < n:
+            chunk = self.sock.recv(n - len(data))
+            if not chunk:
+                raise PhoneError("presse-papiers : le téléphone a fermé le canal")
+            data += chunk
+        return data
+
+    def get(self, wait: float = 1.5) -> str | None:
+        """Texte du presse-papiers ; None s'il est vide (le serveur ne répond alors rien)."""
+        self.sock.sendall(bytes([GET_CLIPBOARD, 0]))
+        self.sock.settimeout(wait)
+        try:
+            kind = self._read(1)[0]
+        except TimeoutError:
+            return None
+        finally:
+            self.sock.settimeout(5)
+        if kind != CLIPBOARD:
+            raise PhoneError(f"presse-papiers : réponse inattendue ({kind})")
+        return self._read(struct.unpack(">I", self._read(4))[0]).decode("utf-8", "replace")
+
+    def set(self, sequence: int, text: str, paste: bool) -> None:
+        """Met le texte dans le presse-papiers (et le colle si paste) ; attend l'accusé de réception."""
+        self.sock.sendall(set_message(sequence, text, paste))
+        while True:
+            kind = self._read(1)[0]
+            if kind == ACK_CLIPBOARD and struct.unpack(">Q", self._read(8))[0] == sequence:
+                return
+            if kind == CLIPBOARD:  # copie faite entre-temps sur le téléphone : lue et ignorée
+                self._read(struct.unpack(">I", self._read(4))[0])
+                continue
+            raise PhoneError(f"presse-papiers : réponse inattendue ({kind})")
+
+
+def _ensure_server(adb: Adb) -> None:
+    if not LOCAL.is_file() or hashlib.sha256(LOCAL.read_bytes()).hexdigest() != SHA256:
+        raise PhoneError("Saisie avec accents indisponible : serveur scrcpy absent du PC ou altéré (lancer "
+                         "install.ps1). Pour un message : draft(to, text).")
+    size = adb.shell("stat", "-c", "%s", REMOTE, check=False).strip()
+    if size != str(LOCAL.stat().st_size):
+        adb.host("push", str(LOCAL), REMOTE)
+
+
+def paste(adb: Adb, text: str) -> bool:
+    """Colle `text` dans le champ qui a le focus, puis rend à l'utilisateur son presse-papiers d'avant. Renvoie False si le
+    collage est fait mais l'ancien contenu n'a pas pu être remis (liaison coupée juste après)."""
+    if len(text.encode("utf-8")) > MAX_BYTES:
+        raise PhoneError("texte trop long pour une saisie (256 Ko au plus)")
+    _ensure_server(adb)
+    scid = f"{random.randrange(1, 0x7FFFFFFF):08x}"
+    port = adb.host("forward", "tcp:0", f"localabstract:scrcpy_{scid}").strip()
+    server: subprocess.Popen[bytes] | None = None
+    sock = None
+    try:
+        if not port.isdigit():
+            raise PhoneError(f"presse-papiers : redirection impossible ({port[:100]})")
+        cmd = [adb.path, "-s", adb.serial or "", "shell",
+               f"CLASSPATH={REMOTE} app_process / com.genymobile.scrcpy.Server {VERSION} scid={scid} log_level=warn "
+               "tunnel_forward=true video=false audio=false control=true send_device_meta=false "
+               "send_dummy_byte=true clipboard_autosync=false cleanup=false"]
+        server = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+                                  creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
+        deadline = time.monotonic() + 8
+        while sock is None:
+            if server.poll() is not None:
+                err = (server.stderr.read() if server.stderr else b"").decode("utf-8", "replace").strip()
+                raise PhoneError(f"presse-papiers : serveur scrcpy arrêté ({err[:200] or 'sans message'})")
+            try:
+                candidate = socket.create_connection(("127.0.0.1", int(port)), timeout=2)
+                candidate.settimeout(2)
+                if candidate.recv(1) == b"\x00":  # octet d'accueil : le serveur écoute vraiment
+                    sock = candidate
+                    break
+                candidate.close()
+            except OSError:
+                pass
+            if time.monotonic() > deadline:
+                raise LinkError("presse-papiers : serveur scrcpy injoignable après 8 s ; rien n'a été collé")
+            time.sleep(0.1)
+        sock.settimeout(5)
+        channel = Channel(sock)
+        before = channel.get()
+        sequence = int.from_bytes(os.urandom(4)) or 1
+        try:
+            channel.set(sequence, text, paste=True)
+        except (OSError, PhoneError) as e:
+            raise LinkError(f"collage interrompu ({e}) : effet inconnu") from None
+        time.sleep(0.3)  # le collage part avant la remise de l'ancien contenu
+        try:
+            channel.set(sequence + 1, before or "", paste=False)
+        except (OSError, PhoneError):
+            return False  # texte collé : ne pas faire croire à un échec qui pousserait à recommencer
+        return True
+    finally:
+        if sock:
+            sock.close()
+        if server:
+            try:
+                server.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                server.kill()
+                try:  # arrêter aussi le serveur côté téléphone : aucun programme d'aide ne doit y rester
+                    adb.shell("pkill", "-f", f"scid=[{scid[0]}]{scid[1:]}", check=False, timeout=10)  # [x] : pas soi
+                except PhoneError:
+                    pass
+        if port.isdigit():
+            try:
+                adb.host("forward", "--remove", f"tcp:{port}", timeout=10)
+            except PhoneError:
+                pass