replx-agent 2.0.0__py3-none-any.whl

replx_agent/transport/serial.py

@@ -0,0 +1,220 @@
+import gc
+import sys
+import time
+from replx_agent.utils.exceptions import TransportError
+
+try:
+    import serial
+except ImportError:
+    serial = None
+
+
+def _require_serial() -> None:
+    if serial is None:
+        raise ImportError("pyserial is required. Install with: pip install pyserial")
+
+
+_PORT_PRESENCE_TTL = 0.5
+_port_presence_cache: dict = {"ts": 0.0, "ports": None}
+
+
+def _enumerate_ports() -> set | None:
+    try:
+        from serial.tools.list_ports import comports
+        ports = {p.device for p in comports()}
+    except Exception:
+        return None
+    _port_presence_cache["ports"] = ports
+    _port_presence_cache["ts"] = time.time()
+    return ports
+
+
+def _port_in(port: str, ports: set) -> bool:
+    if not port:
+        return False
+    if port in ports:
+        return True
+    if sys.platform == "win32":
+        from replx_agent.utils.constants import canon_port
+        needle = canon_port(str(port))
+        return any(canon_port(str(p)) == needle for p in ports)
+    try:
+        import os
+        real_needle = os.path.realpath(port)
+        for p in ports:
+            if p == real_needle or os.path.realpath(p) == real_needle:
+                return True
+    except Exception:
+        pass
+    return False
+
+
+def _port_currently_present(port: str) -> bool | None:
+    """Return True/False if the OS reports ``port`` present, or None if the
+    check itself failed (caller should skip/ignore in that case)."""
+    now = time.time()
+    ports = _port_presence_cache["ports"]
+    fresh = False
+    if ports is None or (now - _port_presence_cache["ts"]) > _PORT_PRESENCE_TTL:
+        ports = _enumerate_ports()
+        if ports is None:
+            return None
+        fresh = True
+
+    if _port_in(port, ports):
+        return True
+    # A cached snapshot can predate a re-enumeration; confirm absence live.
+    if not fresh:
+        ports = _enumerate_ports()
+        if ports is None:
+            return None
+        return _port_in(port, ports)
+    return False
+
+
+class SerialTransport:
+    
+    def __init__(self, port: str, baudrate: int = 115200, timeout: float = 1.0):
+        _require_serial()
+        self.port = port
+        self.baudrate = baudrate
+        if sys.platform != "win32" and timeout > 0.6:
+            timeout = 0.6
+        self._default_timeout = timeout
+        self._serial = None
+        
+        try:
+            self._serial = serial.Serial(
+                port=port,
+                baudrate=baudrate,
+                timeout=timeout,
+                write_timeout=timeout,
+                inter_byte_timeout=0.1
+            )
+            try:
+                self._serial.set_buffer_size(rx_size=262144, tx_size=65536)
+            except Exception:
+                pass
+        except serial.SerialException as e:
+            raise TransportError(f"Failed to open serial port {port}: {e}") from e
+
+    def set_baudrate(self, baudrate: int) -> None:
+        try:
+            self._serial.baudrate = baudrate
+        except (serial.SerialException, ValueError) as e:
+            raise TransportError(f"Failed to set baud rate {baudrate}: {e}") from e
+        self.baudrate = baudrate
+    
+    def write(self, data: bytes) -> int:
+        try:
+            return self._serial.write(data)
+        except (serial.SerialException, OSError) as e:
+            raise TransportError(f"Serial write error: {e}") from e
+    
+    def read(self, size: int = 1) -> bytes:
+        try:
+            return self._serial.read(size)
+        except (serial.SerialException, OSError) as e:
+            raise TransportError(f"Serial read error: {e}") from e
+    
+    def read_byte(self, timeout: float = None) -> bytes:
+        try:
+            if timeout is not None:
+                old_timeout = self._serial.timeout
+                self._serial.timeout = timeout
+                try:
+                    return self._serial.read(1)
+                finally:
+                    self._serial.timeout = old_timeout
+            return self._serial.read(1)
+        except (serial.SerialException, OSError) as e:
+            raise TransportError(f"Serial read_byte error: {e}") from e
+    
+    def read_available(self) -> bytes:
+        try:
+            waiting = self._serial.in_waiting
+            if waiting > 0:
+                return self._serial.read(waiting)
+            return b""
+        except (serial.SerialException, OSError) as e:
+            error_msg = str(e).lower()
+            if "clearcommerror" in error_msg or "not exist" in error_msg or "cannot find" in error_msg:
+                raise TransportError("Serial port disconnected (device removed or cable unplugged)") from e
+            raise TransportError(f"Serial read_available error: {e}") from e
+
+    def in_waiting(self) -> int:
+        try:
+            return self._serial.in_waiting
+        except (serial.SerialException, OSError) as e:
+            error_msg = str(e).lower()
+            raise TransportError(f"Serial input status error: {error_msg}") from e
+    
+    def close(self) -> None:
+        if self._serial:
+            serial_obj = self._serial
+            self._serial = None
+            try:
+                if serial_obj.is_open:
+                    try:
+                        serial_obj.cancel_read()
+                    except Exception:
+                        pass
+                    try:
+                        serial_obj.cancel_write()
+                    except Exception:
+                        pass
+                    try:
+                        serial_obj.reset_input_buffer()
+                    except Exception:
+                        pass
+                    try:
+                        serial_obj.reset_output_buffer()
+                    except Exception:
+                        pass
+                    serial_obj.close()
+            except Exception:
+                pass
+            finally:
+                del serial_obj
+                if sys.platform == 'win32':
+                    gc.collect()
+    
+    def reset_input_buffer(self) -> None:
+        if self._serial:
+            self._serial.reset_input_buffer()
+    
+    def reset_output_buffer(self) -> None:
+        if self._serial:
+            self._serial.reset_output_buffer()
+    
+    def check_connection(self) -> bool:
+        try:
+            if not self._serial or not self._serial.is_open:
+                return False
+            if _port_currently_present(self.port) is False:
+                return False
+            _ = self._serial.in_waiting
+            return True
+        except serial.SerialException as e:
+            error_msg = str(e).lower()
+            if "clearcommerror" in error_msg or "not exist" in error_msg or "cannot find" in error_msg or "access is denied" in error_msg:
+                return False
+            return False
+        except (OSError, IOError):
+            return False
+        except Exception:
+            return False
+    
+    def keep_alive(self) -> None:
+        if not self._serial or not self._serial.is_open:
+            raise TransportError("Serial port disconnected (device removed or cable unplugged)")
+        if _port_currently_present(self.port) is False:
+            raise TransportError("Serial port disconnected (device removed or cable unplugged)")
+        try:
+            _ = self._serial.in_waiting
+        except (serial.SerialException, OSError, IOError) as e:
+            raise TransportError(f"Serial keep-alive failed: {e}") from e
+    
+    @property
+    def is_open(self) -> bool:
+        return self._serial.is_open if self._serial else False

