# BeeOS DeviceAgent

AI-powered device control agent supporting ACP, MQTT, and WebRTC channels.

## Installation

```bash
pip install beeos-device-agent
```

For AI automation (MobileAgent v3.5):

```bash
pip install beeos-device-agent[ai]
```

## Local Development Setup

```bash
# Install bridge-client first (local dependency)
cd sdks/bridge-client-python && python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"

# Install device-agent
cd sdks/device-agent && python3 -m venv .venv
.venv/bin/pip install -e ../bridge-client-python
.venv/bin/pip install -e ".[dev]"

# Run tests
.venv/bin/pytest tests/ -v
```

## Usage

### CLI (Android via ADB)

```bash
python -m device_agent \
    --bridge ws://localhost:18443 \
    --key ~/.beeos/test-device.key \
    --adb <serial> \
    --mqtt-host localhost --mqtt-port 1883 --no-mqtt-tls \
    --http --http-port 9090
```

### CLI (Desktop mode, no ADB needed)

```bash
python -m device_agent \
    --bridge ws://localhost:18443 \
    --key ~/.beeos/test-device.key \
    --mode desktop \
    --mqtt-host localhost --mqtt-port 1883 --no-mqtt-tls \
    --http --http-port 9090
```

### CLI Options

| Flag | Default | Description |
|------|---------|-------------|
| `--bridge` | (required) | Bridge WebSocket URL |
| `--key` | auto-generated | Ed25519 key file path |
| `--mode` | `android` | Runtime mode: `android` or `desktop` |
| `--adb` | auto-detect | ADB device serial (android mode) |
| `--mqtt-host` | (empty) | MQTT broker host (enables MQTT channel) |
| `--mqtt-port` | `8883` | MQTT broker port |
| `--no-mqtt-tls` | false | Disable MQTT TLS (for local dev) |
| `--http` | false | Enable REST API |
| `--http-port` | `8080` | REST API port |
| `--vlm-model` | `gpt-4o` | VLM model for AI automation |

### Python API

```python
from device_agent import DeviceAgent, DeviceAgentConfig
from device_agent.runtime.android_adb import AndroidADBRuntime

runtime = AndroidADBRuntime(serial="R5CT1234")
config = DeviceAgentConfig(
    bridge_url="ws://localhost:18443",
    key_file="~/.beeos/test-device.key",
    mqtt_host="localhost",
    mqtt_port=1883,
    mqtt_use_tls=False,
)
agent = DeviceAgent(config, runtime)
await agent.start()
```

### REST API (when `--http` is enabled)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/device/info` | GET | Device metadata |
| `/device/screenshot` | GET | PNG screenshot |
| `/device/action` | POST | Touch/key/shell actions |
| `/tasks` | POST | Submit AI task |
| `/tasks/{id}` | GET | Get task status |

## Docker

The Dockerfile uses the **repository root** as the build context (because it
needs `sdks/bridge-client-python` at build time).

```bash
docker build -f sdks/device-agent/Dockerfile -t beeos-device-agent .

docker run --rm \
  -e BRIDGE_URL=wss://bridge.beeos.ai \
  beeos-device-agent \
  python -m device_agent \
    --bridge wss://bridge.beeos.ai \
    --adb <device-serial> \
    --mqtt-host mqtt.beeos.ai
```

## Architecture

Three independent channels:
- **ACP** (via Bridge) — AI chat + device management (JSON-RPC 2.0 over WebSocket)
- **MQTT** (via EMQX) — WebRTC signaling + device telemetry
- **WebRTC** (P2P/TURN) — on-demand video streaming + DataChannel control

Each DeviceAgent instance represents one device (1 device = 1 process = 1 BeeOS Instance).
The agent manages all three channels independently and coordinates them for features
like on-demand streaming (auto-start when viewed, auto-cooldown when idle).
