Core concepts
Sessions and actions
One session serializes agent input for one phone. Action records make uncertain delivery recoverable without blind replay.
Lifecycle
Acquire a session, use the returned ID and expiry, submit one action at a time, verify the result, and release in cleanup. Sessions exclude other FleetDeck automation sessions and active touch schedules. They do not block human input or unrelated ADB/WDA clients.
Request identity
A requestId identifies one exact command within one session. Sending the same ID and identical command returns the existing action. Sending changed input under that ID returns IDEMPOTENCY_CONFLICT. Session acquisition and job creation have no idempotency key.
Action statuses
| Status | Meaning | Next step |
|---|---|---|
| queued | Awaiting a bridge | Poll the same request ID |
| running | Claimed under a finite lease | Poll; do not replay |
| completed | Driver finished | Capture or inspect to verify effect |
| failed | Driver reported failure | Observe before deciding on a new action |
| unknown | Delivery or effect is uncertain | Inspect; never blind-replay a publication or upload |
| cancelled | Queued work was cancelled | Do not assume a previous running effect was undone |
Keepalive
The FleetDeck client heartbeats before submission and during longer action calls, then stops its keepalive before returning. Scheduled worker heartbeats also extend still-active child sessions while an agent is thinking. Neither path revives an expired or released session.