replx_agent/utils/__init__.py

@@ -0,0 +1,95 @@
+import re as _re
+import sys as _sys
+from typing import Optional as _Optional
+
+
+def device_name_to_path(device_name: str) -> str:
+    return device_name.replace('-', '_')
+
+
+def canon_port(port: _Optional[str]) -> _Optional[str]:
+    """Canonical form of a serial port name.
+
+    Windows: ``COM3``/``com3``/``Com3`` are equivalent — normalise to upper case.
+    POSIX: pass through stripped string. ``None`` and empty input map to themselves.
+    """
+    if port is None:
+        return None
+    p = str(port).strip()
+    if not p:
+        return p
+    if _sys.platform == "win32" or _sys.platform.startswith("win"):
+        if _re.match(r"(?i)^com\d+$", p):
+            return p.upper()
+    return p
+
+
+from .device_info import (
+    parse_device_banner,
+    get_root_fs_for_core,
+    get_core_profile,
+    CORE_PROFILES,
+    SUPPORT_CORE_DEVICE_TYPES,
+    CORE_ROOT_FS,
+    DEFAULT_ROOT_FS,
+)
+from .constants import (
+    CTRL_A, CTRL_B, CTRL_C, CTRL_D, CTRL_E,
+    REPL_PROMPT, EOF_MARKER,
+    RAW_REPL_PROMPT, SOFT_REBOOT_MSG, OK_RESPONSE, ERROR_HEADER,
+    RAW_PASTE_INIT, RAW_PASTE_SUPPORTED, RAW_PASTE_NOT_SUPPORTED,
+    RAW_PASTE_FALLBACK, RAW_PASTE_WINDOW_INC, RAW_PASTE_END_DATA,
+    PORT_SCAN_TIMEOUT, REPL_READ_TIMEOUT,
+    SERIAL_TIMEOUT, SERIAL_WRITE_TIMEOUT,
+    REPL_BUFSIZE, RAW_PASTE_DEFAULT_WINDOW_SIZE,
+    DEVICE_CHUNK_SIZE_DEFAULT, DEVICE_CHUNK_SIZE_EFR32MG,
+    PUT_BATCH_BYTES_DEFAULT, PUT_BATCH_BYTES_EFR32MG,
+    RAW_MODE_DELAY_DEFAULT, RAW_MODE_DELAY_EFR32MG,
+    DEFAULT_AGENT_PORT, MAX_AGENT_PORT, AGENT_HOST,
+    MAX_CONNECTIONS, AGENT_SOCKET_TIMEOUT,
+    MAX_PAYLOAD_SIZE,
+    HEARTBEAT_INTERVAL, ZOMBIE_CHECK_INTERVAL, IDLE_COMMAND_THRESHOLD,
+    GC_THRESHOLD,
+)
+from .exceptions import (
+    ReplxException,
+    TransportError,
+    ProtocolError,
+    FileSystemError,
+    ValidationError,
+    CompilationError,
+)
+
+__all__ = [
+    "device_name_to_path",
+    "canon_port",
+    "parse_device_banner",
+    "get_root_fs_for_core",
+    "get_core_profile",
+    "CORE_PROFILES",
+    "SUPPORT_CORE_DEVICE_TYPES",
+    "CORE_ROOT_FS",
+    "DEFAULT_ROOT_FS",
+    "CTRL_A", "CTRL_B", "CTRL_C", "CTRL_D", "CTRL_E",
+    "REPL_PROMPT", "EOF_MARKER",
+    "RAW_REPL_PROMPT", "SOFT_REBOOT_MSG", "OK_RESPONSE", "ERROR_HEADER",
+    "RAW_PASTE_INIT", "RAW_PASTE_SUPPORTED", "RAW_PASTE_NOT_SUPPORTED",
+    "RAW_PASTE_FALLBACK", "RAW_PASTE_WINDOW_INC", "RAW_PASTE_END_DATA",
+    "PORT_SCAN_TIMEOUT", "REPL_READ_TIMEOUT",
+    "SERIAL_TIMEOUT", "SERIAL_WRITE_TIMEOUT",
+    "REPL_BUFSIZE", "RAW_PASTE_DEFAULT_WINDOW_SIZE",
+    "DEVICE_CHUNK_SIZE_DEFAULT", "DEVICE_CHUNK_SIZE_EFR32MG",
+    "PUT_BATCH_BYTES_DEFAULT", "PUT_BATCH_BYTES_EFR32MG",
+    "RAW_MODE_DELAY_DEFAULT", "RAW_MODE_DELAY_EFR32MG",
+    "DEFAULT_AGENT_PORT", "MAX_AGENT_PORT", "AGENT_HOST",
+    "MAX_CONNECTIONS", "AGENT_SOCKET_TIMEOUT",
+    "MAX_PAYLOAD_SIZE",
+    "HEARTBEAT_INTERVAL", "ZOMBIE_CHECK_INTERVAL", "IDLE_COMMAND_THRESHOLD",
+    "GC_THRESHOLD",
+    "ReplxException",
+    "TransportError",
+    "ProtocolError",
+    "FileSystemError",
+    "ValidationError",
+    "CompilationError",
+]

