@zseven-w/dsh-android

DSH Android

A live Android device inside a DeepSeek Harness conversation — emulator or USB phone, driven entirely through adb.

20 agent tools • in-process live stream, no external helper • three-button navigation panel • Gradle build & run • Vision OCR

npm: @zseven-w/dsh-android · Current plugin release: 0.1.0-rc.4 · Tested with DSH 0.1.1-rc.1

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français · Español · Deutsch · Português · Русский · हिन्दी · Türkçe · ไทย · Tiếng Việt · Bahasa Indonesia

An Android device streamed and controlled from inside a DSH conversation — the agent's tool call in the center, the live device panel on the right

Why DSH Android

DSH Android gives the agent a real Android device inside the conversation — and gives you the pixels. The agent can start a stream on an emulator or a USB-connected phone, build and install a Gradle project, drive the UI by resource-id/text or by OCR, read logcat, and inspect processes and memory, while a live stream of the device renders in a persistent sidebar panel where you can tap, drag, rotate, and press Back / Home / Recents directly on the video. No image blocks and no screen-recording files: visual bytes reach the UI only through signed, expiring URLs served by the DSH webserver.

There is exactly one code path. adb devices -l reports a serial, and that serial is a device's only identity — emulator-5554, a USB serial, or an ip:port target all behave identically. The plugin is bound to no emulator product (AVD, Genymotion, WSA, a cloud device farm), and there is no simulator/real-device split to reason about.

