# Device Agent Runtime

Device Agent Runtime is a device-agnostic runtime for LLM-driven automation.
It gives agents a stable way to observe, decide, and act against real devices
through a small set of domain models, driver contracts, tools, perception
providers, and runtime orchestration.

iPhone automation through WebDriverAgent/Appium is the first driver, not the
platform boundary. Future drivers can target Android, browsers, desktop
environments, or other device surfaces without changing the runtime's core
contracts.

## Current Shape

- `core/`: shared domain models and runtime errors.
- `driver/`: the `Driver` contract, concrete driver adapters, and driver-type
  registry.
- `device/`: device lifecycle and active driver management.
- `tools/`: device capabilities exposed to runtime and API layers.
- `perception/`: screen-to-`Scene` perception behind `PerceptionProvider`.
- `runtime/`: planning and execution orchestration.
- `api/`: REST/MCP transport adapters.
- `storage/`: timeline, task, and device configuration persistence.
- `packages/cloud-platform/`: cloud scheduling, device pooling, plugins, and
  the Python cloud SDK as the `device-cloud-platform` workspace member.
- `apps/cloud-api/`: deployable authenticated Cloud Control Plane with
  PostgreSQL/SQLite persistence, scheduling, leases, and health endpoints.
- `apps/device-host-agent/`: outbound Host Agent that synchronizes configured
  devices and executes leased tasks through the existing Runtime/workflow.

## Python Workspace

The repository uses a uv workspace with one committed lockfile. From the
repository root, synchronize every Python member with:

```bash
uv sync --locked --all-packages
```

Run the complete local test suite in a workspace environment:

```bash
uv run --all-packages pytest -m "not integration"
```

Select one member when running package-specific commands:

```bash
uv run --package device-agent-runtime python -c "import runtime"
uv run --package device-cloud-platform python -c "import cloud"
uv run --package device-cloud-api device-cloud-api --help
uv run --package device-host-agent device-host-agent --help
uv build --package device-agent-runtime
uv build --package device-cloud-platform
```

The Runtime API ships a same-origin operator console at `/ui/`, rendered through
Jinja2 templates packaged with `device-agent-runtime`. Start the API
(`uvicorn api.rest:create_app --factory`) and open `/` (it redirects to `/ui/`).
The `/console/*` JSON endpoints remain available for programmatic clients. The
console assumes a trusted local network; it has no authentication, authorization,
or CSRF protection.

## Project Direction

The durable roadmap is in [docs/ROADMAP.md](docs/ROADMAP.md). The architecture
invariants future changes must preserve are in
[docs/CONSTITUTION.md](docs/CONSTITUTION.md).

## Operator Guides

- [Cloud Control Plane deployment](docs/CLOUD_DEPLOYMENT.md): run local SQLite
  or deployed PostgreSQL, configure credentials and Runtime AI planning, and
  perform orderly shutdown or rollback.
- [macOS migration and real iPhone setup](docs/MACOS_IPHONE_SETUP.md): install
  Xcode, Appium/XCUITest, sign WebDriverAgent, verify a real device, and start a
  connected Runtime API.