replx_agent/utils/constants.py

@@ -0,0 +1,78 @@
+CTRL_A = b'\x01'  # Raw REPL mode / Paste mode
+CTRL_B = b'\x02'  # Normal REPL mode / Exit paste mode
+CTRL_C = b'\x03'  # Keyboard interrupt
+CTRL_D = b'\x04'  # EOF / Soft reboot
+CTRL_E = b'\x05'  # Enter paste mode
+REPL_PROMPT = b'>>>'
+
+EOF_MARKER = b'\x04'
+
+RAW_REPL_PROMPT = b'raw REPL; CTRL-B to exit\r\n>'
+SOFT_REBOOT_MSG = b'soft reboot\r\n'
+OK_RESPONSE = b'OK'
+
+ERROR_HEADER = b"Traceback (most recent call last):"
+
+RAW_PASTE_INIT = b'\x05A\x01'
+RAW_PASTE_SUPPORTED = b'R\x01'
+RAW_PASTE_NOT_SUPPORTED = b'R\x00'
+RAW_PASTE_FALLBACK = b'raw REPL; CTRL-B'
+RAW_PASTE_WINDOW_INC = b'\x01'
+RAW_PASTE_END_DATA = b'\x04'
+
+PORT_SCAN_TIMEOUT = 0.05
+REPL_READ_TIMEOUT = 0.5
+SERIAL_TIMEOUT = 0.5
+SERIAL_WRITE_TIMEOUT = 0.3
+
+REPL_BUFSIZE = 2048
+RAW_PASTE_DEFAULT_WINDOW_SIZE = 128
+
+DEVICE_CHUNK_SIZE_DEFAULT = 4096
+DEVICE_CHUNK_SIZE_EFR32MG = 256
+
+PUT_BATCH_BYTES_DEFAULT = 16 * 1024
+PUT_BATCH_BYTES_EFR32MG = 2 * 1024
+
+RAW_MODE_DELAY_DEFAULT = 0.0
+RAW_MODE_DELAY_EFR32MG = 0.01
+
+# REPL baud rates tried in order when opening a serial port. Native USB CDC
+# ignores the value; USB-UART bridges (e.g. the CH343 on ESP32-P4 boards) need
+# the rate the firmware was built with. REPLX_BAUD prepends extra candidates.
+REPL_BAUD_DEFAULT = 115200
+REPL_BAUD_CANDIDATES = (115200, 921600)
+
+# Above this baud rate a firmware with a small stdin buffer can be overrun by
+# plain raw-REPL writes, so longer commands use flow-controlled raw-paste.
+RAW_PASTE_SAFE_BAUD = 115200
+RAW_PASTE_HIGH_BAUD_MIN_COMMAND_SIZE = 256
+# Baud/REPL detection sweeps on connect (covers a board still booting after reset)
+CONNECT_DETECT_ROUNDS = 3
+CONNECT_DETECT_RETRY_DELAY = 0.5
+
+DEFAULT_AGENT_PORT = 49153
+MIN_AGENT_PORT = 49152
+MAX_AGENT_PORT = 65535
+AGENT_HOST = '127.0.0.1'
+
+MAX_CONNECTIONS = 20
+AGENT_SOCKET_TIMEOUT = 1.0
+HTTP_REQUEST_TIMEOUT = 15
+
+MAX_PAYLOAD_SIZE = 60000
+
+PUTDIR_EXCLUDED_DIRS = frozenset({
+    '__pycache__', '.git', '.svn', '.hg', 'node_modules',
+    '.venv', 'venv', '__MACOSX',
+})
+PUTDIR_EXCLUDED_EXTENSIONS = frozenset({
+    '.pyc', '.pyo', '.pyd', '.so', '.dll', '.dylib',
+})
+
+HEARTBEAT_INTERVAL = 1
+ZOMBIE_CHECK_INTERVAL = 10
+IDLE_COMMAND_THRESHOLD = 5
+GC_COLLECT_INTERVAL = 60
+
+GC_THRESHOLD = (1500, 15, 15)