📱 Live device in the conversation	A multipart/x-mixed-replace PNG stream produced in-process and served straight from the latest-frame buffer through signed /_dsh/dsh-android/* routes.
🔌 No external stream helper, no inner port	One persistent adb exec-out child runs while :; do screencap -p; done; the host splits the concatenated PNGs into frames itself. There is no loopback stream server to proxy, no port range to manage, and nothing to adopt after an ungraceful exit.
🧩 One adb code path	Emulators and phones are the same thing to adb and to this plugin. No simctl/WebDriverAgent dual stack, no build-and-trust dance before a physical device works.
🛠️ 20 agent tools	Devices, boot/shutdown, screenshot, interact, Gradle build & run, app listing/launching, uiautomator UI tree + tap-by-element, list/feed row actions, Vision OCR find/tap/wait, logcat, processes, ANR/crash backtrace, meminfo, app info.
👆 Three-button navigation panel	Tap and drag on the live video; a toolbar with ◁ Back · ○ Home · □ Recents plus rotate, screenshot, and refresh; a device menu for the notification shade, quick settings, lock, wake, and the assistant.
🖼️ Native multimodal	On an image-capable model every capture tool (screenshot, interact, tap_element, tap_text, tap_row) returns the screenshot ITSELF as an image block — the model sees the screen directly. OCR stays for pixel-precise text taps and text-only routes; text-only models keep the plain JSON summary.
🔐 Signed loopback-only routes	Every route requires a loopback peer, a loopback Host (DNS rebinding rejected), and Fetch-Metadata/Origin checks — before any capability is consulted. HMAC-SHA256 capabilities expire within 10 minutes.
🔍 Semantic + visual automation	android_ui_tree dumps the uiautomator hierarchy and android_tap_element taps by resource-id, text, or content-description; when the tree is empty or the text is baked into an image, android_find_text / android_tap_text OCR the screen instead of guessing coordinates.

Tools

All 20 tools are registered on every host and return plain JSON — visual bytes reach the UI only through presentationMeta + signed routes, never as image blocks. When adb cannot be resolved the tools stay registered and every call fails with an explanatory error naming the fix.

Coordinates are normalized 0..1 of the streamed frame everywhere. The frame follows the display rotation (a landscape app streams 2400×1080 on a 1080×2400 device) and input tap shares that same space, so no client-side rotation math exists anywhere in this plugin.

Core tools

Tool	What it does	Key parameters
android_devices	List every device adb devices -l reports (serial, state, emulator/physical, model, Android version, API level, AVD name) plus the machine's AVD names under avds. Use it to discover the serial the other tools take. A failed enumeration throws instead of returning an empty list.	—
android_boot	Start the live stream. Pass an ONLINE serial to stream it immediately, or an AVD name to launch that emulator first and stream it once it finishes booting (minutes on a cold start). The stream stays alive for the conversation so the panel can show the device live.	device (required — a serial or an AVD name)
android_shutdown	Shut an emulator down (adb emu kill) and stop the stream when it targets that device. A physical device is refused with the reason: adb cannot power off a phone.	device
android_screenshot	Capture a PNG and return a small JSON summary (path, bytes, dimensions, device); the image renders in the card and the panel, never as an image block.	device (optional — streamed device, else the only online one)
android_interact	Interact with the streamed device: tap at normalized 0..1 coordinates, type text, press a navigation or hardware button (back, home, recents, power, volume_up, volume_down, menu, enter, delete), send a swipe gesture, or scroll. After the action settles (~300 ms) a fresh screenshot shows the effect.	action (required — tap/type/button/gesture/scroll), x/y, text, name, json, device
android_list_apps	List the packages installed on the device (pm list packages), with the version name from dumpsys package and a human label when one is resolvable — a third-party package name cannot be guessed, so list it or pass name to android_launch_app.	device, query (case-insensitive substring, CJK included), include_system (default false)
android_launch_app	Launch an installed app by packageName, or by name (a case-insensitive label substring resolved through the same listing). Exactly one of the two. relaunch force-stops the app first.	packageName or name (exactly one), device, relaunch
android_build_run	Build a Gradle project (./gradlew assembleDebug), install the resulting debug APK (adb install -r), and launch it. Takes minutes for a full build; on failure the result carries the tail of the Gradle error output.	projectPath (required), device

UI-tree and row tools (uiautomator)

Tool	What it does	Key parameters
android_ui_tree	Dump the foreground app's uiautomator hierarchy as nodes — type (the class tail), text, contentDesc, resourceId, bounds in pixels, enabled, focused — capped at ~40 KB (the deepest levels are pruned and truncated is set).	device, max_depth, filter (case-insensitive substring over text/content-description/resource-id)
android_tap_element	Tap an element by identity — resource_id matches the node's resource-id; text matches its text or content-description. Exact match first, then case-insensitive substring; nested duplicates collapse to one target and an ambiguous match lists up to 8 candidates instead of picking one. Disabled elements are refused. The tap lands on the element center, then a ~300 ms screenshot shows the effect; pass expect_text / expect_gone and the tap plus its verification become one round trip.	device, resource_id, text, expect_text, expect_gone
android_ui_rows	Read a list/feed screen (RecyclerView and friends) as ROWS instead of a raw tree: repeated same-shaped children become rows carrying an index, a pixel frame, the aggregated label, and the counters parsed out of that label (number + classifier token, Chinese or English — no app vocabulary is hardcoded). Counter keys round-trip: pass one exactly as listed to android_tap_row.expect_count.	device, max_depth
android_tap_row	Tap at a relative position inside one visible row (index from android_ui_rows; x/y as fractions of that row's frame, default 0.5 = center). The frame comes from a FRESH tree read, so no absolute coordinates are guessed, and an out-of-range index FAILS rather than clamping. With expect_count={key, delta} the tool re-reads the row after ~800 ms and verifies the counter moved by exactly ±1; an unknown key REFUSES the tap before it happens.	device, index (required), x, y, expect_count ({key, delta})

OCR, logs, and debug tools

Tool	What it does	Key parameters
android_find_text	OCR the CURRENT screen with the plugin-compiled Vision helper (accurate recognition, zh-Hans + en-US). Use it when the UI tree is empty or degenerate, for text rendered as graphics (badge counts, prices baked into images), or to independently verify what is on screen. Returns {device, size, items:[{text, confidence, rect}]} where rects are pixel boxes with a top-left origin, confidence-sorted and capped at ~40 KB. macOS host only.	device, query (case-insensitive substring), min_confidence (default 0.3)
android_tap_text	OCR the CURRENT screen and tap the center of the best text match — the same exact → contains → candidate-list rules as android_tap_element, for text the UI tree cannot see. The matched pixel center is normalized against the frame size and sent as a tap; after ~300 ms a fresh screenshot shows the effect. macOS host only.	device, query (required), min_confidence, expect_text, expect_gone
android_wait_for	Wait until text appears or disappears, polling the same capture + OCR pipeline every 600 ms until the condition holds or the timeout expires (default 8 s, max 60 s). A timeout is a normal matched:false answer, never an error. macOS host only.	device, text (required), mode (appear/disappear), timeout_ms, min_confidence
android_logs	Read what the device logs: snapshot (logcat -d -v time over a recent window, default 2m) or follow (a bounded live capture for duration_seconds, default 10, max 60 — never a hanging stream). Filter to one app with bundle_id (the Android package name, resolved to its pid). Output is capped at ~300 lines / 30 KB with a narrowing hint.	device, mode (snapshot/follow), duration, duration_seconds, bundle_id, grep
android_processes	List the device's running processes (ps -A) as {pid, name} — the pid source for android_backtrace.	device, filter (case-insensitive substring over the process name)
android_backtrace	Ask the process to dump its stacks (kill -3) and read the resulting ANR trace from /data/anr/. Most non-rooted devices refuse that directory, so the tool degrades to the crash buffer (logcat -b crash -d) and reports honestly which engine answered and what it cannot see.	device, pid or bundle_id
android_meminfo	Parse `dumpsys meminfo
`: total PSS, the Java/native/graphics split, and the top categories — the Android answer to a leak summary.	device, bundle_id (required)
android_app_info	Installed-app facts from `dumpsys package
: version name and code, data directory, code path, first-install time, and the system flag. A missing app returns installed: falseplus a note namingandroid_list_apps` — it does not throw.	device, bundle_id (required)

Display surfaces

• Sidebar panel. The live view lives in a persistent right-hand panel (a fixed dock that pushes the conversation aside, or a centered overlay on narrow viewports). It renders the live PNG stream and accepts click-to-tap and drag-to-gesture directly on the video, with a toolbar carrying ◁ Back, ○ Home, □ Recents, rotate, screenshot, and refresh. A device menu runs the five device-level actions (notification shade, quick settings, lock, wake, assistant). The device picker lists every adb device in ONE list, grouped by kind, with offline AVDs shown as a hint pointing at android_boot rather than a boot-on-click. Size modes and frame styles (frameless / bezel / phone shell) work as in the iOS twin; the panel adapts its aspect ratio from the frame's own natural size, so a rotation needs no configuration.
• Compact conversation cards. Tool results render as one-line cards with no inline imagery: the device name, an action sub-label, a status badge, and an "open in sidebar" cue. Clicking the row opens the panel.
• Status capsule above the input. While the panel is closed and a stream is online, a small pill appears above the composer and opens the panel when clicked.
• Standard mode and Code Mode. Standard sessions use the host-projected presentationMeta; nested Code Mode dispatches carry no meta, so the client reconstructs the identical meta from the durable result JSON — the panel, the cards, and the capsule work in both.

Security

• The browser never talks to adb, and there is no inner port to talk to. The stream is produced in this process and served from memory; every byte crosses the DSH webserver origin through plugin-owned /_dsh/dsh-android/* routes: /stream/ (live multipart PNG), /screenshot/ (cached PNG), plus /grant, /switch-device, /devices, /capture, /status, /control, and /device-action. This is a strictly smaller attack surface than a proxied loopback stream server.
• A triple loopback fence, applied before any capability is read. The transport peer must be a loopback address, the Host header must name a loopback authority (so a DNS-rebinding Host is rejected), and Fetch-Metadata/Origin must be same-origin. Host and Origin are caller-controlled data and are never trusted on their own.
• HMAC-SHA256 capabilities expiring within 10 minutes, formatted base64url(payload).base64url(mac) and signed with a 32-byte per-DSH-home key (/cache/dsh-android/stream-access.key, mode 0600, created atomically). A capability minted for one device stops working the moment another device takes the stream slot, and a screenshot capability cannot be replayed against the stream route.
• The screenshot route serves exactly one directory. Paths are walked with lstat (any symbolic link is refused), finished with a realpath containment check, opened with O_NOFOLLOW, size-bounded, and re-validated after the read — so a file swapped for a symlink between minting and fetching is never served.