Launch an app and return its landing screen.

Force-stops the app, optionally clears its data, then starts it (a specific activity if given, else the launcher entry) and reports the settled screen plus any startup log activity.

Args: package: App package id, e.g. com.example.app. activity: Optional fully-qualified or relative activity to start directly. clear_data: If true, pm clear before launch for a fresh-install state.

Return the current screen as a compact, element-indexed list.

One line per interactable/text element with a short id (e1 …) you pass to tap_element / input_text. Screenshots are off by default to save tokens; enable include_screenshot when the layout is visual or the element list is empty (e.g. a canvas-rendered screen).

Args: include_screenshot: Attach a downscaled screenshot image block.

Capture the current screen as an image — no hierarchy dump.

Use this for a purely visual check: canvas/Flutter/game/video screens where the element list comes back empty, a visual sanity check, or evidence capture. It is faster and more reliable than get_screen_state when you only need to see the screen (no uiautomator dump, so it works mid-animation too).

Args: save_path: If set, write the full-resolution PNG to this path and return the path only — no inline image, no token cost. Use for evidence/report assets. If unset, return a downscaled inline image block. max_dim: Max width/height for the inline image (ignored when save_path is set).

Tap an element by id (preferred) or by raw coordinates.

Returns the new screen state and the log delta the tap produced. If the target moved or vanished since the last observation, it is re-resolved by selector, or the fresh screen is returned so you can retarget in one turn.

Args: element: Element id from a recent screen state, e.g. e3. x: X pixel (only if not using element). y: Y pixel (only if not using element).

Type text into a field, optionally focusing it first and submitting.

Phase 1 types via adb shell input text (ASCII only — non-ASCII may be mangled). Pass element to tap-focus a specific field before typing.

Args: text: The text to type. element: Optional field element id to focus first, e.g. e1. submit: If true, press ENTER after typing (submit the form/search).

Query app logcat, PID-scoped to the current app.

By default returns the classified delta since the last action (crashes, ANRs, errors + counts). With level set, returns raw filtered lines at that priority and above.

Args: lines: Max lines to fetch when not scoping to the last action. level: Minimum priority to show raw: V/D/I/W/E. since_last_action: Scope to the window since the most recent action.

Send a hardware/navigation key and return the new screen.

Args: key: Key name (BACK, HOME, ENTER, TAB, DEL, MENU, APP_SWITCH, DPAD_* …) or a numeric Android keycode.

Swipe/drag from one point to another (scroll lists, dismiss sheets).

Args: x1: Start X pixel. y1: Start Y pixel. x2: End X pixel. y2: End Y pixel. duration_ms: Gesture duration; longer = slower, more controlled scroll.

Navigate to a known screen by name, using the learned app map.

Instead of re-exploring the UI, this plans a route over screens the app map has already learned (built automatically as the app is driven), declares the route — e.g. Home —[tap 'Menu']→ Drawer —[tap 'Instellingen']→ Settings with a saved screenshot per hop — then replays each step, re-resolving tapped elements by selector so a shifted layout still lands.

Call with plan_only=True first to see the route (and screenshots) without touching the device, then call again to execute. Fails clearly, with the list of known screens, when the target or a route isn't in the map yet.

Args: target: Screen to reach — matched by name, activity, or how it's reached (the label of the tap that leads there, e.g. "Instellingen"). plan_only: If true, return the planned route without executing it.

Return the learned app map for the current app — where is what.

Lists every known screen (name, activity, fingerprint, saved screenshot) and how each is reached (the incoming transitions), so you can plan against a map before touching the device. The map is built automatically as the app is driven.

Auto-explore the current app to fill the navigation map (bounded, best-effort).

Breadth-first from the current screen: taps each untried element, records where it leads, and returns to a known screen between taps (relaunch → navigate_to). Stays inside the current package and skips destructive-looking controls (logout/delete/…), so an unattended crawl can't wreck account state. Seed a map with this, then drive it deterministically with navigate_to. Call get_map afterwards to see the result.

Args: max_screens: Stop once the map holds this many screens. max_taps: Hard cap on total taps performed during the crawl.

Reset the app to a known-good starting state and verify where it landed.

restart force-stops and relaunches (warm restart); clear also wipes app data first for a fresh-install state. The landing screen becomes the app's known root, so go_home can return to it later. Warns explicitly if the app lands somewhere unexpected instead of silently reporting success.

Args: package: App to reset; defaults to the app currently in the foreground. mode: "restart" (force-stop + relaunch) or "clear" (also pm clear).

Return to the app's root screen, whatever screen you're on.

Escalates cheapest-and-most-deterministic first: follow a learned map route, else unwind the back stack pressing BACK and re-checking the screen after every press (stopping the moment BACK would leave the app), else relaunch. Never blind-presses.

Args: max_back: Maximum BACK presses to try while unwinding before relaunching.