dsh-mobilecode 0.4.0 → 0.5.0

package/README.md

@@ -87,6 +87,11 @@ drawer:
 - `device_apps` / `device_launch_app` — list installed packages (third-party by
   default) so a package name is never guessed / launch one by package or a
   unique substring, with `relaunch` for a cold start.
+- `device_intent` — open anything by Android intent: an `action` (e.g.
+  `android.settings.WIFI_SETTINGS`), a deep-link `uri` (`geo:`, `https://`,
+  `file://`), or an explicit `component` (`pkg/.Activity`). Reaches screens no
+  tap can address. Values are single-quoted for the device shell (apostrophes
+  escaped, control characters refused), so metacharacters stay inert.
 - `device_stream` — drive the live screen stream the panel shows: `start` an
   online device (returns a signed `streamUrl`), `status`, or `stop`. Agents that
   just need to see the screen should prefer `device_screen` / `device_ui_tree`.
@@ -148,6 +153,9 @@ the plain JSON summary (path + UI tree + OCR) with no new error.
     Fix button for auto-fixable checks (PaddleOCR install).
   - **PaddleOCR** — install status, progress log, and the install button.
   - **AI Prompt** — the copyable agent prompt.
+  - **Connection** — the resolved adb binary path and every device `adb` sees
+    (serial, state dot, model, USB / Wi-Fi badge), straight from
+    `GET /connection`. Explains the Wi-Fi reconnect policy.
 - The same settings appear as a **`MobileCode` page in the DSH Settings**
   (registered as a `settings.section` slot, like the other installed plugins),
   so they are reachable from Settings even when the Devices pane is closed.
@@ -159,7 +167,22 @@ the plain JSON summary (path + UI tree + OCR) with no new error.
 `directory` + `platform` body, mirroring mobilecode's `server.devicePreview`
 group — plus setup endpoints: `GET /welcome`, `POST /welcome/dismiss`,
 `GET /doctor`, `POST /doctor/fix {id}`, `GET /ocr`, `POST /ocr/install`,
-`GET/POST /settings`.
+`GET/POST /settings`, `GET /connection`.
+
+**One classified adb boundary** — every serial-targeted adb command runs through
+`adbRun()` in `lib/device-build.js`:
+
+- A transport failure (`device not found` / `offline` / `unauthorized` /
+  `closed` / `no devices`) on a **Wi-Fi serial** (`ip:port`) gets exactly ONE
+  `adb connect` retry. Read-only commands (the `replaySafeAdb` allowlist:
+  `exec-out`/`screencap`/`uiautomator`/`dumpsys`/`getprop`/`logcat`/`cat`/…)
+  then replay automatically; **side-effectful ones never do** — a replayed tap
+  could double-tap — they raise "reconnected — call again" instead.
+- USB serials and non-transport failures (a real `am start` error, a
+  `SecurityException`) surface as classified, actionable errors — the old
+  silent `capture()` → `""` swallowing is gone on agent-facing paths.
+- Tolerant internal callers (boot polling, IME checks) opt back into
+  best-effort with an explicit `.catch(() => "")`.
 
 ## How it works
 

package/lib/android-stream.js

