PreviewAPK

Run a batch of up to 20 actions in order on the device: tap (x/y fractions, or target {text|id|desc, nth}, or target {ref, snapshot_id}), swipe {x1,y1,x2,y2}, long_press, double_tap, type {text, clear, submit}, key {key: back|home|recents|enter|delete or code}, open_app {package}, close_app {package}, open_url {url}, notifications, wait {ms}, wait_for {text|id|desc, present, timeout_s}. Stops at the first failure — earlier actions stay done — and returns per-action results with timing and error envelopes. NEVER replay a batch whose outcome you don't know; observe first. observe='ui'|'screenshot'|'both' attaches the screen after the batch.

Device controls for realistic QA. action='set_timezone' (IANA tz, e.g. America/New_York) — verified on the device. action='set_locale' (BCP 47 tag, e.g. de-DE; package optional, defaults to the session app) — per-app language, Android 13+ style; relaunch the app if it doesn't switch live. action='set_location' (lat, lon) — GPS reports a mock fix until cleared. action='clear_location'. action='push_file' (local_path on this machine, remote_path under /sdcard, max 10 MB) — test fixtures, seed files. action='pull_file' (remote_path, local_path, max 10 MB). action='list_files' (remote_path folder, default Download). action='delete_file' (remote_path). action='reboot' — restarts the phone (same phone, same data: app, files and settings survive; ~a minute; a running recording is saved first). There is NO clipboard control: not available on these phones.

File a field report about THIS tool — you are one of the few who actually use it, and your report is read and tallied by the team that builds it. Say what broke or behaved unexpectedly (broke), what worked well (worked), what feature you wished it had for your task (wish), and anything you had to work around (workaround). One call, any subset of fields. File it before you stop the session, while the details are fresh — the wishes of working agents are the roadmap.

File the wrap-up when your work on this session is done, and get back message_for_human — relay it to the human VERBATIM. The counts in it (session duration, actions taken, errors) are composed by the SERVER from the session's real record — never state counts from your own memory instead. The report is also stored on the session (visible in the portal, kept in the session archive after the session ends). end_session defaults to FALSE: finishing does not stop the phone — it stays live at the portal link and idle-stops on the normal 15-minute rule. Pass end_session=true only when the human should get the session-record wording and the phone should stop now. File your previewapk_feedback field report too — finish is the human's summary, feedback is the tool team's.

The share link for the live session (view-only; minted at start, dies when the session ends), plus driver state — including driver_note, which tells you if the user took the wheel.

Read the attached app's debug log (logcat) from this session — its prints, warnings, errors and crash traces. Check it after actions and whenever something misbehaves: a crash's exact reason is here. Works after the session ends too (the saved tail of the last session).

