dsh-mobilecode 0.4.0 → 0.6.0

package/lib/index.js

@@ -25,6 +25,7 @@ import * as Vision from './vision.js'
 import { DevicePreviewEngine } from './device-preview.js'
 import * as Setup from './setup.js'
 import { registerMobileSkill } from './skill.js'
+import { existsSync } from 'node:fs'
 
 export const name = 'mobilecode'
 export const inject = ['webServer', 'tools', 'systemPrompt']
@@ -220,6 +221,74 @@ 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) })
+        }
+      },
+    },
+    // POST /api/dsh-mobilecode/connect {host, port?, pairing_code?, pairing_port?} — attach a Wi-Fi device (with optional pairing).
+    {
+      kind: 'exact',
+      path: API_BASE + '/connect',
+      handler: async (req, res) => {
+        if (!fence(req, res, true) || !isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        try {
+          const host = String(body.host ?? '').trim().replace(/^adb:\/\//, '')
+          if (host === '') { writeJson(res, 400, { error: 'host is required' }); return }
+          const port = body.port ?? 5555
+          const target = `${host}:${port}`
+          let paired
+          const code = String(body.pairing_code ?? '').trim()
+          if (code !== '') {
+            const pairPort = body.pairing_port ?? 37000
+            await DeviceBuild.adbPair(`${host}:${pairPort}`, code)
+            paired = true
+          }
+          const connected = await DeviceBuild.adbConnectSerial(target)
+          if (!connected) { writeJson(res, 409, { error: `adb connect ${target} failed — check the Wi-Fi IP/port and Wireless debugging; pass pairing_code + pairing_port if it needs pairing.` }); return }
+          writeJson(res, 200, { ok: true, serial: target, paired: paired === true })
+        } catch (error) {
+          writeJson(res, 502, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    // POST /api/dsh-mobilecode/pair-qr {timeout_ms?} — WIFI:T:ADB QR + mDNS auto-pair + connect (one blocking call).
+    {
+      kind: 'exact',
+      path: API_BASE + '/pair-qr',
+      handler: async (req, res) => {
+        if (!fence(req, res, true) || !isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        try {
+          const timeoutMs = Math.min(Math.max(Number(body.timeout_ms) || 60_000, 10_000), 180_000)
+          const { name, password } = DeviceBuild.randomQrCredentials()
+          const qrText = DeviceBuild.generateQrAdbWifi(name, password)
+          const how = 'Render the returned qr_text as a QR code and scan it with the phone (Settings → Connected devices → Pair by QR). Pairing + connect happen automatically once scanned.'
+          const pairingSerial = await DeviceBuild.waitForMdnsPairing(timeoutMs)
+          if (pairingSerial === undefined) { writeJson(res, 200, { qr_text: qrText, name, password, status: 'timeout', how }); return }
+          await DeviceBuild.adbPair(pairingSerial, password)
+          const connectHost = pairingSerial.split(':')[0]
+          const connected = await DeviceBuild.adbConnectSerial(`${connectHost}:5555`)
+          writeJson(res, 200, connected
+            ? { qr_text: qrText, name, password, status: 'connected', serial: `${connectHost}:5555`, how }
+            : { qr_text: qrText, name, password, status: 'paired-not-connected', serial: pairingSerial, how })
+        } catch (error) {
+          writeJson(res, 502, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
     // GET /api/dsh-mobilecode/doctor → [{name, ok, detail, fix?}] — plugin health check.
     {
       kind: 'exact',
@@ -728,11 +797,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 +808,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 +833,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 +843,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)
@@ -850,6 +982,392 @@ function deviceWaitForTool() {
   })
 }
 
+/** First node matching the tap-element selector (exact, then contains), or undefined. Used by device_scroll_to. */
+function findMatchingNode(roots, selector) {
+  const identifier = selector.identifier !== undefined && selector.identifier.trim() !== '' ? selector.identifier.trim() : undefined
+  const label = selector.label !== undefined && selector.label.trim() !== '' ? selector.label.trim() : undefined
+  if (identifier === undefined && label === undefined) return undefined
+  const matchesValue = (actual, wanted, mode) => actual !== undefined && (mode === 'exact' ? actual === wanted : actual.toLowerCase().includes(wanted.toLowerCase()))
+  const matchesNode = (node, mode) => {
+    if (identifier !== undefined && !matchesValue(node.resourceId, identifier, mode)) return false
+    if (label !== undefined && !matchesValue(node.text, label, mode) && !matchesValue(node.contentDesc, label, mode)) return false
+    return true
+  }
+  const flat = UiTree.flattenNodes(roots)
+  return flat.find((node) => matchesNode(node, 'exact')) ?? flat.find((node) => matchesNode(node, 'contains'))
+}
+
+function deviceScrollToTool() {
+  return defineTool({
+    name: 'device_scroll_to',
+    description: 'Scroll until an element (by resource_id or text/content-desc, exact then substring) comes into view, then ' +
+      'tap nothing — just report it. Repeats: read UI tree → check the selector → swipe up (or left) until found or max_swipes ' +
+      'exhausted. Completes the control loop for long lists: run device_wait_for won\'t scroll, this brings the element to the ' +
+      'screen so a follow-up device_tap_element can hit it. Returns the found node and how many swipes it took.',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      resource_id: { type: 'string', description: 'The resource-id to find, e.g. com.android.settings:id/some_item.' },
+      text: { type: 'string', description: 'Text or content-desc to find (exact wins; falls back to substring).' },
+      max_swipes: { type: 'integer', description: 'Swipe budget before giving up (default 8).' },
+      direction: { type: 'string', enum: ['up', 'left'], description: 'Which way to swipe (default up).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          found: { type: 'boolean', required: true },
+          swipes: { type: 'integer', required: true },
+          node: { type: 'string' },
+          bounds: { type: 'array', items: { type: 'integer' } },
+          x: { type: 'integer' },
+          y: { type: 'integer' },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', found: false, swipes: 0 }
+        return [{ type: 'text', text: v.found
+          ? `Found ${v.node} at ${v.bounds?.join(',') ?? ''} (center ${v.x},${v.y}) after ${v.swipes} swipe(s) on ${v.serial} — device_tap_element it (text/resource_id) or tap ${v.x},${v.y} via device_input`
+          : `Not found after ${v.swipes} swipes on ${v.serial} — the element may live behind a deeper navigation, or the selector is wrong (run device_ui_tree / device_screen to check).` }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const selector = { identifier: args.resource_id, label: args.text }
+      const maxSwipes = Math.min(Math.max(args.max_swipes ?? 8, 1), 20)
+      const direction = args.direction === 'left' ? 'left' : 'up'
+      // Screen size drives the swipe path so it works on any panel.
+      let swipes = 0
+      for (;;) {
+        const parsed = await UiTree.readUiTree(serial)
+        const found = findMatchingNode(parsed.roots, selector)
+        if (found) {
+          const center = UiTree.boundsCenter(found.bounds)
+          return { serial, found: true, swipes, node: found.text || found.contentDesc || found.resourceId || found.type, bounds: [found.bounds.x, found.bounds.y, found.bounds.w, found.bounds.h], x: center.x, y: center.y }
+        }
+        if (swipes >= maxSwipes) return { serial, found: false, swipes }
+        const sizeStr = await DeviceBuild.adbRun(serial, ['shell', 'wm', 'size']).catch(() => '')
+        const override = /Override size:\s*(\d+)x(\d+)/.exec(sizeStr)
+        const physical = /Physical size:\s*(\d+)x(\d+)/.exec(sizeStr)
+        const match = override ?? physical
+        if (!match) throw new Error(`cannot read the screen size of ${serial} (wm size returned nothing) — cannot swipe`)
+        const w = Number(match[1]); const h = Number(match[2])
+        const fromX = Math.round(w / 2); const fromY = Math.round(h * 0.7); const toY = Math.round(h * 0.3)
+        if (direction === 'left') {
+          await DeviceBuild.adbRun(serial, ['shell', 'input', 'swipe', String(Math.round(w * 0.8)), String(Math.round(h / 2)), String(Math.round(w * 0.2)), String(Math.round(h / 2)), '400'])
+        } else {
+          await DeviceBuild.adbRun(serial, ['shell', 'input', 'swipe', String(fromX), String(fromY), String(fromX), String(toY), '400'])
+        }
+        swipes += 1
+        await new Promise((resolve) => setTimeout(resolve, 500))
+      }
+    },
+  })
+}
+
+function deviceConnectTool() {
+  return defineTool({
+    name: 'device_connect',
+    description: 'Attach an Android device over Wi-Fi: `adb connect <host>:<port>` (requires the phone\'s Wireless debugging' +
+      ' "Pair device" flow the first time — pass pairing_code to pair first). Reattaching a known wireless device needs no' +
+      ' code. Returns the connected serial.',
+    parameters: {
+      host: { type: 'string', description: 'IP address (or mDNS name) of the device.' },
+      port: { type: 'integer', description: 'Connect port (default 5555).' },
+      pairing_code: { type: 'string', description: 'Six-digit pairing code shown by "Wireless debugging → Pair device".' },
+      pairing_port: { type: 'integer', description: 'Pairing port shown by the pairing dialog (default 37000).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          paired: { type: 'boolean' },
+          connected: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', connected: false }
+        return [{ type: 'text', text: `${v.connected ? 'Connected' : 'Failed to connect'} to ${v.serial}${v.paired ? ' (paired)' : ''}` }]
+      },
+    },
+    async execute(args) {
+      const host = String(args.host ?? '').trim().replace(/^adb:\/\//, '')
+      if (host === '') throw new Error('device_connect requires a host (IP address).')
+      const port = args.port ?? 5555
+      const target = `${host}:${port}`
+      let paired
+      const code = String(args.pairing_code ?? '').trim()
+      if (code !== '') {
+        const pairPort = args.pairing_port ?? 37000
+        await DeviceBuild.adbPair(`${host}:${pairPort}`, code)
+        paired = true
+      }
+      const connected = await DeviceBuild.adbConnectSerial(target)
+      if (!connected) throw new Error(`adb connect ${target} failed — check the Wi-Fi IP/port and that Wireless debugging is on; if it needs pairing, pass pairing_code + pairing_port.`)
+      return { serial: target, paired, connected: true }
+    },
+  })
+}
+
+function devicePairQrTool() {
+  return defineTool({
+    name: 'device_pair_qr',
+    description: 'The full Wi-Fi pairing flow: generates a WIFI:T:ADB QR string (render it as a QR code — any QR generator ' +
+      'works — and scan it with the phone: Settings → Connected devices → Pair by QR), waits for the phone to advertise its ' +
+      'pairing service over mDNS (`adb mdns services`, needs adb >= 31), then auto-pairs and connects. One call covers ' +
+      'generate → wait → pair → connect.',
+    parameters: {
+      timeout_ms: { type: 'integer', description: 'How long to wait for the QR scan (default 60000).' },
+      serial: { type: 'string', description: 'Only used to pre-check adb is present; pairing targets whatever the QR scan names.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          qr_text: { type: 'string', required: true },
+          name: { type: 'string', required: true },
+          password: { type: 'string', required: true },
+          status: { type: 'string', required: true },
+          serial: { type: 'string' },
+          how: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { qr_text: '', name: '', password: '', status: '' }
+        const lines = [`WIFI:T:ADB QR (status ${v.status})`, `  ${v.qr_text}`, '']
+        if (v.serial) lines.push(`Paired & connected: ${v.serial}`)
+        lines.push('Scan the QR text above with the phone: Settings → Connected devices → Pair by QR. Any QR generator renders it.')
+        return [{ type: 'text', text: lines.join('\n') }]
+      },
+    },
+    async execute(args) {
+      const timeoutMs = Math.min(Math.max(args.timeout_ms ?? 60_000, 10_000), 180_000)
+      const { name, password } = DeviceBuild.randomQrCredentials()
+      const qrText = DeviceBuild.generateQrAdbWifi(name, password)
+      const how = 'Render the returned qr_text as a QR code and scan it with the phone (Settings → Connected devices → Pair by QR). Pairing + connect happen automatically once scanned.'
+      const pairingSerial = await DeviceBuild.waitForMdnsPairing(timeoutMs)
+      if (pairingSerial === undefined) {
+        return { qr_text: qrText, name, password, status: 'timeout', how }
+      }
+      await DeviceBuild.adbPair(pairingSerial, password)
+      // The pairing dialog usually pairs the tls-port; the connect port is 5555 or mdns-advertised — try 5555.
+      const connectHost = pairingSerial.split(':')[0]
+      const connected = await DeviceBuild.adbConnectSerial(`${connectHost}:5555`)
+      if (!connected) {
+        return { qr_text: qrText, name, password, status: 'paired-not-connected', serial: pairingSerial, how }
+      }
+      return { qr_text: qrText, name, password, status: 'connected', serial: `${connectHost}:5555`, how }
+    },
+  })
+}
+
+function devicePerfTool() {
+  return defineTool({
+    name: 'device_perf',
+    description: 'One-shot memory / battery / CPU snapshot of an attached Android device (reads /proc/meminfo, dumpsys battery, ' +
+      '/proc/cpuinfo). Use to check the device\'s resource state before or after a run — cheap and deterministic.',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          memory: { type: 'object', additionalProperties: true },
+          battery: { type: 'object', additionalProperties: true },
+          cpu: { type: 'object', additionalProperties: true },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '' }
+        const mem = v.memory ? `RAM ${v.memory.usedPercent}% used (${Math.round(v.memory.usedKb / 1024)}/${Math.round(v.memory.totalKb / 1024)} MB)` : 'RAM n/a'
+        const bat = v.battery && v.battery.level !== undefined ? `Battery ${v.battery.level}% ${v.battery.temperatureC !== undefined ? `(${v.battery.temperatureC}°C) ` : ''}${v.battery.status}` : 'Battery n/a'
+        const cpu = v.cpu && v.cpu.cores ? `CPU ${v.cpu.cores} cores${v.cpu.hardware ? ` (${v.cpu.hardware})` : ''}` : 'CPU n/a'
+        return [{ type: 'text', text: `${v.serial}: ${mem} · ${bat} · ${cpu}` }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const [meminfo, battery, cpuinfo] = await Promise.all([
+        DeviceBuild.adbRun(serial, ['shell', 'cat', '/proc/meminfo']).catch(() => ''),
+        DeviceBuild.adbRun(serial, ['shell', 'dumpsys', 'battery']).catch(() => ''),
+        DeviceBuild.adbRun(serial, ['shell', 'cat', '/proc/cpuinfo']).catch(() => ''),
+      ])
+      return {
+        serial,
+        memory: DeviceBuild.parseMeminfo(meminfo),
+        battery: parseBatteryShaped(battery),
+        cpu: DeviceBuild.parseCpuinfo(cpuinfo),
+      }
+    },
+  })
+}
+
+/** battery status words: dumpsys battery status 2=charging, 5=full etc. */
+function parseBatteryShaped(output) {
+  const raw = DeviceBuild.parseBattery(output)
+  if (raw === undefined) return undefined
+  const status = { 1: 'unknown', 2: 'charging', 3: 'discharging', 4: 'not charging', 5: 'full' }[raw.status] ?? raw.status
+  const health = { 1: 'unknown', 2: 'good', 3: 'overheat', 4: 'dead', 5: 'over-voltage', 6: 'unspecified', 7: 'cold' }[raw.health] ?? raw.health
+  return { ...raw, status, health }
+}
+
+function deviceAppInfoTool() {
+  return defineTool({
+    name: 'device_app_info',
+    description: 'Detail for one installed app: versionName/versionCode, minSdk/targetSdk, requested permissions, and exported ' +
+      'activities — straight from `dumpsys package <pkg>`. Use to answer "what does this app do / what permissions / which ' +
+      'version" without guessing.',
+    parameters: {
+      package: { type: 'string', description: 'Package name, e.g. com.android.chrome.' },
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          package: { type: 'string', required: true },
+          versionName: { type: 'string' },
+          versionCode: { type: 'string' },
+          minSdk: { type: 'string' },
+          targetSdk: { type: 'string' },
+          permissions: { type: 'array', items: { type: 'string' } },
+          activities: { type: 'array', items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { package: '' }
+        const lines = [`${v.package}`, `  version ${v.versionName ?? '?'} (${v.versionCode ?? '?'}) · minSdk ${v.minSdk ?? '?'} · targetSdk ${v.targetSdk ?? '?'}`]
+        if (v.permissions?.length) lines.push(`  permissions (${v.permissions.length}):`, v.permissions.slice(0, 15).map((p) => `    ${p}`).join('\n'))
+        if (v.activities?.length) lines.push(`  activities (${v.activities.length}):`, v.activities.slice(0, 8).map((a) => `    ${a}`).join('\n'))
+        return [{ type: 'text', text: lines.join('\n') }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const pkg = String(args.package ?? '').trim()
+      if (pkg === '') throw new Error('device_app_info requires a package name.')
+      const output = await DeviceBuild.adbRun(serial, ['shell', 'dumpsys', 'package', pkg])
+      const info = DeviceBuild.parseAppInfo(output, pkg)
+      if (info.versionName === undefined) throw new Error(`package ${pkg} is not installed (dumpsys package returned nothing for it) — run device_apps to list what is.`)
+      return info
+    },
+  })
+}
+
+function deviceInstallTool() {
+  return defineTool({
+    name: 'device_install',
+    description: 'Install a local APK onto an attached Android device (`adb install -r -g`: replace + grant runtime permissions). ' +
+      'The apk_path is a LOCAL path on this host (e.g. a build output). Independent of device_run — use it to sideload a debug ' +
+      'build onto a device whose app is already set up.',
+    parameters: {
+      apk_path: { type: 'string', description: 'Absolute local path to the APK, e.g. F:/app/build/outputs/apk/debug/app-debug.apk.' },
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          apk: { type: 'string', required: true },
+          installed: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', apk: '', installed: false }
+        return [{ type: 'text', text: `Installed ${v.apk} on ${v.serial} (${v.installed ? 'ok' : 'failed'})` }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const apk = String(args.apk_path ?? '').trim()
+      if (apk === '') throw new Error('device_install requires apk_path.')
+      if (!existsSync(apk)) throw new Error(`APK not found on this host: ${apk}`)
+      const output = await DeviceBuild.adbRun(serial, ['install', '-r', '-g', apk], { timeoutMs: 180_000 })
+      if (!/success/i.test(output)) throw new Error(`adb install failed on ${serial}: ${output.slice(-300)}`)
+      return { serial, apk, installed: true }
+    },
+  })
+}
+
+function deviceUninstallTool() {
+  return defineTool({
+    name: 'device_uninstall',
+    description: 'Uninstall an app from an attached Android device (`adb uninstall <pkg>`, keeps data unless -k is wanted). ' +
+      'Irreversible — the app\'s data is removed. Confirm the intent before calling.',
+    parameters: {
+      package: { type: 'string', description: 'Package name to remove, e.g. com.example.app.' },
+      keep_data: { type: 'boolean', description: 'Pass -k to keep the app data (default false).' },
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          package: { type: 'string', required: true },
+          uninstalled: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', package: '', uninstalled: false }
+        return [{ type: 'text', text: `Uninstalled ${v.package} on ${v.serial} (${v.uninstalled ? 'ok' : 'failed'})` }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const pkg = String(args.package ?? '').trim()
+      if (pkg === '') throw new Error('device_uninstall requires a package name.')
+      const argv = args.keep_data === true ? ['uninstall', '-k', pkg] : ['uninstall', pkg]
+      const output = await DeviceBuild.adbRun(serial, argv)
+      if (!/success/i.test(output)) throw new Error(`adb uninstall failed on ${serial}: ${output.slice(-300)}`)
+      return { serial, package: pkg, uninstalled: true }
+    },
+  })
+}
+
+function deviceRebootTool() {
+  return defineTool({
+    name: 'device_reboot',
+    description: 'Reboot an attached Android device: `adb reboot` (normal), recovery, or bootloader. The device goes offline and ' +
+      'comes back in a minute or two — a subsequent call to a device_* tool will auto-wait or fail with a reconnect hint. ' +
+      'Disruptive: rebooting interrupts anything running on the device.',
+    parameters: {
+      mode: { type: 'string', enum: ['normal', 'recovery', 'bootloader'], description: 'Where to reboot into (default normal).' },
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          mode: { type: 'string', required: true },
+          rebooting: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `Rebooting ${value?.serial} into ${value?.mode}` }],
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const mode = args.mode === 'recovery' || args.mode === 'bootloader' ? args.mode : 'normal'
+      const argv = mode === 'normal' ? ['reboot'] : ['reboot', mode]
+      await DeviceBuild.adbRun(serial, argv)
+      return { serial, mode, rebooting: true }
+    },
+  })
+}
+
 function deviceBootTool() {
   return defineTool({
     name: 'device_boot',
@@ -931,7 +1449,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 +1489,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 +1530,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 +1568,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 +1580,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 +1758,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 +1880,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}`)
@@ -1572,6 +2090,16 @@ function guidance() {
     '  expect_text / expect_gone (no separate screenshot needed to know the tap landed).',
     '- device_wait_for: wait for text to appear/disappear (polls the UI tree, falls back to OCR on textless surfaces);',
     '  a timeout is a normal matched:false result, never an error. One call replaces an agent-side poll loop.',
+    '- device_scroll_to: scroll until an element (resource_id or text) comes into view, then report it — use before tapping',
+    '  elements that are off-screen in long lists (Settings pages, app lists). Returns the found node + its center tap point.',
+    '- device_connect / device_pair_qr: attach a Wi-Fi device. device_connect does `adb connect host:port` (pass pairing_code +',
+    '  pairing_port for the first-time "Pair device" flow). device_pair_qr does the full journey: generates a WIFI:T:ADB QR',
+    '  string (render it as a QR code and scan it with the phone: Settings → Connected devices → Pair by QR), waits for the',
+    '  pairing service over mDNS, then auto-pairs and connects. Needs adb >= 31 for the QR flow.',
+    '- device_perf: one-shot RAM / battery / CPU snapshot of an attached device (meminfo + dumpsys battery + cpuinfo).',
+    '- device_app_info / device_install / device_uninstall: per-app detail (version, SDK, permissions, activities via dumpsys',
+    '  package) / sideload a local APK onto a running device (`install -r -g`) / remove an app. Uninstall is destructive.',
+    '- device_reboot: reboot the device (normal / recovery / bootloader). The device drops off then comes back; disruptive.',
     '- device_input: tap/swipe/type/press on the attached Android device at ABSOLUTE pixel coordinates (take the center of a',
     '  device_screen box: x=(x1+x2)/2, y=(y1+y2)/2). The control loop is device_ui_tree → device_tap_element, falling back to',
     '  device_screen → device_input when a surface exposes no accessibility tree. Typing is ASCII over plain adb; non-ASCII',
@@ -1579,6 +2107,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 +2193,15 @@ export function apply(ctx, config) {
         deviceActionTool(),
         deviceAppsTool(),
         deviceLaunchAppTool(),
+        deviceIntentTool(),
+        deviceScrollToTool(),
+        deviceConnectTool(),
+        devicePairQrTool(),
+        devicePerfTool(),
+        deviceAppInfoTool(),
+        deviceInstallTool(),
+        deviceUninstallTool(),
+        deviceRebootTool(),
         deviceStreamTool(streamHost, streamAccess),
         deviceLogTool(engine),
         deviceStatusTool(engine),