@@ -247,7 +247,7 @@ export class AndroidStreamHost {
 
   async getRotation(serial) {
     try {
-      const value = Number((await DeviceBuild.capture(DeviceBuild.adb(), ['-s', serial, 'shell', 'settings', 'get', 'system', 'user_rotation'])).trim())
+      const value = Number((await DeviceBuild.adbRun(serial, ['shell', 'settings', 'get', 'system', 'user_rotation'])).trim())
       return ROTATION_CYCLE.includes(value) ? value : 0
     } catch {
       return 0
@@ -263,8 +263,7 @@ export class AndroidStreamHost {
   }
 
   async #shell(serial, shell) {
-    const code = await DeviceBuild.exec(DeviceBuild.adb(), ['-s', serial, 'shell', ...shell], { timeoutMs: CONTROL_TIMEOUT_MS }).exit
-    if (code !== 0) throw new Error(`adb shell ${shell.join(' ')} failed (exit ${code})`)
+    await DeviceBuild.adbRun(serial, ['shell', ...shell], { timeoutMs: CONTROL_TIMEOUT_MS })
   }
 
   async #keepAliveTick() {
@@ -371,7 +370,7 @@ export class AndroidStreamHost {
 
 /** Override-aware physical screen size for the non-streaming control fallback. */
 async function screenSize(serial) {
-  const output = await DeviceBuild.capture(DeviceBuild.adb(), ['-s', serial, 'shell', 'wm', 'size'])
+  const output = await DeviceBuild.adbRun(serial, ['shell', 'wm', 'size'])
   const match = /Override size:\s*(\d+)x(\d+)/.exec(output) ?? /Physical size:\s*(\d+)x(\d+)/.exec(output)
   if (!match) throw new Error(`cannot read the screen size of ${serial}`)
   return { width: Number(match[1]), height: Number(match[2]) }

package/lib/client.js

@@ -121,6 +121,13 @@ window.__ModuleLoader__.load({
 .mc-live-nav button { border: 1px solid light-dark(rgba(0,0,0,.16), rgba(255,255,255,.18)); background: light-dark(#fff, #20242b); color: inherit; border-radius: 999px; width: 40px; height: 32px; cursor: pointer; font-size: 14px; }
 .mc-live-nav button:hover { background: light-dark(rgba(0,0,0,.06), rgba(255,255,255,.1)); }
 .mc-live-cap { font-size: 11px; color: light-dark(#6b7078, #9aa0a8); text-align: center; }
+.mc-device-list { display: flex; flex-direction: column; gap: 4px; margin: 8px 0; }
+.mc-device-row { display: flex; align-items: center; gap: 8px; padding: 6px 8px; border: 1px solid light-dark(rgba(0,0,0,.12), rgba(255,255,255,.14)); border-radius: 8px; }
+.mc-dot { width: 8px; height: 8px; border-radius: 50%; flex: none; display: inline-block; background: #9e9e9e; }
+.mc-dot[data-on="true"] { background: #4caf50; box-shadow: 0 0 6px rgba(76,175,80,.6); }
+.mc-serial { font-weight: 600; font-family: ui-monospace, Consolas, monospace; font-size: 12px; }
+.mc-badge { font-size: 11px; padding: 1px 7px; border-radius: 999px; background: light-dark(rgba(0,0,0,.07), rgba(255,255,255,.12)); }
+.mc-warn { color: #b3261e; font-size: 12px; margin: 6px 0; }
 `;
 		//#endregion
 
@@ -140,13 +147,13 @@ window.__ModuleLoader__.load({
 		}
 
 		const getInfo = async (directory) => {
-			const url = API_BASE + (directory ? "?directory=" + encodeURIComponent(directory) : "");
+			const url = location.origin + API_BASE + (directory ? "?directory=" + encodeURIComponent(directory) : "");
 			const response = await fetch(url);
 			if (!response.ok) throw new Error("HTTP " + response.status);
 			return response.json();
 		};
 		const post = async (path, body) => {
-			const response = await fetch(API_BASE + path, {
+			const response = await fetch(location.origin + API_BASE + path, {
 				method: "POST",
 				headers: { "content-type": "application/json" },
 				body: JSON.stringify(body ?? {}),
@@ -155,14 +162,14 @@ window.__ModuleLoader__.load({
 			return response.json();
 		};
 		const apiGet = async (path) => {
-			const response = await fetch(API_BASE + path);
+			const response = await fetch(location.origin + API_BASE + path);
 			if (!response.ok) throw new Error("HTTP " + response.status);
 			return response.json();
 		};
 		// POST that surfaces the server's JSON error copy (stream routes return
 		// human-readable 4xx bodies the generic post() would flatten to "HTTP 409").
 		const streamPost = async (path, body) => {
-			const response = await fetch(API_BASE + path, {
+			const response = await fetch(location.origin + API_BASE + path, {
 				method: "POST",
 				headers: { "content-type": "application/json" },
 				body: JSON.stringify(body ?? {}),
@@ -374,7 +381,9 @@ window.__ModuleLoader__.load({
 				if (!device) return;
 				try {
 					const r = await streamPost("/stream/grant", { device });
-					setStreamUrl(r.streamUrl);
+					// Absolute URL: the plugin card can be hosted under a different
+					// origin/path than the API, and <img> src ignores fetch()'s base.
+					setStreamUrl(location.origin + r.streamUrl);
 					setSerial(r.device);
 					setError("");
 					clearTimeout(grantTimer.current);
@@ -575,14 +584,21 @@ window.__ModuleLoader__.load({
 		}
 
 		/** Settings dialog: tabs for Doctor / PaddleOCR / AI prompt. */
-		/** Shared settings tabs (Doctor / PaddleOCR / AI Prompt) — used by both the ⚙ dialog and the DSH Settings page. */
+		/** Shared settings tabs (Doctor / PaddleOCR / AI Prompt / Connection) — used by both the ⚙ dialog and the DSH Settings page. */
 		function SettingsTabs() {
 			const [tab, setTab] = useState("doctor");
 			const [prompt, setPrompt] = useState("");
 			const [copied, setCopied] = useState(false);
+			const [conn, setConn] = useState(null);
+			const [connError, setConnError] = useState("");
 			useEffect(() => {
 				apiGet("/welcome").then((w) => setPrompt(w.prompt ?? "")).catch(() => {});
 			}, []);
+			useEffect(() => {
+				if (tab !== "connection") return;
+				setConn(null); setConnError("");
+				apiGet("/connection").then(setConn).catch((e) => setConnError(e instanceof Error ? e.message : String(e)));
+			}, [tab]);
 
 			const copy = async () => {
 				const done = await copyText(prompt);
@@ -598,6 +614,7 @@ window.__ModuleLoader__.load({
 					tabButton("doctor", "Doctor"),
 					tabButton("ocr", "PaddleOCR"),
 					tabButton("prompt", "AI Prompt"),
+					tabButton("connection", "Connection"),
 				),
 				tab === "doctor" && h("div", { className: "mc-modal-body" }, h(DoctorView, { onFixed: () => {} })),
 				tab === "ocr" && h("div", { className: "mc-modal-body" }, h(OcrCard, {})),
@@ -611,6 +628,27 @@ window.__ModuleLoader__.load({
 						h("button", { className: "mc-btn mc-copy", onClick: copy }, copied ? "Copied ✓" : "Copy"),
 					),
 				),
+				tab === "connection" && h("div", { className: "mc-modal-body" },
+					h("div", null,
+						h("h3", null, "adb connection"),
+						connError !== "" && h("div", { className: "mc-warn" }, connError),
+						!conn && connError === "" && h("div", { className: "mc-hint" }, "Loading…"),
+						conn && h("div", null,
+							h("div", { className: "mc-hint" }, `adb: ${conn.adb}`),
+							h("div", { className: "mc-device-list" },
+								conn.devices.length === 0 && h("div", { className: "mc-hint" }, "No devices attached. Plug a phone (USB debug) or boot an emulator."),
+								conn.devices.map((d) => h("div", { className: "mc-device-row", key: d.serial },
+									h("span", { className: "mc-dot", "data-on": d.state === "device" ? "true" : undefined }),
+									h("span", { className: "mc-serial" }, d.serial),
+									d.model && h("span", { className: "mc-hint" }, d.model),
+									h("span", { className: "mc-badge" }, d.wifi ? "Wi-Fi" : "USB"),
+									h("span", { className: "mc-hint" }, d.state),
+								)),
+							),
+							h("div", { className: "mc-hint" }, "Wi-Fi serials look like 192.168.1.23:5555 — attach with `adb connect <ip>:5555`. A dropped Wi-Fi link is reconnected once automatically; read-only probes then replay, taps never do."),
+						),
+					),
+				),
 			];
 		}
 

package/lib/device-build.js

@@ -97,17 +97,20 @@ export function exec(command, args, options, onLine) {
   return { child, exit }
 }
 
-/** Run a command purely for its stdout, e.g. a `-json` query. Empty string on failure. */
-export async function capture(command, args, options = {}) {
+/** Run a command, capturing stdout AND stderr. Resolves {code, out, err}. */
+export async function captureFull(command, args, options = {}) {
   const out = []
+  const err = []
   const running = launch(command, args, {
     cwd: options.cwd,
     env: options.env ? { ...process.env, ...options.env } : undefined,
-    stdio: ["ignore", "pipe", "ignore"],
+    stdio: ["ignore", "pipe", "pipe"],
     windowsHide: true,
   })
   running.stdout?.setEncoding("utf8")
+  running.stderr?.setEncoding("utf8")
   running.stdout?.on("data", (chunk) => out.push(chunk))
+  running.stderr?.on("data", (chunk) => err.push(chunk))
   let timer
   if (options.timeoutMs) {
     timer = setTimeout(() => running.kill(), options.timeoutMs)
@@ -118,9 +121,18 @@ export async function capture(command, args, options = {}) {
     running.once("close", (value) => resolve(value ?? -1))
   })
   if (timer) clearTimeout(timer)
-  if (code !== 0) return ""
   const text = out.join("")
-  return options.maxBytes && Buffer.byteLength(text) > options.maxBytes ? text.slice(0, options.maxBytes) : text
+  return {
+    code,
+    out: options.maxBytes && Buffer.byteLength(text) > options.maxBytes ? text.slice(0, options.maxBytes) : text,
+    err: err.join(""),
+  }
+}
+
+/** Run a command purely for its stdout, e.g. a `-json` query. Empty string on failure. */
+export async function capture(command, args, options = {}) {
+  const result = await captureFull(command, args, options)
+  return result.code === 0 ? result.out : ""
 }
 
 /** Direct child pids of `pid`. POSIX only; returns nothing when pgrep is unavailable. */
@@ -715,6 +727,87 @@ export function adb() {
   return exe ?? "adb"
 }
 
+// ── classified adb boundary (Wi-Fi resilience; pattern credited to boheastill/phone-eye) ──
+
+/** Wi-Fi adb serials end in `ip:port` (`192.168.1.23:5555`); USB/emulator serials never do. */
+export function isWifiSerial(serial) {
+  return /:\d+$/.test(serial)
+}
+
+const ADB_TRANSPORT_RE = /no devices|device (?:'.*?' )?not found|device offline|device unauthorized|device still connecting|error: closed|cannot connect to daemon|failed to start daemon/i
+
+/** Why an adb command failed: 'multi-device', 'transport' (transient — a reconnect may fix it), or undefined (real command error). */
+export function classifyAdbFailure(result) {
+  const text = `${result.err}\n${result.out}`
+  if (/more than one device/i.test(text)) return "multi-device"
+  if (ADB_TRANSPORT_RE.test(text)) return "transport"
+  return undefined
+}
+
+/**
+ * Commands that may be auto-replayed after a reconnect: read-only probes only.
+ * Anything else (input/am/pm-mutate/install/screencap-to-file) must never
+ * replay — a replayed `input tap` could double-tap a payment button.
+ */
+export function replaySafeAdb(args) {
+  return /^(exec-out (screencap|cat|uiautomator|logcat|getprop|dumpsys)|shell (screencap|uiautomator|dumpsys|getprop|wm|settings get|pm list|ime list|cat|df|dmesg|logcat|true)|logcat( |$)|emu avd name)/.test(args.join(" "))
+}
+
+function adbFailTail(result) {
+  const text = `${result.err}\n${result.out}`.trim().split(/\r?\n/).filter(Boolean).slice(-3).join(" | ")
+  return text.slice(-300)
+}
+
+async function adbConnect(serial) {
+  const result = await captureFull(adb(), ["connect", serial], { timeoutMs: 15_000 })
+  return /connected|already connected/i.test(`${result.out}\n${result.err}`)
+}
+
+/**
+ * The single classified boundary for every serial-targeted adb command.
+ * On a transient transport failure with a Wi-Fi serial (ip:port) it attempts
+ * exactly one `adb connect`; only read-only commands are then replayed, while
+ * side-effectful ones raise "reconnected — call again". USB serials get a
+ * classified, actionable message instead of an empty result.
+ */
+export async function adbRun(serial, args, options = {}) {
+  const argv = ["-s", serial, ...args]
+  let result = await captureFull(adb(), argv, options)
+  if (result.code === 0) return result.out
+  const kind = classifyAdbFailure(result)
+  if (kind === "multi-device") throw new Error("adb: more than one device/emulator attached — pass an explicit serial (see adb devices)")
+  if (kind !== "transport" || !isWifiSerial(serial)) {
+    throw new Error(kind === "transport"
+      ? `device ${serial} unreachable (${adbFailTail(result)}). For Wi-Fi adb run: adb connect <ip>:5555`
+      : `adb ${String(args[0])} failed on ${serial} (exit ${result.code}): ${adbFailTail(result)}`)
+  }
+  if (!(await adbConnect(serial))) {
+    throw new Error(`device ${serial} unreachable — adb connect failed; check the phone's Wi-Fi IP or replug USB once`)
+  }
+  if (!replaySafeAdb(args)) {
+    throw new Error(`device ${serial} reconnected over Wi-Fi; command not auto-replayed (side effects) — call again`)
+  }
+  result = await captureFull(adb(), argv, options)
+  if (result.code !== 0) throw new Error(`device ${serial} still failing after reconnect (exit ${result.code}): ${adbFailTail(result)}`)
+  return result.out
+}
+
+/** Quote one value for the device shell (`adb shell` rejoins argv through sh -c): '…' with ' → '\''; control chars refused. */
+export function shQuoteDevice(text) {
+  if (/[\x00-\x1f]/.test(text)) throw new Error(`refusing control characters in adb shell argument: ${JSON.stringify(text.slice(0, 40))}`)
+  return `'${text.replace(/'/g, `'\\''`)}'`
+}
+
+/** Build the `am start` argv from intent parts; values are device-shell quoted so metacharacters stay inert. */
+export function adbIntentArgs({ action, uri, component } = {}) {
+  const parts = ["shell", "am", "start"]
+  for (const [flag, value] of [["-a", action], ["-d", uri], ["-n", component]]) {
+    if (value === undefined || String(value) === "") continue
+    parts.push(flag, shQuoteDevice(String(value)))
+  }
+  return parts
+}
+
 /** SDK emulator binary (emulator.exe on Windows), or undefined. */
 export function emulatorBinary() {
   const sdk = androidSdk()
@@ -736,13 +829,13 @@ export async function androidAvds() {
 
 /** True once the serial has finished booting (sys.boot_completed == 1). */
 export async function androidBooted(serial) {
-  const output = await capture(adb(), ["-s", serial, "shell", "getprop", "sys.boot_completed"])
+  const output = await adbRun(serial, ["shell", "getprop", "sys.boot_completed"]).catch(() => "")
   return output.trim() === "1"
 }
 
 /** AVD name of an emulator serial (`adb emu avd name`); undefined for physical/offline. */
 export async function avdName(serial) {
-  const output = await capture(adb(), ["-s", serial, "emu", "avd", "name"])
+  const output = await adbRun(serial, ["emu", "avd", "name"]).catch(() => "")
   const line = output
     .split(/\r?\n/)
     .map((item) => item.trim())
@@ -771,14 +864,14 @@ export function bootEmulator(avd) {
 
 /** True when the ADBKeyboard IME is installed (the only way to type non-ASCII over adb). */
 export async function adbKeyboardReady(serial) {
-  const output = await capture(adb(), ["-s", serial, "shell", "ime", "list", "-s"])
+  const output = await adbRun(serial, ["shell", "ime", "list", "-s"]).catch(() => "")
   return /com\.android\.adbkeyboard/i.test(output)
 }
 
 /** Type one string via the ADBKeyboard broadcast (base64, so any codepoint survives the shell). */
 export async function typeViaAdbKeyboard(serial, text) {
   const msg = Buffer.from(text, "utf8").toString("base64")
-  await exec(adb(), ["-s", serial, "shell", "am", "broadcast", "-a", "ADB_INPUT_B64", "--es", "msg", msg]).exit
+  await adbRun(serial, ["shell", "am", "broadcast", "-a", "ADB_INPUT_B64", "--es", "msg", msg])
 }
 
 /** True when every codepoint is safe for `adb shell input text` (printable ASCII, no shell metachars). */
@@ -819,14 +912,14 @@ export async function androidDevice() {
 
 /** Primary CPU ABI of a device, e.g. `arm64-v8a`. */
 export async function androidAbi(serial) {
-  const output = await capture(adb(), ["-s", serial, "shell", "getprop", "ro.product.cpu.abi"])
+  const output = await adbRun(serial, ["shell", "getprop", "ro.product.cpu.abi"]).catch(() => "")
   const abi = output.trim()
   return /^[a-z0-9_-]+$/i.test(abi) ? abi : undefined
 }
 
 /** Free space on the device's data partition in megabytes, when `df` reports it. */
 export async function androidFreeMb(serial) {
-  return parseFreeMb(await capture(adb(), ["-s", serial, "shell", "df", "-k", "/data"]))
+  return parseFreeMb(await adbRun(serial, ["shell", "df", "-k", "/data"]).catch(() => ""))
 }
 
 /** Second line of `df -k`: Filesystem 1K-blocks Used Available Use% Mounted. */
@@ -931,7 +1024,7 @@ export async function devices(serial) {
 /** Local path of a fresh screenshot of the serial. undefined on failure. */
 export async function screenCapture(serial, outDir) {
   const remote = "/sdcard/dsh-mobilecode-shot.png"
-  await exec(adb(), ["-s", serial, "shell", "screencap", "-p", remote]).exit
+  await adbRun(serial, ["shell", "screencap", "-p", remote])
   const name = `screen-${serial}-${Date.now()}.png`
   const local = path.join(outDir ?? os.tmpdir(), name)
   const pulled = await new Promise((resolve) => {
@@ -952,8 +1045,8 @@ export async function screenCapture(serial, outDir) {
  */
 export async function uiDump(serial) {
   const remote = "/sdcard/dsh-mobilecode-ui.xml"
-  await exec(adb(), ["-s", serial, "shell", "uiautomator", "dump", remote]).exit
-  const xml = await capture(adb(), ["-s", serial, "shell", "cat", remote])
+  await adbRun(serial, ["shell", "uiautomator", "dump", remote])
+  const xml = await adbRun(serial, ["shell", "cat", remote])
   const items = []
   const node = /<node[^>]*>/g
   for (const match of xml.match(node) ?? []) {
@@ -975,7 +1068,7 @@ export async function uiDump(serial) {
 
 /** Foreground activity, e.g. "com.foo/.MainActivity", or undefined. */
 export async function foregroundActivity(serial) {
-  const output = await capture(adb(), ["-s", serial, "shell", "dumpsys", "activity", "activities"])
+  const output = await adbRun(serial, ["shell", "dumpsys", "activity", "activities"]).catch(() => "")
   const line = output.split("\n").find((item) => /topResumedActivity|mResumedActivity/.test(item))
   const match = /ActivityRecord\{[^}]*\s([^\s}]+)\}/.exec(line ?? "")
   return match?.[1] ?? undefined
@@ -983,14 +1076,14 @@ export async function foregroundActivity(serial) {
 
 /** Kernel log (dmesg). Requires adb root — works on emulators, usually not on real devices. */
 export async function dmesg(serial) {
-  return capture(adb(), ["-s", serial, "shell", "dmesg"])
+  return adbRun(serial, ["shell", "dmesg"])
 }
 
 /** logcat snapshot, filtered by buffer/level/package-like substring. */
 export async function logcat(serial, { buffer = "main", lines = 200, filter } = {}) {
-  const args = ["-s", serial, "logcat", "-d", "-t", String(lines)]
+  const args = ["logcat", "-d", "-t", String(lines)]
   if (buffer && buffer !== "all") args.push("-b", buffer)
-  let output = await capture(adb(), args)
+  let output = await adbRun(serial, args)
   if (filter) output = output.split("\n").filter((line) => line.toLowerCase().includes(filter.toLowerCase())).join("\n")
   return output
 }

package/lib/index.js

@@ -220,6 +220,20 @@ function makeRoutes(engine, config, stream) {
         writeJson(res, 200, { ok: true })
       },
     },
+    // GET /api/dsh-mobilecode/connection → {adb, devices:[{serial, state, model?, wifi}]} — connection card data.
+    {
+      kind: 'exact',
+      path: API_BASE + '/connection',
+      handler: async (req, res) => {
+        if (!guard(req, res)) return
+        if ((req.method ?? 'GET') !== 'GET') { writeJson(res, 405, { error: 'method not allowed' }); return }
+        try {
+          writeJson(res, 200, { adb: adbHostInfo(), devices: await connectionDevices() })
+        } catch (error) {
+          writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
     // GET /api/dsh-mobilecode/doctor → [{name, ok, detail, fix?}] — plugin health check.
     {
       kind: 'exact',
@@ -728,11 +742,10 @@ function deviceInputTool() {
     async execute(args) {
       const serial = await requireAndroidDevice(args.serial)
       const action = args.action ?? 'tap'
-      const adbArgs = (shell) => ['-s', serial, 'shell', ...shell]
       switch (action) {
         case 'tap': {
           if (typeof args.x !== 'number' || typeof args.y !== 'number') throw new Error('action=tap requires x and y (integer pixels).')
-          await DeviceBuild.exec(DeviceBuild.adb(), adbArgs(['input', 'tap', String(args.x), String(args.y)])).exit
+          await DeviceBuild.adbRun(serial, ['shell', 'input', 'tap', String(args.x), String(args.y)])
           return { serial, action, sent: `tap ${args.x},${args.y}` }
         }
         case 'swipe': {
@@ -740,13 +753,13 @@ function deviceInputTool() {
             throw new Error('action=swipe requires x, y, x2, y2.')
           }
           const duration = args.duration ?? 200
-          await DeviceBuild.exec(DeviceBuild.adb(), adbArgs(['input', 'swipe', String(args.x), String(args.y), String(args.x2), String(args.y2), String(duration)])).exit
+          await DeviceBuild.adbRun(serial, ['shell', 'input', 'swipe', String(args.x), String(args.y), String(args.x2), String(args.y2), String(duration)])
           return { serial, action, sent: `swipe ${args.x},${args.y}→${args.x2},${args.y2} (${duration}ms)` }
         }
         case 'text': {
           if (typeof args.text !== 'string' || args.text.length === 0) throw new Error('action=text requires a non-empty text string.')
           if (DeviceBuild.isAsciiInput(args.text)) {
-            await DeviceBuild.exec(DeviceBuild.adb(), adbArgs(['input', 'text', DeviceBuild.escapeInputText(args.text)])).exit
+            await DeviceBuild.adbRun(serial, ['shell', 'input', 'text', DeviceBuild.escapeInputText(args.text)])
             return { serial, action, sent: `text "${args.text}"` }
           }
           // Non-ASCII (CJK, emoji, accented) cannot go through `input text`; the
@@ -765,7 +778,7 @@ function deviceInputTool() {
           const raw = String(args.key ?? '')
           const code = /^\d+$/.test(raw) ? Number(raw) : KEYCODES[raw.toLowerCase()]
           if (!code) throw new Error(`unknown key "${raw}" — use a name from ${Object.keys(KEYCODES).join(', ')} or a raw keycode integer.`)
-          await DeviceBuild.exec(DeviceBuild.adb(), adbArgs(['input', 'keyevent', String(code)])).exit
+          await DeviceBuild.adbRun(serial, ['shell', 'input', 'keyevent', String(code)])
           return { serial, action, sent: `key ${raw} (${code})` }
         }
         default:
@@ -775,7 +788,71 @@ function deviceInputTool() {
   })
 }
 
-/** OCR the current screen and report whether `wantedLower` appears; undefined when OCR is unavailable. */
+/** Plain-device adb diagnostics (no serial) for the settings Connection card. */
+export function adbHostInfo() {
+  return DeviceBuild.adb()
+}
+
+/** Lines of `adb devices -l` after the header rows, parsed for the settings Connection card. */
+export async function connectionDevices() {
+  const output = await DeviceBuild.capture(DeviceBuild.adb(), ["devices", "-l"])
+  return parseDeviceLongList(output)
+}
+
+/** Parse `adb devices -l` into [{serial, state, model, wifi}]. */
+export function parseDeviceLongList(output) {
+  return String(output)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !/^List of devices/i.test(line) && !/^\* daemon/i.test(line))
+    .map((line) => {
+      const [serial, state, ...rest] = line.split(/\s+/)
+      const model = /model:(\S+)/.exec(rest.join(" "))?.[1]
+      const row = { serial, state: state || "unknown", wifi: DeviceBuild.isWifiSerial(serial) }
+      if (model) row.model = model
+      return row
+    })
+    .filter((row) => row.serial)
+}
+
+function deviceIntentTool() {
+  return defineTool({
+    name: 'device_intent',
+    description: 'Open anything on the device by Android intent: an action (e.g. android.settings.WIFI_SETTINGS), ' +
+      'a deep-link URI, or an explicit component (package/.Activity). Reaches screens no tap can address — deep ' +
+      'settings pages, app deep links, files. Values are device-shell quoted so metacharacters stay inert.',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      action: { type: 'string', description: 'Intent action, e.g. android.settings.WIFI_SETTINGS or android.intent.action.VIEW.' },
+      uri: { type: 'string', description: 'Data URI the intent carries, e.g. geo:0,0?q=Berlin or a https:// deep link.' },
+      component: { type: 'string', description: 'Explicit component, e.g. com.android.settings/.Settings.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          intent: { type: 'string', required: true },
+          started: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `Started ${value?.intent} on ${value?.serial}` }],
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const argv = DeviceBuild.adbIntentArgs({ action: args.action, uri: args.uri, component: args.component })
+      if (argv.length === 3) throw new Error('device_intent needs at least one of action, uri or component.')
+      const output = await DeviceBuild.adbRun(serial, argv)
+      if (/^Error/i.test(output.trim())) throw new Error(`am start refused the intent on ${serial}: ${output.trim().split(/\r?\n/)[0]}`)
+      const label = [["-a", args.action], ["-d", args.uri], ["-n", args.component]]
+        .filter(([, value]) => value !== undefined && value !== '')
+        .map(([flag, value]) => `${flag} ${value}`)
+        .join(' ')
+      return { serial, intent: label, started: true }
+    },
+  })
+}
 async function ocrHasText(serial, wantedLower) {
   if (!DeviceBuild.ocrPython()) return undefined
   const png = await DeviceBuild.screenCapture(serial)
@@ -931,7 +1008,7 @@ function deviceShutdownTool() {
       if (!isEmulator) {
         throw new Error(`device_shutdown refuses ${serial}: it is a physical device and adb has no power-off verb for phones — use its own power button.`)
       }
-      await DeviceBuild.exec(DeviceBuild.adb(), ['-s', serial, 'emu', 'kill']).exit
+      await DeviceBuild.adbRun(serial, ['emu', 'kill'])
       return { serial, shutdown: true }
     },
   })
@@ -971,15 +1048,15 @@ function deviceActionTool() {
       const serial = await requireAndroidDevice(args.serial)
       const action = String(args.action ?? '')
       if (action === 'rotate') {
-        const current = Number(await DeviceBuild.capture(DeviceBuild.adb(), ['-s', serial, 'shell', 'settings', 'get', 'system', 'user_rotation']))
+        const current = Number(await DeviceBuild.adbRun(serial, ['shell', 'settings', 'get', 'system', 'user_rotation']))
         const next = ((Number.isFinite(current) ? current : 0) + 1) % 4
-        await DeviceBuild.exec(DeviceBuild.adb(), ['-s', serial, 'shell', 'settings', 'put', 'system', 'accelerometer_rotation', '0']).exit
-        await DeviceBuild.exec(DeviceBuild.adb(), ['-s', serial, 'shell', 'settings', 'put', 'system', 'user_rotation', String(next)]).exit
+        await DeviceBuild.adbRun(serial, ['shell', 'settings', 'put', 'system', 'accelerometer_rotation', '0'])
+        await DeviceBuild.adbRun(serial, ['shell', 'settings', 'put', 'system', 'user_rotation', String(next)])
         return { serial, action, rotation: next }
       }
       const shell = DEVICE_ACTIONS[action]
       if (!shell) throw new Error(`unknown action "${action}" — use ${[...Object.keys(DEVICE_ACTIONS), 'rotate'].join(', ')}.`)
-      await DeviceBuild.exec(DeviceBuild.adb(), ['-s', serial, 'shell', ...shell]).exit
+      await DeviceBuild.adbRun(serial, ['shell', ...shell])
       return { serial, action }
     },
   })
@@ -1012,7 +1089,7 @@ function deviceAppsTool() {
     },
     async execute(args) {
       const serial = await requireAndroidDevice(args.serial)
-      const output = await DeviceBuild.capture(DeviceBuild.adb(), ['-s', serial, 'shell', 'pm', 'list', 'packages', ...(args.include_system ? [] : ['-3'])])
+      const output = await DeviceBuild.adbRun(serial, ['shell', 'pm', 'list', 'packages', ...(args.include_system ? [] : ['-3'])])
       const packages = output
         .split(/\r?\n/)
         .map((line) => line.trim())
@@ -1050,7 +1127,7 @@ function deviceLaunchAppTool() {
       const serial = await requireAndroidDevice(args.serial)
       let pkg = String(args.package ?? '').trim()
       if (pkg === '') throw new Error('device_launch_app requires a package name (or a unique substring).')
-      const listOut = await DeviceBuild.capture(DeviceBuild.adb(), ['-s', serial, 'shell', 'pm', 'list', 'packages'])
+      const listOut = await DeviceBuild.adbRun(serial, ['shell', 'pm', 'list', 'packages'])
       const all = listOut
         .split(/\r?\n/)
         .map((line) => line.trim())
@@ -1062,9 +1139,9 @@ function deviceLaunchAppTool() {
         if (matches.length > 1) throw new Error(`"${pkg}" matches ${matches.length} packages (${matches.slice(0, 8).join(', ')}${matches.length > 8 ? ', …' : ''}) — be more specific.`)
         pkg = matches[0]
       }
-      if (args.relaunch) await DeviceBuild.exec(DeviceBuild.adb(), ['-s', serial, 'shell', 'am', 'force-stop', pkg]).exit
-      const code = await DeviceBuild.exec(DeviceBuild.adb(), ['-s', serial, 'shell', 'monkey', '-p', pkg, '-c', 'android.intent.category.LAUNCHER', '1']).exit
-      if (code !== 0) throw new Error(`Could not launch ${pkg} (no launcher activity, or monkey failed with exit ${code}).`)
+      if (args.relaunch) await DeviceBuild.adbRun(serial, ['shell', 'am', 'force-stop', pkg])
+      const launched = await DeviceBuild.adbRun(serial, ['shell', 'monkey', '-p', pkg, '-c', 'android.intent.category.LAUNCHER', '1']).catch((error) => { throw new Error(`Could not launch ${pkg}: ${error instanceof Error ? error.message : error}`) })
+      if (/no activities found|no events to send/i.test(launched)) throw new Error(`Could not launch ${pkg} (no launcher activity).`)
       return { serial, package: pkg, launched: true }
     },
   })
@@ -1240,7 +1317,7 @@ function deviceScreenTool(engine, vision) {
 }
 
 async function captureScreenSize(serial) {
-  const output = await DeviceBuild.capture(DeviceBuild.adb(), ['-s', serial, 'shell', 'wm', 'size'])
+  const output = await DeviceBuild.adbRun(serial, ['shell', 'wm', 'size'])
   // An `wm size` override wins over the physical panel — the input space is the override.
   const override = /Override size:\s*(\d+)x(\d+)/.exec(output)
   const match = override ?? /Physical size:\s*(\d+)x(\d+)/.exec(output)
@@ -1362,7 +1439,7 @@ function deviceTapElementTool() {
       const selector = { identifier: args.resource_id, label: args.text }
       const { node, matchedBy } = UiTree.resolveTapTarget(parsed.roots, selector, { tool: 'device_tap_element', allowOffscreen: args.allow_offscreen === true })
       const center = UiTree.boundsCenter(node.bounds)
-      await DeviceBuild.exec(DeviceBuild.adb(), ['-s', serial, 'shell', 'input', 'tap', String(center.x), String(center.y)]).exit
+      await DeviceBuild.adbRun(serial, ['shell', 'input', 'tap', String(center.x), String(center.y)])
       const describe = () => {
         const parts = []
         if (node.resourceId) parts.push(`resource_id ${node.resourceId}`)
@@ -1579,6 +1656,10 @@ function guidance() {
     '- device_action: notifications / quick_settings / collapse / lock / wake / assistant / rotate.',
     '- device_boot / device_shutdown: boot an AVD by name and wait for boot / shut an emulator down (refuses physical devices).',
     '- device_apps / device_launch_app: list installed packages (never guess a package name) / launch one by package or unique substring.',
+    '- device_intent: open anything by Android intent (action, deep-link URI, or package/.Activity). Reaches screens no tap can address.',
+    '  Every adb command runs through one classified boundary: a dropped Wi-Fi connection (ip:port serial) gets exactly one',
+    '  `adb connect` attempt, read-only commands then replay automatically, and side-effectful ones refuse the replay —',
+    '  a replayed tap could double-tap — and raise "reconnected — call again" instead.',
     '- device_stream: drive the live screen stream the Devices panel shows (status / start an online device / stop). Agents',
     '  that just need to see the screen should prefer device_screen or device_ui_tree.',
     '- device_log: read device logs (logcat main/crash/events, kernel dmesg). Call it when a run fails or an app misbehaves.',
@@ -1661,6 +1742,7 @@ export function apply(ctx, config) {
         deviceActionTool(),
         deviceAppsTool(),
         deviceLaunchAppTool(),
+        deviceIntentTool(),
         deviceStreamTool(streamHost, streamAccess),
         deviceLogTool(engine),
         deviceStatusTool(engine),

package/lib/uitree.js

@@ -13,7 +13,7 @@
  * Ported design credit: ZSeven-W/dsh-android (MIT) src/uitree.ts.
  */
 
-import { adb, capture, exec } from "./device-build.js"
+import { adb, adbRun, exec } from "./device-build.js"
 
 const DUMP_TIMEOUT_MS = 60_000
 const DUMP_MAX_BYTES = 8 * 1024 * 1024
@@ -260,7 +260,7 @@ export async function dumpUiTreeXml(serial) {
   let primaryFailure
   for (let attempt = 0; attempt < 2; attempt += 1) {
     try {
-      const buffer = await capture(adb(), ["-s", serial, "exec-out", "uiautomator", "dump", "/dev/tty"], options)
+      const buffer = await adbRun(serial, ["exec-out", "uiautomator", "dump", "/dev/tty"], options)
       if (buffer === "") throw new Error("the device produced no output")
       return extractHierarchyXml(buffer)
     } catch (error) {
@@ -284,8 +284,8 @@ export async function dumpUiTreeXml(serial) {
   }
   const remotePath = "/sdcard/window_dump.xml"
   try {
-    const notice = await capture(adb(), ["-s", serial, "shell", "uiautomator", "dump", remotePath], options)
-    const buffer = await capture(adb(), ["-s", serial, "exec-out", "cat", remotePath], options)
+    const notice = await adbRun(serial, ["shell", "uiautomator", "dump", remotePath], options)
+    const buffer = await adbRun(serial, ["exec-out", "cat", remotePath], options)
     const xml = extractHierarchyXml(buffer)
     await exec(adb(), ["-s", serial, "shell", "rm", "-f", remotePath]).exit.catch(() => {})
     if (xml.trim() === "") throw new Error(notice.trim() || "empty dump")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mobilecode",
-  "description": "MobileCode for the dsh web GUI: detect iOS/Android projects, run serve-sim / serve-avd preview servers, and build-install-launch the app on the simulator or emulator from the session — plus agent tools (device_run, device_detect). Hot-pluggable — mounted via the profile bundle list + cordis.patch.yml, no dsh source changes.",
-  "version": "0.4.0",
+  "description": "MobileCode for the dsh web GUI: detect iOS/Android projects, run preview servers, and drive the simulator/emulator from the session — 15 agent tools (device_run, device_screen, device_ui_tree, device_tap_element, device_input, device_intent, device_log, live screen stream, multimodal screenshots) with one classified adb boundary. Hot-pluggable — mounted via the profile bundle list + cordis.patch.yml, no dsh source changes.",
+  "version": "0.5.0",
   "type": "module",
   "packageManager": "pnpm@11.22.0",
   "engines": {