Pass the wheel mid-session: to='user' lets the human drive in the portal (e.g. after you've verified a feature); to='agent' gives control back to you.

Get the current screen as a UI element tree (class, text, content-desc, resource id, bounds, center coordinates, state flags) instead of pixels. Much faster and cheaper than a screenshot for navigation and assertions: find elements, read values, check state. Use previewapk_screenshot for visual checks (layout, overlap, images).

List the devices on this account: name, id, profile, Android version, status, attached app. Call this FIRST when the account may have more than one device, then pass the chosen device's name (or id) as the 'device' argument to the other tools.

Read the current screen as a compact numbered snapshot: foreground app, keyboard state, screen size, and the useful elements (ref, type, text, desc, id, pixel bounds/center, state flags) in reading order — plus the same snapshot as compact text. Much cheaper than a screenshot and cheaper than the full hierarchy. Keep the snapshot_id: previewapk_tap with ref + snapshot_id taps an element from it safely (stale_snapshot if the screen changed). Set screenshot=true to also get the frame as an image.

Send an Android keycode: 4=Back, 3=Home, 187=Recents, 66=Enter, 67=Delete.

Upload an APK file from this machine to the device. If the device is OFF it becomes the attached app (then call previewapk_start). If the device is RUNNING and you hold the wheel, the new app is hot-swapped in live — installed and relaunched with no reboot. Returns the parsed app info (swapped=true on a hot swap; deduped=true when identical bytes were already stored). Installing an OLDER versionCode over the app in a live session is refused (version_downgrade) unless replace=true, which uninstalls the installed app first — its data is deleted.

Download a finished recording's MP4 to a local file path on this machine (resumable — a cut transfer picks up where it stopped). Omit rec_id to get the session's latest finished recording.

Start recording the device screen to an MP4 (screenrecord; one recording caps at 180s). Stop it with previewapk_record_stop, then download with previewapk_record_download. A recording in progress is stopped and saved automatically if the session ends or the phone reboots.

Stop the running recording. The MP4 is pulled off the device to the server and indexed (rec_id, size, duration) — download it with previewapk_record_download. Recordings stay downloadable after the session ends.

Bring the session's app back to the foreground — after Back exits to the launcher, or the app crashed or was closed. Takes about 2 seconds; no reboot.

Ask the human for a step only a human should do: a password or 2FA code typed on the phone itself, a payment or consent approval, a CAPTCHA, anything sensitive or irreversible. Records the request in the portal (the device card shows 'Your agent needs you') and returns message_for_human — relay it to the human VERBATIM in chat, then park on previewapk_wait_for with condition='driver' until the wheel comes back (the handback note rides that result). Never ask the human to paste a password or code into chat for you to type — the human types it on the phone. Requires a live session you are driving.

Capture the device's current screen as an image you can see (the real screen — it agrees with the hierarchy). Use it to verify your changes look right. The download resumes automatically if the connection is cut; pass scale=0.5 on weak networks for a quarter-size transfer.

Start a preview session for the device's attached app. driver='agent': you drive and screenshot; the human watches. driver='user': the human drives in the portal; your input is refused. Returns links info — share the session_url from previewapk_get_links with the human.

State of the owner's PreviewAPK device(s): attached app, session status, driver, links. Also carries the handoff block (a pending request for the human: reason + when), the agent's finish_report once filed, and — exactly once, on the first status read after the human hands the wheel back — handback_note + resumed:true: that is how you learn the handback happened, no chat message needed.

Stop the session. The session link dies with it. (previewapk_feedback files a field report about the tool — what broke, what worked, what you wish it had; reports directly shape what gets fixed and built next.)

Swipe from (x1,y1) to (x2,y2), 0..1 fractions. duration_ms optional (default 300).

Tap the screen. Either coordinates (0..1 fractions of the screen, resolution-independent) or a ref from previewapk_observe: pass ref + snapshot_id and the server re-finds that exact element on the current screen first — if it moved or changed, the call fails with stale_snapshot instead of tapping the wrong thing. Requires an agent-driven session.

Tap the element whose visible text matches (exact match preferred, else substring; use index to pick among matches). If several elements match at the same level and no index is given, the call returns an ambiguous_target result with the candidates instead of guessing. Resolves the element's center from the UI hierarchy — prefer this over coordinate taps whenever the target has text.

Type text into the currently focused field on the device. The field must be focused first (tap it) — the call fails honestly when nothing is focused, instead of typing into the void.

Select your working device — the 'cd' of PreviewAPK. After selecting, every other tool talks to this device until you select another or start one (starting also selects). Pass the device NAME (e.g. 'Device 1') or its id, from previewapk_list_devices.

Wait until an element is present on screen (or gone, with present=false), polling the UI. Returns {found, waited_ms} — found=false at the timeout is a result, not an error. Use after actions that load content instead of sleeping blind. With condition='driver' instead of an element: wait until the human hands the wheel back to you (after previewapk_request_human or any takeover) — the result carries the handback note (handback_note, resumed) when there is one. Driver waits default to timeout_s=300 (max 600): a human step takes human time.