ADR 0001: Device-Agnostic Runtime

Status

Accepted

Context

The project began as Apex Agent, centered on iPhone automation. The existing MVP already has a driver-independent Driver interface, WDA as the first driver, device lifecycle management, scene perception, runtime execution, task memory, and REST/MCP surfaces. The old names and package layout still implied that iPhone/WDA was the platform rather than the first adapter.

The OpenSpec change device-agent-runtime-foundation records the detailed design decisions for this repositioning.

Decision

Reposition the project as Device Agent Runtime:

Keep core/ for shared domain models and errors.
Move the driver contract and concrete drivers into driver/.
Move device lifecycle management into device/.
Rename vision/ to perception/.
Move driver-type factory selection into driver/registry.py.
Rename the shared error base to DeviceRuntimeError.
Treat iPhone/WDA as the first driver, not the product boundary.

Alternatives Considered

Keeping the old Apex Agent/iPhone framing was rejected because it would make future Android, browser, desktop, and cloud-device support look like exceptions instead of first-class adapters.

Eliminating core/ entirely was rejected for this change because models such as Scene, Task, and Device are shared across several layers today. Forcing them into perception/ or runtime/ would add coupling without behavioral value.

Keeping a deprecated ApexAgentError alias was rejected because there are no external consumers to preserve yet.

Consequences

Future driver support is added in the driver layer and registry. Future perception techniques are added behind PerceptionProvider. User-facing runtime behavior remains unchanged, while package names and docs now match the device-agnostic direction.

1.8 KiB Raw Blame History