Metadata-Version: 2.4
Name: evd-host
Version: 0.2.1
Summary: Computer SDK and CLI for the EVD Android server
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# EVD Host

Python CLI and SDK for the EVD Android instrumentation server. The release wheel includes the Android ARM64 server ELF and creates the `evd` and `evd-client` commands. The host runs Python; JavaScript executes inside the target Android Agent, with native Interceptor backed by the EVD dual-view kernel.

## Install and run

```sh
python3 -m pip install -U evd-host
evd --version
evd -U -f org.evd.lab -l script.js
evd -U -n org.evd.lab -l script.js --watch
evd -U -f org.evd.lab -l script.js --pause --repl
```

The first USB command selects the online device, verifies the bundled ELF, deploys it, starts the authenticated loopback server and creates an ADB TCP forward. Matching running servers are reused. Use `--serial SERIAL` with multiple devices. A server from another build must first be stopped with `evd -U server stop`, so existing sessions are not silently interrupted.

Requirements: Python 3.9+, adb on PATH, a rooted Android ARM64 phone and a compatible EVD kernel. The bundled payload targets the project's 4 KB kernel baseline. pip installs the client and server payload; kernel installation remains a device prerequisite. macOS, Linux and Windows can use the Python client; current device acceptance is on NE2210.

`-f` is the Android package or exact `package:process` specification; the project demo is `org.evd.lab`. Java/native scripts run in one target context. Messages (`send/recv`), `rpc.exports`, explicit resume and target expression REPL are supported. `--pause` leaves the early main-thread gate held until `:resume`. Ctrl+C or `:quit` detaches; disconnects retire the owning session. The server remains available until `evd -U server stop`.

## SDK

```python
from evd import Device
with Device.usb(serial="SERIAL") as device:
    pid = device.spawn("org.evd.lab")
    session = device.attach(pid)
    script = session.create_script(open("script.js").read())
    script.on("message", lambda message, data: print(message, data))
    script.load()
    device.resume(pid)
    session.detach()
```

Start the server with the CLI before SDK use. Script APIs retain the current implementation's bounded queues, single-script sessions and supported ART/Interceptor semantics; they do not imply complete stock Frida wire/API compatibility.

## Distribution

The PyPI distribution is named `evd-host`; the installed commands are `evd` and `evd-client`, and the Python import is `evd`. A release wheel includes its matching Android server and checks the payload hash before deployment.

To upgrade a running installation:

```sh
python3 -m pip install -U evd-host
evd -U server stop
evd -U server start
evd -U -f org.evd.lab -l script.js
```

Stop existing sessions before stopping their server. Restart a target App that still contains an older injected Agent; the new server rejects incompatible Agent bridge versions. No kernel upgrade is needed for the 0.2.1 runtime fixes on the validated #13 / 4 KB baseline.

Version 0.2.1 adds RPC/eval deadlines and cancellation, preserves a live script after a replacement syntax error, and bundles the callback scheduling, invocation retirement and native exception-unwind fixes. Syntax preflight does not roll back arbitrary runtime side effects. Executable hook pools remain mapped until process exit, and exceptions must not cross a live Rust/JS foreign-call frame.

Authentication tokens and device credentials are generated after installation and are never included in the package.
