dsh-mobilecode 0.5.0 → 0.6.1

package/lib/device-build.js

@@ -763,6 +763,63 @@ async function adbConnect(serial) {
   return /connected|already connected/i.test(`${result.out}\n${result.err}`)
 }
 
+/** Attach a Wi-Fi device: `adb connect <ip>:<port>`; true on success. Never throws (returns false with no side effect). */
+export async function adbConnectSerial(serial) {
+  return adbConnect(serial)
+}
+
+/**
+ * Pair a Wi-Fi device (Android 11+ requires pairing before the first connect):
+ * `adb pair <ip>:<pair-port> <code>`. Resolves when pairing succeeded.
+ */
+export async function adbPair(serial, code) {
+  const result = await captureFull(adb(), ["pair", serial, String(code)], { timeoutMs: 20_000 })
+  if (/successfully paired/i.test(`${result.out}\n${result.err}`)) return true
+  throw new Error(`adb pair ${serial} failed: ${adbFailTail(result) || "no output"}`)
+}
+
+/**
+ * Parse `adb mdns services` output for the pairing service the device advertises
+ * while its "pair using QR code" dialog is open. Returns the `ip:port` the
+ * pairing broadcast listens on, or undefined.
+ */
+export function parseMdnsPairing(output) {
+  const line = String(output).split(/\r?\n/).find((row) => row.includes("_adb-tls-pairing._tcp"))
+  if (line === undefined) return undefined
+  const address = /(\d{1,3}(?:\.\d{1,3}){3}:\d+)/.exec(line)?.[1] ?? /(\[[0-9a-f:]+\]:\d+)/.exec(line)?.[1]
+  return address ?? undefined
+}
+
+/** A Wi-Fi QR code the device scanner accepts: `WIFI:T:ADB;S:<name>;P:<password>;;`. */
+export function generateQrAdbWifi(name, password) {
+  return `WIFI:T:ADB;S:${name};P:${password};;`
+}
+
+/**
+ * Poll `adb mdns services` until the phone's pairing dialog advertises
+ * `_adb-tls-pairing._tcp` (resolves to its `ip:port`), or undefined on timeout.
+ * Requires adb with mdns support (>= 31). Non-serial, read-only.
+ */
+export async function waitForMdnsPairing(timeoutMs = 60_000, pollMs = 1_500) {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    const result = await captureFull(adb(), ["mdns", "services"], { timeoutMs: 5_000 }).catch(() => null)
+    if (result && result.code === 0) {
+      const address = parseMdnsPairing(result.out)
+      if (address !== undefined) return address
+    }
+    if (Date.now() >= deadline) return undefined
+    await new Promise((resolve) => setTimeout(resolve, pollMs))
+  }
+}
+
+const QR_NAME_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+/** Random ADB QR name (ADB_WIFI_xxxxxxxxxxxxxx-yyyyyy) + 21-char password, matching Android's own structure. */
+export function randomQrCredentials(prefix = "ADB_WIFI") {
+  const pick = (n) => Array.from({ length: n }, () => QR_NAME_CHARS[Math.floor(Math.random() * QR_NAME_CHARS.length)]).join("")
+  return { name: `${prefix}_${pick(14)}-${pick(6)}`, password: pick(21) }
+}
+
 /**
  * The single classified boundary for every serial-targeted adb command.
  * On a transient transport failure with a Wi-Fi serial (ip:port) it attempts
@@ -808,6 +865,118 @@ export function adbIntentArgs({ action, uri, component } = {}) {
   return parts
 }
 
+// ── perf / app-info parsers (pattern credited to newborne/dsh-adb-ultimate) ──
+
+/** Parse `cat /proc/meminfo` into {totalKb, availableKb, usedKb, usedPercent}. */
+export function parseMeminfo(output) {
+  const grab = (name) => {
+    const match = new RegExp(`^${name}:\\s*(\\d+)`, "m").exec(String(output))
+    return match ? Number(match[1]) : undefined
+  }
+  const totalKb = grab("MemTotal")
+  const availableKb = grab("MemAvailable")
+  if (totalKb === undefined) return undefined
+  const usedKb = availableKb === undefined ? undefined : totalKb - availableKb
+  return {
+    totalKb,
+    availableKb,
+    usedKb,
+    usedPercent: usedKb !== undefined && totalKb > 0 ? Math.round((usedKb / totalKb) * 1000) / 10 : undefined,
+  }
+}
+
+/** Parse `dumpsys battery` into {level, temperatureC, status, health, powered}. */
+export function parseBattery(output) {
+  const grab = (name) => {
+    const match = new RegExp(`^\\s*${name}:\\s*(.+)`, "m").exec(String(output))
+    return match ? match[1].trim() : undefined
+  }
+  const levelRaw = grab("level")
+  const tempRaw = grab("temperature")
+  const level = levelRaw ? Number(levelRaw) : undefined
+  const tempRawNum = tempRaw ? Number(tempRaw) : undefined
+  return {
+    level,
+    temperatureC: tempRawNum !== undefined && Number.isFinite(tempRawNum) ? Math.round(tempRawNum) / 10 : undefined,
+    status: grab("status"),
+    health: grab("health"),
+    powered: grab("AC powered") === "true" || grab("USB powered") === "true" || grab("Wireless powered") === "true",
+  }
+}
+
+/** Parse `cat /proc/cpuinfo` into {cores, hardware}. */
+export function parseCpuinfo(output) {
+  const text = String(output)
+  const cores = (text.match(/^processor\s*:/gm) ?? []).length
+  const hardware = /^Hardware\s*:\s*(.+)$/m.exec(text)?.[1]?.trim()
+  return { cores: cores > 0 ? cores : undefined, hardware }
+}
+
+/**
+ * Deep-clean a parsed value for a DSH tool output: drop `undefined` keys (and
+ * undefined array holes) and turn non-finite numbers into `null`, so the value
+ * round-trips JSON losslessly (DSH rejects outputs that lose keys/values on
+ * serialize). Leaves everything else untouched; primitives pass through.
+ */
+export function jsonSafe(value) {
+  if (Array.isArray(value)) {
+    const out = []
+    for (const item of value) {
+      if (item !== undefined) out.push(jsonSafe(item))
+    }
+    return out
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {}
+    for (const [key, item] of Object.entries(value)) {
+      if (item !== undefined) out[key] = jsonSafe(item)
+    }
+    return out
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) return null
+  return value
+}
+
+/** Parse `dumpsys package <pkg>` into {versionName, versionCode, minSdk, targetSdk, permissions, activities}. */
+export function parseAppInfo(output, packageName) {
+  const text = String(output)
+  const grab = (name) => {
+    const match = new RegExp(`${name}=(\\S+)`, "m").exec(text)
+    return match ? match[1] : undefined
+  }
+  const permissions = []
+  const textLines = text.split(/\r?\n/)
+  const headerIndex = textLines.findIndex((line) => line.trim() === "requested permissions:")
+  if (headerIndex >= 0) {
+    for (let i = headerIndex + 1; i < textLines.length; i += 1) {
+      const trimmed = textLines[i].trim()
+      if (trimmed === "" || !/^(android\.permission\.|com\.[^\s]+\.permission\.)[A-Z0-9_.]+$/.test(trimmed)) break
+      permissions.push(trimmed)
+    }
+  }
+  const activities = []
+  const resolverIndex = textLines.findIndex((line) => line.trim() === "Activity Resolver Table:")
+  if (resolverIndex >= 0) {
+    // Real resolver-table rows are `<hex> pkg/.Activity filter <hex>` (or `pkg/.Activity (hex)`):
+    //  5f60459 com.android.settings/.Settings$ApnEditorActivity filter 4e9281e
+    // MIME-type headers (vnd.android.cursor.item/telephony-carrier:) contain a `-` so the
+    // component class [\w.$]+ cannot span it, keeping them out of the match.
+    for (let i = resolverIndex + 1; i < textLines.length && activities.length < 20; i += 1) {
+      const match = /([A-Za-z_][\w.$]*\/[\w.$]+)\s+(?:filter\s+[0-9a-f]+|\([0-9a-f]+\))/i.exec(textLines[i].trim())
+      if (match && !activities.includes(match[1])) activities.push(match[1])
+    }
+  }
+  return {
+    package: packageName,
+    versionName: grab("versionName"),
+    versionCode: grab("versionCode"),
+    minSdk: grab("minSdk"),
+    targetSdk: grab("targetSdk"),
+    permissions: [...new Set(permissions)].slice(0, 60),
+    activities: activities.slice(0, 20),
+  }
+}
+
 /** SDK emulator binary (emulator.exe on Windows), or undefined. */
 export function emulatorBinary() {
   const sdk = androidSdk()

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']
@@ -234,6 +235,60 @@ function makeRoutes(engine, config, stream) {
         }
       },
     },
+    // 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',
@@ -927,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 DeviceBuild.jsonSafe({
+        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 DeviceBuild.jsonSafe(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',
@@ -1649,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',
@@ -1743,6 +2194,14 @@ export function apply(ctx, config) {
         deviceAppsTool(),
         deviceLaunchAppTool(),
         deviceIntentTool(),
+        deviceScrollToTool(),
+        deviceConnectTool(),
+        devicePairQrTool(),
+        devicePerfTool(),
+        deviceAppInfoTool(),
+        deviceInstallTool(),
+        deviceUninstallTool(),
+        deviceRebootTool(),
         deviceStreamTool(streamHost, streamAccess),
         deviceLogTool(engine),
         deviceStatusTool(engine),