replx_agent/utils/device_info.py

@@ -0,0 +1,183 @@
+import re
+from typing import Optional, Tuple
+
+from replx_agent.utils.constants import (
+    DEVICE_CHUNK_SIZE_DEFAULT, DEVICE_CHUNK_SIZE_EFR32MG,
+    PUT_BATCH_BYTES_DEFAULT, PUT_BATCH_BYTES_EFR32MG,
+    RAW_MODE_DELAY_DEFAULT, RAW_MODE_DELAY_EFR32MG,
+)
+
+
+_DEFAULT_PROFILE = {
+    'std': True,
+    'devices': set(),
+    'root_fs': '/',
+    'chunk_size': DEVICE_CHUNK_SIZE_DEFAULT,
+    'put_batch_bytes': PUT_BATCH_BYTES_DEFAULT,
+    'raw_mode_delay': RAW_MODE_DELAY_DEFAULT,
+    'raw_paste': True,
+    'get_chunk_size': 12288,
+}
+
+CORE_PROFILES = {
+    'EFR32MG': {
+        'std': False,
+        'devices': {'xnode'},
+        'root_fs': '/flash',
+        'chunk_size': DEVICE_CHUNK_SIZE_EFR32MG,
+        'put_batch_bytes': PUT_BATCH_BYTES_EFR32MG,
+        'raw_mode_delay': RAW_MODE_DELAY_EFR32MG,
+        'raw_paste': False,
+        'get_chunk_size': DEVICE_CHUNK_SIZE_EFR32MG,
+    },
+    'RP2350': {
+        'devices': {'ticle', 'ticle-lite', 'ticle-sensor', 'ticle-auto'},
+    },
+    'MIMXRT1062DVJ6A': {
+        'devices': {'teensy'},
+        'root_fs': '/flash',
+    },
+    'ESP32C5': {
+        'devices': {'ESP32C5'},
+    },
+    'ESP32S3': {
+        'devices': {'ESP32S3'},
+    },
+    'ESP32P4': {
+        'devices': {'ESP32P4'},
+    },
+}
+
+SUPPORT_CORE_DEVICE_TYPES = {
+    k: {'std': v.get('std', _DEFAULT_PROFILE['std']), 'devices': v.get('devices', set())}
+    for k, v in CORE_PROFILES.items()
+}
+
+CORE_ROOT_FS = {
+    k: v.get('root_fs', _DEFAULT_PROFILE['root_fs'])
+    for k, v in CORE_PROFILES.items()
+}
+
+DEFAULT_ROOT_FS = '/' 
+
+
+def normalize_version(version: str) -> str:
+    if version is None:
+        return "?"
+
+    text = str(version).strip()
+    if not text or text == '?':
+        return "?"
+
+    match = re.search(r'(\d+)\.(\d+)(?:\.(\d+))?', text)
+    if not match:
+        return text
+
+    major, minor, patch = match.groups()
+    if patch is None:
+        return f"{major}.{minor}.0"
+    return f"{major}.{minor}.{patch}"
+
+
+def normalize_core(core: str) -> str:
+    core = (core or '').upper().replace('ESP32-', 'ESP32')
+    if core and "/" in core:
+        core = core.split("/", 1)[0]
+
+    if core in CORE_PROFILES:
+        return core
+
+    if core.startswith("EFR32MG"):
+        return "EFR32MG"
+    if core in ("ESP32P4C5", "ESP32P4C6"):
+        return "ESP32P4"
+
+    if core and len(core) > 1 and core[-1].isalpha() and core[-2].isdigit():
+        return core[:-1]
+    return core
+
+
+def get_core_profile(core: str) -> dict:
+    normalized = normalize_core(core)
+    profile = CORE_PROFILES.get(normalized, {})
+    return {**_DEFAULT_PROFILE, **profile}
+
+
+def get_root_fs_for_core(core: str) -> str:
+    return get_core_profile(core)['root_fs']
+
+
+def is_std_micropython(core: str) -> bool:
+    return get_core_profile(core)['std']
+
+
+def get_devices_for_core(core: str) -> set:
+    return get_core_profile(core)['devices']
+
+
+def parse_device_banner(banner_text: str) -> Optional[Tuple[str, str, str, str]]:
+    version_match = re.search(r'v(\d+\.\d+(?:\.\d+)?)', banner_text)
+    version = normalize_version(version_match.group(1)) if version_match else '?'
+
+    if re.search(r'\bXBee\s*3\b', banner_text, re.IGNORECASE):
+        return version, 'EFR32MG', 'xbee3', 'Digi'
+    
+    multi_with_match = re.search(r';\s*(.+?)\s+with\s+(.+?)\s+module\s+of\s+external\s+([\w-]+)\s+with\s+([\w-]+)', banner_text)
+    if multi_with_match:
+        prefix = multi_with_match.group(1).strip()
+        wifi_desc = multi_with_match.group(2).strip()
+        core2 = multi_with_match.group(3).strip().upper().replace('-', '')
+        core1 = multi_with_match.group(4).strip().upper().replace('-', '')
+
+        if core1 == "ESP32P4" and core2 in ("ESP32C5", "ESP32C6"):
+            core = f"ESP32P4{core2[-2:]}"
+        else:
+            core = core1
+        
+        if prefix.endswith(" module"):
+            prefix = prefix[:-7].strip()
+        
+        manufacturer = f"{prefix} with {wifi_desc} ({core2})".strip()
+
+        device = core
+        return version, core, device, manufacturer
+    
+    match = re.search(r';\s*(.+?)\s+with\s+(\S+)', banner_text)
+    if not match:
+        return None
+    
+    prefix = match.group(1).strip()
+    core_raw = match.group(2).strip().upper()
+    core = normalize_core(core_raw)
+    
+    device_set = get_devices_for_core(core)
+    
+    device = None
+    manufacturer = None
+    
+    for known_device in sorted(device_set, key=len, reverse=True):
+        prefix_lower = prefix.lower()
+        if prefix_lower.endswith(known_device):
+            device = known_device
+            idx = prefix_lower.rfind(known_device)
+            manufacturer = prefix[:idx].strip()
+            break
+    
+    if device is None:
+        if len(device_set) == 1:
+            device = next(iter(device_set))
+            manufacturer = prefix.split()[0] if prefix else "Unknown"
+        else:
+            device = core
+            manufacturer = prefix
+    
+    if manufacturer:
+        if manufacturer.startswith("Raspberry Pi"):
+            manufacturer = "Raspberry Pi"
+        elif manufacturer.endswith(" module"):
+            manufacturer = manufacturer[:-7].strip()
+    
+    if not manufacturer:
+        manufacturer = "Unknown"
+    
+    return version, core, device, manufacturer

