assistant_* tools. Send a natural-language task, poll its progress, and handle the human-in-the-loop (HITL) cards it raises.
For HTTP/curl or SDK access, use Mobilerun Agents · chat. For connection setup, see MCP server. For direct phone control, use OpenClaw · Android control.
Install
Download the packaged skill and load it into a compatible agent runtime:mobilerun-assistant-mcp.skill
Download the latest release from GitHub
MOBILERUN_API_KEY, curl, or jq is required.
Mobilerun Agents write tools require the server’s full policy profile, which is also the default for a self-hosted server. Under readonly or no-commerce, only assistant_list_sessions and assistant_get_messages are available. Tell the user about that restriction rather than bypassing it with another tool or transport.
How a conversation works
A session is a persistent chat thread. Each message starts a turn, and only one turn can run in a session. Each action is its own tool, for exampleassistant_send_message.
1
Create or select a session
Call
assistant_create_session with a title, or assistant_list_sessions to find an existing conversation. Keep its id as sessionId. Before sending into an existing session, check assistant_get_messages for an active turn or pending cards.2
Send a message once
Call
assistant_send_message with sessionId and message. waitSeconds is an integer from 1 to 50, defaulting to 45. The response reports completed or running; read any errorText before treating a completed response as success.3
Poll long-running turns
On
running, a send error, or a timeout, call assistant_get_messages — never resend the task. Inspect turnActive, turn, lastTurnOutcome, and pending on each poll.4
Resolve pending cards
Surface
pending.questions and pending.permissions, collect the user’s decision, and call the matching answer or rejection tool. Use the card IDs from pending directly, then continue polling.5
Read the final outcome
Once the turn settles, read its text and outcome before reporting the result.
turn.outcome and lastTurnOutcome are completed, error, aborted, crash-recovered, or awaiting-input (waiting for a card). Surface anything other than completed; do not silently retry a task that was cut off.Human-in-the-loop (HITL)
Question and approval cards appear inassistant_get_messages under pending. Sending follow-up chat text does not resolve them.
Answer or dismiss a question
UsequestionId from pending.questions. For assistant_answer_question, answers is an outer array aligned with the card’s questions. Each inner array must be nonempty and contain {label}, {custom}, or {label, custom} selections with nonempty strings.
assistant_reject_question and its questionId.
Approve or reject a permission
Show the user theaction, title, and params from pending.permissions. Call assistant_answer_permission with its permissionId and response: "once" for one-time approval, or response: "reject" when the user declines. There is no always option over MCP.
After resolving either kind of card, poll assistant_get_messages to follow the turn.
Turn lifecycle and pitfalls
- Blocked, not broken:
turnActive: truewith a pending card means the turn is waiting for a human. Question cards wait for an answer; approval cards expire after about ten minutes. Resolve them using the user’s decision. If your integration cannot wait, useassistant_abortwithsessionIdto stop the turn. - A turn can die at birth:
assistant_send_messagecan returncompletedwitherrorTextand empty or missingassistantText. Checkassistant_get_messages; if no turn is active, send a short nudge such as “Are you still on it?” rather than resending the original text verbatim. - Answer retries are not deduplicated: if an answer or rejection errors or times out, check
assistant_get_messagesfirst. Retry only if the card is still inpending. A404fromassistant_answer_questionmeans the card is no longer outstanding. - No stream re-attach: recover from disconnects with
assistant_get_messagesand its pending cards. A wait timeout does not stop the server-side turn. - Conflicting turn:
409means a turn is already running; poll it or abort it instead of retrying the original message. Session-scopedassistant_abortsucceeds when no turn is running and, withoutexpectedTurnId, also dismisses leftover question cards; optionally passexpectedTurnIdfromturn.id. - Credits and stale sessions:
402means out of credits — stop and ask the user to top up.404means an unknown or archived session.410withsession_machine_replacedmeans the runtime was recycled — start a fresh session.