Skip to main content
Two facts about driving a real phone shape this page. An action takes real time, because the device has to apply it and confirm it. And some screens cannot be solved by an agent at all, because they are asking for a person. PhoneUse handles both, and how well it handles them depends on your transport.

Progress on a long action

An action call blocks until the device commits it. That is usually quick, but a caller waiting on the response is waiting on the device, not on the server. If your client sends a progress token with the request, the server reports the handoff as soon as the action is dispatched to the device:
That notification says the request reached the device and the device is applying it. It does not say the action succeeded. The success answer is the result itself, and it arrives when the device confirms. Two conditions have to hold for any of this to reach you.
  1. You asked. The protocol only sends progress against a token the request carried. A request with no progress token gets no notification.
  2. Your transport can carry it. A mid request notification needs a live bidirectional session. The hosted HTTP endpoint is stateless, and phoneuse mcp --stdio relays to it, so neither carries one today.
A transport that cannot deliver the notification does not fail your action over it. Progress is a transport capability, never a promise the tool surface makes.

When progress is not available

Do not build a loop that depends on notifications. Build it on the recorded outcome instead, which works everywhere:
  1. Send the action with an idempotencyKey you generated.
  2. If the response arrives, you are done. Read status and committedAt.
  3. If it does not, call get_receipt with the same key.
    • found: false means the action never began. Retry with the same key.
    • A committed receipt means it happened. Do not retry.
    • A failed receipt carrying outcome_unknown means the transport to the device was lost after dispatch, so a person has to reconcile it.
This path survives a lost response, a client restart, and a transport with no notification channel at all. See Reading a trace.

When a person has to step in

Some screens are designed to stop automation, and correctly so: a sign in, a one time code, a challenge. An agent should not be trying to defeat them. The mechanism is MCP elicitation. The server asks your client’s operator to go and deal with the screen, and to confirm when they are done. The request carries the device id, a short machine stable reason, and an instruction of what to do. The person acts on the same device under the same lease; nothing is handed over and nothing is taken away.
No secret ever travels this channel. The person acts on the device, not in a chat window. PhoneUse asks a human to go and type a password into the phone in front of them; it never asks anyone to send it one.
The wait is generous, because a person unlocking a device and solving a challenge takes minutes rather than the seconds a normal remote call is given. It is still bounded, because an elicitation that never resolves would hold a lease open behind it. Every non confirmation fails closed: Only an explicit confirmation counts as completed. Like progress, elicitation needs a live bidirectional session, so the stateless HTTP path (and the CLI relay in front of it) cannot carry it: the caller sees a terminal outcome and re drives after the person is finished.

A person’s turn inside an autonomous run

The agent tier has its own form of the same idea, and it is stronger. A worker that hits a screen needing a person reports the run as needs_user_control. The run parks: it does not end, and while it is parked the worker’s channel is shut on every side. A tap or a swipe is refused; a screenshot is refused before the device is ever asked for one; and a second run cannot be started on the same device to observe it around the first. So what the person does while the agent waits is not served to the worker. The only way out is a person, through resume_run or the equivalent REST call. A worker cannot lift its own request, not by asking to resume and not by reporting the run finished out from under the person; a worker report on a parked run is refused until someone resumes it. Two exceptions:
  • A run still stops at its deadline, so a wait that runs long can expire. Give the run enough wall-clock when you start it.
  • A run parked by an API restart ends by itself. A run PhoneUse was driving when the API restarted ends canceled once the earlier of its saved time and 10 minutes has passed, and frees the phone, unless an action from before the restart has an unclear outcome: that action still holds the phone.
One rule is stricter, for runs PhoneUse drives. On such a run, a goal that needs a person from the start (paying, buying, erasing, changing a password and the like) is parked before anything drives it, and it ends as succeeded only when a person signed in to the console presses Done. A resume from an API key, the CLI, a third-party app or Copilot leaves it waiting. To stop it instead, cancel it with cancel_run, POST /v1/runs/{runId}/cancel or phoneuse runs cancel <runId>; it then ends canceled. See Runs. A person does not have to wait to be asked. They may act on the device while the run is driving, and the run is informed through others on its next result rather than stopped. See Runs for how the two hands share one phone, and for the full lifecycle.