replx_agent/utils/exceptions.py

@@ -0,0 +1,31 @@
+class ReplxException(Exception):
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self):
+        return f"{self.__class__.__name__}: {self.message}"
+
+
+class TransportError(ReplxException):
+    pass
+
+
+class ProtocolError(ReplxException):
+    pass
+
+
+class FileSystemError(ReplxException):
+    pass
+
+
+class ValidationError(ReplxException):
+    pass
+
+
+class CompilationError(ReplxException):
+    pass
+
+
+class PkgError(ReplxException):
+    pass

replx_agent-2.0.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: replx-agent
+Version: 2.0.0
+Summary: Local MicroPython board-management agent for replx.
+License-Expression: MIT
+Project-URL: Homepage, https://planxlab.com
+Project-URL: Repository, https://github.com/PlanXLab/replx
+Project-URL: Issues, https://github.com/PlanXLab/replx/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: esptool<6,>=5.6.0
+Requires-Dist: mpy-cross>=1.29.0
+Dynamic: license-file
+
+# replx-agent
+
+`replx-agent` is the board-management service used by the `replx` MicroPython CLI. It owns serial discovery and connections, board filesystem operations, transfer staging, and firmware flashing through `esptool`.
+
+## Package Boundary
+
+The CLI depends on `replx-agent`; the agent never imports `replx`. The packages communicate through a versioned TCP RPC protocol, allowing separate builds while protocol versions remain compatible. The distribution version is defined in `src/replx_agent/__init__.py`.
+
+## Runtime
+
+- The agent is a single process per endpoint and supports multiple TCP clients using `ThreadingTCPServer` and bounded command worker pools.
+- Serial access is owned by the agent. Commands for the same board are serialized; separate boards can be serviced concurrently.
+- Client sessions are identified by source IP and terminal SID. `replx agent status` reports the current client's foreground/background board assignments.
+- The default endpoint is `127.0.0.1:49153`. The CLI creates `.vscode/.replx` as needed and stores `AGENT_IP` and `AGENT_PORT` there.
+- Legacy `~/.replx/config`, `~/.replx/.config`, and `~/.replx/.agent_port` settings are read for migration compatibility.
+
+## Remote Access
+
+The default loopback endpoint does not require a token. Binding to a non-loopback interface or connecting to a non-loopback agent requires the same `REPLX_AGENT_TOKEN` environment variable on the agent and every client.
+
+```powershell
+$env:REPLX_AGENT_TOKEN = "<shared-secret>"
+replx agent start --host 192.168.1.20 --port 49153
+```
+
+On Linux/macOS, export the variable before starting the agent or running the client:
+
+```sh
+export REPLX_AGENT_TOKEN="<shared-secret>"
+replx agent connect 192.168.1.20 --port 49153
+```
+
+The RPC transport is plain TCP, not TLS. Use remote access only on a trusted LAN or VPN; do not expose the port to an untrusted network.
+
+## CLI Lifecycle
+
+```sh
+replx agent status
+replx agent start --port 49153
+replx agent connect 192.168.1.20 --port 49153
+replx agent disconnect 192.168.1.30
+replx agent stop
+```
+
+`agent start` restarts an existing local agent at the selected endpoint. `agent connect` verifies the endpoint before saving workspace settings. `agent disconnect IP` removes that client's sessions and releases only boards not still assigned to another client. `agent stop` stops the configured agent and releases its board connections.
+
+## Build and Install
+
+Build this package before building `replx`. Windows, Linux, and macOS builds use PowerShell 7 and `uv`:
+
+```powershell
+.\build.ps1
+```
+
+Use `-Install` to install the wheel into the active virtual environment. The build script locates `Scripts/python.exe` on Windows and `bin/python` on Linux/macOS. On Windows it bootstraps pip if the environment lacks it and avoids uv's metadata replacement path. `-NoDeps` skips dependency installation.
+
+Build the local agent wheel before the CLI wheel. The `replx` build script installs the matching local agent wheel when it is present.