List all adb-connected Android devices as {serial, connection_type}.

Returns an empty list (never an error) when no device is connected.

Read device facts: model, manufacturer, Android version, resolution, density.

Reset the session: clear per-device snapshot caches and the execution budget counters (spec execution-budget).

Call this after an EXECUTION_BUDGET_EXCEEDED error to continue, or whenever element ids from get_screen have gone stale (a fresh observer is created on the next screen access).

Returns the reset budget state {action_count, elapsed_seconds, max_actions, max_seconds, exceeded}.

Capture a compact text-mode snapshot of the current screen.

Returns elements as [id] class "label" kind@(x,y) lines plus the screen hash. Elements carry stable ids you can reference in tap().

Return a cheap fingerprint of the current screen (hash of the snapshot).

Call this before and after an action to detect whether the screen changed, without refetching the full snapshot.

Tap a semantic target and verify the result.

Prefer semantic selectors — never compute coordinates yourself:

• by=text: exact text label, e.g. {"by": "text", "value": "保存"}

• by=desc: content-desc label

• by=id: a stable element id from get_screen

• by=bounds: last resort, "x,y" or "l,t,r,b" (raw coordinates)

Returns verification evidence {executed, screen_changed, changed_elements[], screen_hash}, or SELECTOR_AMBIGUOUS with candidates[] when several elements match (retry with by=id).

Swipe the screen by direction (up/down/left/right).

Returns verification evidence {executed, screen_changed, changed_elements[], screen_hash}.

Scroll exactly one viewport page (native one-page scroll).

Type text into an input field.

With target, the field is located semantically first (must be an editable field). Without target, the currently focused field is used. The field is cleared before typing.

Scroll until a semantic target appears (or the scroll reaches its end).

Uses one-viewport-page scrolling and stops as soon as the container boundary is reached (no useless swipes at the end).

Launch an installed app by friendly name or package name.

Unknown/not-installed apps return a structured APP_NOT_INSTALLED error (with a hint to pass the exact package name).

Open a system settings panel via ACTION deep link.

Supported panels: home, about_phone, wifi, bluetooth, display, sound, apps, storage, security, location, battery, network, date, accessibility, language, developer.

Press a system key: back, home, recent, menu, enter, power, volume_up, volume_down, clear.

Block until a semantic target appears or disappears on screen.

Polls fresh snapshots every interval seconds until the condition holds or timeout expires (handles loading screens and transient UI). Never raises on timeout — returns satisfied: false + final hash.

Assert whether a semantic target exists on the current screen.

Structured boolean result — never raises for not-found or a text mismatch, so the model can branch on it directly.

Diff the current screen against the last cached snapshot.

Returns added/removed/text-changed element lists (stable-id diff) plus both screen hashes — the explicit counterpart of the automatic evidence returned by every action tool.

Scroll and AGGREGATE every matching element across the screens passed.

Unlike scroll_until (first hit), smart_scroll visits each screen in the scroll budget and returns ALL matches with their positions. Reuses the one-viewport-page scrolling + end detection; on tree-failed screens the OCR layer is aggregated for free.

Locate a described element via the VLM grounding layer (read-only).

The THIRD perception layer (tree -> OCR -> VLM): when the accessibility tree and OCR cannot resolve a target on a tree-failed screen (Flutter/ Unity/games), this asks a vision-language model for the element's bounding box on the current screenshot.