dsh-mobilecode 0.6.0 → 0.7.0

package/lib/index.js

@@ -18,6 +18,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import * as DeviceBuild from './device-build.js'
 import * as UiTree from './uitree.js'
+import * as RowList from './list-rows.js'
 import * as FrameSource from './frame-source.js'
 import * as StreamAccess from './stream-access.js'
 import { AndroidStreamHost, ROTATION_CYCLE } from './android-stream.js'
@@ -25,7 +26,8 @@ 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'
+import { existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 
 export const name = 'mobilecode'
 export const inject = ['webServer', 'tools', 'systemPrompt']
@@ -385,14 +387,14 @@ function makeRoutes(engine, config, stream) {
         if ((req.method ?? 'GET') !== 'GET') { writeJson(res, 405, { error: 'method not allowed' }); return }
         const token = new URL(req.url ?? '/', 'http://localhost').searchParams.get('token') ?? ''
         const payload = await stream.access.verifyStreamToken(token)
-        if (payload === undefined) { writeJson(res, 403, { error: 'the stream token is invalid or expired' }); return }
-        if (stream.host.streamedSerial !== payload.serial) { writeJson(res, 503, { error: 'the device stream is not running; request a fresh grant' }); return }
+        if (payload === undefined) { writeJson(res, 403, { code: 'token_invalid', error: 'the stream token is invalid or expired' }); return }
+        if (stream.host.streamedSerial !== payload.serial) { writeJson(res, 503, { code: 'stream_not_running', error: 'the device stream is not running; request a fresh grant' }); return }
         const release = stream.host.acquire()
         try {
           await stream.host.ensureStreaming({ serial: payload.serial })
         } catch (error) {
           release()
-          writeJson(res, 502, { error: `the device stream failed to start: ${error instanceof Error ? error.message : String(error)}` })
+          writeJson(res, 502, { code: 'stream_start_failed', error: `the device stream failed to start: ${error instanceof Error ? error.message : String(error)}` })
           return
         }
         const writer = new FrameSource.MultipartFrameWriter(res)
@@ -458,7 +460,8 @@ function makeRoutes(engine, config, stream) {
         writeJson(res, 200, { ok: true, running: true, serial: status.serial, width: status.width, height: status.height })
       },
     },
-    // POST /api/dsh-mobilecode/stream/devices — online device list for the picker.
+    // POST /api/dsh-mobilecode/stream/devices — online device list for the picker
+    // + bootable AVDs (for the "start with device_boot" hint rows).
     {
       kind: 'exact',
       path: API_BASE + '/stream/devices',
@@ -466,11 +469,73 @@ function makeRoutes(engine, config, stream) {
         if (!fence(req, res, true) || !isPost(req, res)) return
         await readBody(req, res)
         try {
-          const devices = await stream.host.listDevices()
+          const [devices, avds] = await Promise.all([
+            stream.host.listDevices(),
+            DeviceBuild.androidAvds().catch(() => []),
+          ])
           const streamed = stream.host.streamedSerial
-          writeJson(res, 200, { ok: true, devices: devices.map((device) => ({ ...device, ...(device.serial === streamed ? { streaming: true } : {}) })) })
+          writeJson(res, 200, {
+            ok: true,
+            avds,
+            devices: devices.map((device) => ({ ...device, ...(device.serial === streamed ? { streaming: true } : {}) })),
+          })
+        } catch (error) {
+          writeJson(res, 503, { code: 'devices_unavailable', error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    // POST /api/dsh-mobilecode/stream/still {device?} — capture ONE fresh
+    // screencap PNG and serve it; returns {path, width, height, dataUrl}. The
+    // panel's Screenshot button uses this (a still is the current pixels, unlike
+    // the live multipart loop). Falls back to the streamed device when device is
+    // omitted. The PNG is written to a temp dir; dataUrl embeds it so the
+    // browser can show it immediately (device_screen writes the same files).
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/still',
+      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 serial = typeof body.device === 'string' && body.device !== '' ? body.device : stream.host.streamedSerial
+          if (!serial) { writeJson(res, 409, { code: 'device_not_found', error: 'no device is streaming; pass a serial' }); return }
+          if (!StreamAccess.SERIAL_PATTERN.test(serial)) { writeJson(res, 400, { code: 'bad_request', error: 'device must be an adb device serial' }); return }
+          const local = await DeviceBuild.screenCapture(serial, tmpdir())
+          if (local === undefined) { writeJson(res, 502, { code: 'capture_failed', error: `could not capture a still of ${serial}` }); return }
+          const size = pngSize(local)
+          const out = { ok: true, path: local, ...(size ? { width: size.width, height: size.height } : {}) }
+          const bytes = readFileSync(local)
+          if (bytes.length > 0 && bytes.length < 4 * 1024 * 1024) {
+            out.dataUrl = 'data:image/png;base64,' + bytes.toString('base64')
+          }
+          writeJson(res, 200, out)
         } catch (error) {
-          writeJson(res, 503, { error: error instanceof Error ? error.message : String(error) })
+          writeJson(res, 502, { code: 'capture_failed', error: `the still capture failed: ${error instanceof Error ? error.message : String(error)}` })
+        }
+      },
+    },
+    // POST /api/dsh-mobilecode/stream/device-action {device, action} — the
+    // panel device menu: notifications / quick_settings / collapse / lock /
+    // wake / assistant (the DEVICE_ACTIONS map device_action uses as a tool).
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/device-action',
+      handler: async (req, res) => {
+        if (!fence(req, res, true) || !isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        const serial = typeof body.device === 'string' && body.device !== '' ? body.device : stream.host.streamedSerial
+        if (!serial) { writeJson(res, 409, { code: 'device_not_found', error: 'no device is streaming; pass a device' }); return }
+        const action = typeof body.action === 'string' ? body.action : ''
+        const argv = DEVICE_ACTIONS[action]
+        if (argv === undefined) { writeJson(res, 400, { code: 'unknown_action', error: `unknown device action "${action}"` }); return }
+        if (!StreamAccess.SERIAL_PATTERN.test(serial)) { writeJson(res, 400, { code: 'bad_request', error: 'device must be an adb device serial' }); return }
+        try {
+          await DeviceBuild.adbRun(serial, ['shell', ...argv])
+          writeJson(res, 200, { ok: true, action, device: serial })
+        } catch (error) {
+          writeJson(res, 502, { code: 'device_action_failed', error: `device action "${action}" failed: ${error instanceof Error ? error.message : String(error)}` })
         }
       },
     },
@@ -484,17 +549,17 @@ function makeRoutes(engine, config, stream) {
         const body = await readBody(req, res)
         if (body === undefined) return
         const serial = body.device
-        if (typeof serial !== 'string' || !StreamAccess.SERIAL_PATTERN.test(serial)) { writeJson(res, 400, { error: 'device must be an adb device serial' }); return }
+        if (typeof serial !== 'string' || !StreamAccess.SERIAL_PATTERN.test(serial)) { writeJson(res, 400, { code: 'bad_request', error: 'device must be an adb device serial' }); return }
         const action = body.action
-        if (typeof action !== 'object' || action === null || typeof action.kind !== 'string') { writeJson(res, 400, { error: 'action must be an object with a kind' }); return }
+        if (typeof action !== 'object' || action === null || typeof action.kind !== 'string') { writeJson(res, 400, { code: 'bad_request', error: 'action must be an object with a kind' }); return }
         const point = (x, y) => typeof x === 'number' && typeof y === 'number' && x >= 0 && x <= 1 && y >= 0 && y <= 1
-        if (action.kind === 'tap' && !point(action.x, action.y)) { writeJson(res, 400, { error: 'tap needs normalized x,y in 0..1' }); return }
-        if (action.kind === 'drag' && !(point(action.fromX, action.fromY) && point(action.toX, action.toY))) { writeJson(res, 400, { error: 'drag needs normalized fromX,fromY,toX,toY in 0..1' }); return }
-        if (action.kind === 'button' && (typeof action.name !== 'string' || action.name === '')) { writeJson(res, 400, { error: 'button requires a non-empty name' }); return }
-        if (action.kind === 'type' && (typeof action.text !== 'string' || action.text === '')) { writeJson(res, 400, { error: 'type requires a non-empty text' }); return }
+        if (action.kind === 'tap' && !point(action.x, action.y)) { writeJson(res, 400, { code: 'bad_request', error: 'tap needs normalized x,y in 0..1' }); return }
+        if (action.kind === 'drag' && !(point(action.fromX, action.fromY) && point(action.toX, action.toY))) { writeJson(res, 400, { code: 'bad_request', error: 'drag needs normalized fromX,fromY,toX,toY in 0..1' }); return }
+        if (action.kind === 'button' && (typeof action.name !== 'string' || action.name === '')) { writeJson(res, 400, { code: 'bad_request', error: 'button requires a non-empty name' }); return }
+        if (action.kind === 'type' && (typeof action.text !== 'string' || action.text === '')) { writeJson(res, 400, { code: 'bad_request', error: 'type requires a non-empty text' }); return }
         if (stream.host.streamedSerial !== serial) {
           const online = await stream.host.listDevices()
-          if (!online.some((device) => device.serial === serial)) { writeJson(res, 409, { error: `device ${serial} is not online` }); return }
+          if (!online.some((device) => device.serial === serial)) { writeJson(res, 409, { code: 'device_offline', error: `device ${serial} is not online` }); return }
         }
         const release = stream.host.acquire()
         try {
@@ -511,11 +576,11 @@ function makeRoutes(engine, config, stream) {
               result = { ok: true, rotation: next }
               break
             }
-            default: writeJson(res, 400, { error: `unknown control action ${JSON.stringify(action.kind)}` }); return
+            default: writeJson(res, 400, { code: 'unknown_action', error: `unknown control action ${JSON.stringify(action.kind)}` }); return
           }
           writeJson(res, 200, result)
         } catch (error) {
-          writeJson(res, 502, { error: `the device control failed: ${error instanceof Error ? error.message : String(error)}` })
+          writeJson(res, 502, { code: 'control_failed', error: `the device control failed: ${error instanceof Error ? error.message : String(error)}` })
         } finally {
           release()
         }
@@ -747,6 +812,24 @@ async function requireAndroidDevice(serial) {
   return target
 }
 
+/**
+ * PNG IHDR hand-parse: read the 8-byte signature + 24-byte IHDR chunk and pull
+ * width/height (big-endian at offsets 16/20). Returns undefined for non-PNGs —
+ * the PNG the screencap writes is always 8-bit RGBA non-interlaced, so no
+ * deeper parsing is needed.
+ */
+function pngSize(filePath) {
+  try {
+    const bytes = readFileSync(filePath)
+    if (bytes.length < 24 || bytes[0] !== 0x89 || bytes[1] !== 0x50 || bytes[2] !== 0x4e || bytes[3] !== 0x47) return undefined
+    const width = bytes.readUInt32BE(16)
+    const height = bytes.readUInt32BE(20)
+    return width > 0 && height > 0 ? { width, height } : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /** Common key names → Android keycode. Anything else can be passed as a raw keycode integer. */
 const KEYCODES = {
   back: 4, home: 3, menu: 82, recents: 187, app_switch: 187, enter: 66, tab: 61, space: 62,
@@ -1199,12 +1282,12 @@ function devicePerfTool() {
         DeviceBuild.adbRun(serial, ['shell', 'dumpsys', 'battery']).catch(() => ''),
         DeviceBuild.adbRun(serial, ['shell', 'cat', '/proc/cpuinfo']).catch(() => ''),
       ])
-      return {
+      return DeviceBuild.jsonSafe({
         serial,
         memory: DeviceBuild.parseMeminfo(meminfo),
         battery: parseBatteryShaped(battery),
         cpu: DeviceBuild.parseCpuinfo(cpuinfo),
-      }
+      })
     },
   })
 }
@@ -1257,7 +1340,7 @@ function deviceAppInfoTool() {
       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
+      return DeviceBuild.jsonSafe(info)
     },
   })
 }
@@ -1368,6 +1451,365 @@ function deviceRebootTool() {
   })
 }
 
+function deviceUiRowsTool() {
+  return defineTool({
+    name: 'device_ui_rows',
+    description: 'Detect the list/feed ROWS on the attached Android screen (Settings pages, inboxes, feeds): every row reports ' +
+      'its index, an isomorphic group id, its pixel frame, the aggregated visible label, and any parsed counters (e.g. "3万 粉丝" ' +
+      '→ {key:"粉丝", value:30000}, "1.2k likes" → {key:"likes", value:1200}). Rows are the unit the user sees — use this instead of ' +
+      'device_ui_tree when the screen is a list, then tap a row by index with device_tap_row. Row detection is repetition-based: ' +
+      '>=3 sibling subtrees of one parent sharing a class and near-equal height (tolerance max(8px, 15%)).',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      filter: { type: 'string', description: 'Optional case-insensitive substring; keep only rows whose label contains it.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          screen: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              width: { type: 'integer', required: true },
+              height: { type: 'integer', required: true },
+            },
+          },
+          omittedOffscreen: { type: 'integer' },
+          rows: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                index: { type: 'integer', required: true },
+                group: { type: 'integer', required: true },
+                frame: {
+                  type: 'object',
+                  additionalProperties: false,
+                  properties: {
+                    x: { type: 'integer', required: true },
+                    y: { type: 'integer', required: true },
+                    w: { type: 'integer', required: true },
+                    h: { type: 'integer', required: true },
+                  },
+                },
+                label: { type: 'string', required: true },
+                counters: {
+                  type: 'array',
+                  required: true,
+                  items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                      key: { type: 'string', required: true },
+                      value: { type: 'number', required: true },
+                      raw: { type: 'string', required: true },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', rows: [] }
+        const lines = [`Device: ${v.serial} — ${v.rows.length} row(s)${v.omittedOffscreen ? ` (${v.omittedOffscreen} off-screen omitted)` : ''}`]
+        for (const row of v.rows.slice(0, 20)) {
+          const counterText = row.counters.length > 0 ? ` [${row.counters.map((c) => `${c.key}=${c.value}`).join(', ')}]` : ''
+          lines.push(`  #${row.index} g${row.group} @${row.frame.x},${row.frame.y} ${row.frame.w}x${row.frame.h} — ${row.label || '(no text)'}${counterText}`)
+        }
+        if (v.rows.length > 20) lines.push(`  ... and ${v.rows.length - 20} more`)
+        if (v.rows.length === 0) lines.push('No repeated rows detected — the screen may not be a list, or it may need a scroll (see device_scroll_to).')
+        return [{ type: 'text', text: lines.join('\n') }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const parsed = await UiTree.readUiTree(serial)
+      const screen = UiTree.screenBoundsOf(parsed.roots)
+      const { rows, omittedOffscreen } = RowList.detectRows(parsed.roots, screen)
+      const filter = args.filter !== undefined && String(args.filter).trim() !== '' ? String(args.filter).trim().toLowerCase() : undefined
+      const out = {
+        serial,
+        screen: { width: screen.width, height: screen.height },
+        omittedOffscreen,
+        rows: rows.filter((row) => filter === undefined || row.label.toLowerCase().includes(filter)),
+      }
+      return DeviceBuild.jsonSafe(out)
+    },
+  })
+}
+
+function deviceTapRowTool() {
+  return defineTool({
+    name: 'device_tap_row',
+    description: 'Tap inside a list/feed row by index (from device_ui_rows) at a row-relative position: x,y are fractions of the ' +
+      'row frame (default 0.5,0.5 = the row center). Optional expect_count {key, delta} turns the tap into one verified round trip: ' +
+      'the counter must ALREADY be visible in the row before the tap (refused otherwise — never probe an unknown control), and after ' +
+      'an 800ms settle the row at the same index + position must show the count changed by EXACTLY delta (default +1).',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      row: { type: 'integer', description: 'Zero-based row index from device_ui_rows.', required: true },
+      x: { type: 'number', description: 'Row-relative X fraction 0..1 (0 = left edge, 1 = right edge). Default 0.5.' },
+      y: { type: 'number', description: 'Row-relative Y fraction 0..1. Default 0.5.' },
+      expect_count: {
+        type: 'object',
+        additionalProperties: false,
+        description: 'Verify a counter changed by exactly delta after the tap.',
+        properties: {
+          key: { type: 'string', description: 'Counter key as reported by device_ui_rows (e.g. "粉丝", "likes").', required: true },
+          delta: { type: 'integer', description: 'Expected change: 1 (default) or -1.' },
+        },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          row: { type: 'integer', required: true },
+          x: { type: 'integer', required: true },
+          y: { type: 'integer', required: true },
+          expect: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              verified: { type: 'boolean', required: true },
+              reason: { type: 'string' },
+              before: { type: 'number' },
+              after: { type: 'number' },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', row: 0, x: 0, y: 0 }
+        const lines = [`Tapped row #${v.row} at ${v.x},${v.y} on ${v.serial}`]
+        if (v.expect) {
+          lines.push(`Expect_count: ${v.expect.verified ? 'VERIFIED' : 'NOT verified'}${v.expect.reason ? ` — ${v.expect.reason}` : ''}${v.expect.before !== undefined ? ` (${v.expect.before} → ${v.expect.after})` : ''}`)
+        }
+        return [{ type: 'text', text: lines.join('\n') }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      if (!Number.isInteger(args.row) || args.row < 0) throw new Error('device_tap_row requires a non-negative integer row index (see device_ui_rows).')
+      const parsed = await UiTree.readUiTree(serial)
+      const screen = UiTree.screenBoundsOf(parsed.roots)
+      const { rows } = RowList.detectRows(parsed.roots, screen)
+      const row = rows[args.row]
+      if (row === undefined) throw new Error(`row ${args.row} does not exist — device_ui_rows reported ${rows.length} row(s). Re-run it for fresh indices.`)
+      const fractionX = args.x === undefined ? 0.5 : args.x
+      const fractionY = args.y === undefined ? 0.5 : args.y
+      const expect = args.expect_count
+      if (expect) {
+        const key = RowList.normalizeCountKey(String(expect.key))
+        if (!row.counters.some((c) => c.key === key)) {
+          throw new Error(`refusing to tap: counter "${expect.key}" is not visible in row ${args.row} ("${row.label}") — pass a key device_ui_rows reported.`)
+        }
+      }
+      const point = RowList.planRowTap(rows, args.row, fractionX, fractionY)
+      await DeviceBuild.adbRun(serial, ['shell', 'input', 'tap', String(point.x), String(point.y)])
+      const out = { serial, row: args.row, x: point.x, y: point.y }
+      if (expect) {
+        await new Promise((resolve) => setTimeout(resolve, 800))
+        const fresh = await UiTree.readUiTree(serial).catch(() => undefined)
+        if (fresh === undefined) {
+          out.expect = { verified: false, reason: 'could not re-read the screen after the tap' }
+        } else {
+          const freshRows = RowList.detectRows(fresh.roots, UiTree.screenBoundsOf(fresh.roots)).rows
+          const afterRow = freshRows[args.row]
+          const key = RowList.normalizeCountKey(String(expect.key))
+          const delta = expect.delta === undefined ? 1 : Number(expect.delta)
+          const verification = afterRow !== undefined && RowList.rowsStayedPut(row, afterRow)
+            ? RowList.verifyCountChange(row, afterRow, key, delta)
+            : { verified: false, reason: 'the list moved after the tap (row at this index changed position) — the count could not be verified' }
+          out.expect = {
+            verified: verification.verified,
+            ...(verification.reason ? { reason: verification.reason } : {}),
+            ...(verification.before !== undefined ? { before: verification.before, after: verification.after } : {}),
+          }
+        }
+      }
+      return DeviceBuild.jsonSafe(out)
+    },
+  })
+}
+
+function deviceBacktraceTool() {
+  return defineTool({
+    name: 'device_backtrace',
+    description: 'Capture a native/ANR thread backtrace or crash log for an app on the device. Sends SIGQUIT (kill -3) to the process, ' +
+      'waits for the ART runtime to write the thread dump, then reads the newest /data/anr entry. When /data/anr is unrunnable it falls ' +
+      'back to the logcat crash buffer and says so (engine field: "anr-trace" | "logcat-crash"). Pass package_name or pid.',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      package_name: { type: 'string', description: 'Package of the process to trace (e.g. com.simspoof.app).' },
+      pid: { type: 'integer', description: 'Explicit pid; resolved from package_name when omitted.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          engine: { type: 'string', required: true },
+          package_name: { type: 'string' },
+          pid: { type: 'integer', required: true },
+          trace_path: { type: 'string' },
+          note: { type: 'string' },
+          lines: { type: 'array', items: { type: 'string' }, required: true },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', engine: '', pid: 0, lines: [] }
+        const lines = [`Backtrace of pid ${v.pid} on ${v.serial} (engine: ${v.engine})${v.trace_path ? ` — ${v.trace_path}` : ''}`]
+        if (v.note) lines.push(v.note)
+        for (const line of v.lines.slice(-40)) lines.push(`  ${line}`)
+        if (v.lines.length > 40) lines.push(`  ... ${v.lines.length - 40} more lines`)
+        return [{ type: 'text', text: lines.join('\n') }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const packageName = args.package_name !== undefined && args.package_name !== '' ? String(args.package_name) : undefined
+      let pid
+      if (args.pid !== undefined && Number.isInteger(args.pid) && args.pid > 0) {
+        pid = args.pid
+      } else if (packageName) {
+        const pidout = await DeviceBuild.adbRun(serial, ['shell', 'pidof', '-s', DeviceBuild.shQuoteDevice(packageName)]).catch(() => undefined)
+        const parsedPid = Number((pidout ?? '').trim())
+        if (Number.isInteger(parsedPid) && parsedPid > 0) pid = parsedPid
+        if (pid === undefined) {
+          const ps = await DeviceBuild.adbRun(serial, ['shell', 'ps', '-A']).catch(() => '')
+          const match = ps.split(/\r?\n/).find((line) => /\s+\d+\s/.test(line) && line.split(/\s+/).pop() === packageName)
+          pid = match ? Number(/\s+(\d+)\s+/.exec(match)?.[1]) : undefined
+        }
+      }
+      if (pid === undefined) {
+        throw new Error(`device_backtrace could not resolve a running process for ${packageName ? `"${packageName}"` : 'the request'} on ${serial} — pass a package_name of a running app, or an explicit pid.`)
+      }
+      // SIGQUIT: the ART runtime writes the thread dump to /data/anr/.
+      await DeviceBuild.adbRun(serial, ['shell', 'kill', '-3', String(pid)])
+      await new Promise((resolve) => setTimeout(resolve, 1200))
+      const listing = await DeviceBuild.adbRun(serial, ['shell', 'ls', '-t', '/data/anr']).catch(() => undefined)
+      const newest = (listing ?? '').split(/\r?\n/).map((line) => line.trim()).filter((line) => line !== '' && !line.includes(' '))[0]
+      if (newest !== undefined) {
+        const content = await DeviceBuild.adbRun(serial, ['shell', 'cat', DeviceBuild.shQuoteDevice(`/data/anr/${newest}`)], { timeoutMs: 30_000 }).catch(() => undefined)
+        if (content !== undefined && content.trim() !== '') {
+          return DeviceBuild.jsonSafe({
+            serial,
+            engine: 'anr-trace',
+            ...(packageName ? { package_name: packageName } : {}),
+            pid,
+            trace_path: `/data/anr/${newest}`,
+            lines: content.split(/\r?\n/).slice(-250),
+          })
+        }
+      }
+      // Fallback: the logcat crash buffer (FATAL/AndroidRuntime lines), filtered by package when known.
+      const log = await DeviceBuild.adbRun(serial, ['logcat', '-b', 'crash', '-d', '-v', 'time']).catch(() => '')
+      const all = log.split(/\r?\n/).filter((line) => /FATAL EXCEPTION|AndroidRuntime|DEBUG|Abort message/.test(line))
+      const lines = (packageName ? all.filter((line) => line.includes(packageName)) : all)
+      if (lines.length === 0) {
+        // Keep the honest fallback note: anr-trace failed; crash buffer silent.
+        return DeviceBuild.jsonSafe({
+          serial,
+          engine: 'logcat-crash',
+          ...(packageName ? { package_name: packageName } : {}),
+          pid,
+          note: `SIGQUIT sent to pid ${pid}; /data/anr was ${newest === undefined ? 'empty/unreadable' : `read but produced no content for ${newest}`}; the logcat crash buffer has no matching FATAL lines now. The app may not have crashed — check device_log for the main buffer.`,
+          lines: [],
+        })
+      }
+      return DeviceBuild.jsonSafe({
+        serial,
+        engine: 'logcat-crash',
+        ...(packageName ? { package_name: packageName } : {}),
+        pid,
+        note: '/data/anr unreadable; fell back to the logcat crash buffer.',
+        lines: lines.slice(-200),
+      })
+    },
+  })
+}
+
+function deviceMeminfoTool() {
+  return defineTool({
+    name: 'device_meminfo',
+    description: 'Read a running app\'s memory profile from `dumpsys meminfo <package>`: TOTAL PSS/RSS/Swap-PSS plus the App Summary heap ' +
+      'breakdown (Java/Native/Code/Stack/Graphics) and the top PSS categories (mmap regions etc.). Throws when the package has no running ' +
+      'process. Use to check an app\'s footprint after a run, or to compare builds.',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      package_name: { type: 'string', description: 'Package to profile (see device_apps).', required: true },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          package_name: { type: 'string', required: true },
+          totalPssKb: { type: 'number' },
+          totalRssKb: { type: 'number' },
+          totalSwapPssKb: { type: 'number' },
+          appSummary: {
+            type: 'object',
+            additionalProperties: true,
+            description: 'PSS KB per heap bucket: {javaHeapKb, nativeHeapKb, codeKb, stackKb, graphicsKb}.',
+          },
+          topCategories: {
+            type: 'array',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                name: { type: 'string', required: true },
+                pssKb: { type: 'number', required: true },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', package_name: '' }
+        const mb = (kb) => (kb === undefined ? '?' : `${Math.round(kb / 1024)} MB`)
+        const lines = [`Memory of ${v.package_name} on ${v.serial}`]
+        lines.push(`  TOTAL PSS: ${mb(v.totalPssKb)}  RSS: ${mb(v.totalRssKb)}  SwapPSS: ${mb(v.totalSwapPssKb)}`)
+        if (v.appSummary && Object.keys(v.appSummary).length > 0) {
+          const labels = { javaHeapKb: 'Java heap', nativeHeapKb: 'Native heap', codeKb: 'Code', stackKb: 'Stack', graphicsKb: 'Graphics' }
+          const parts = []
+          for (const [key, label] of Object.entries(labels)) {
+            if (v.appSummary[key] !== undefined) parts.push(`${label}: ${mb(v.appSummary[key])}`)
+          }
+          if (parts.length > 0) lines.push(`  App Summary — ${parts.join(', ')}`)
+        }
+        if (v.topCategories && v.topCategories.length > 0) {
+          lines.push('  Top categories:')
+          for (const category of v.topCategories.slice(0, 6)) lines.push(`    - ${category.name}: ${mb(category.pssKb)}`)
+        }
+        return [{ type: 'text', text: lines.join('\n') }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const packageName = String(args.package_name ?? '').trim()
+      if (packageName === '') throw new Error('device_meminfo requires a package_name (see device_apps).')
+      const output = await DeviceBuild.adbRun(serial, ['shell', 'dumpsys', 'meminfo', packageName], { timeoutMs: 30_000 })
+      const parsed = DeviceBuild.parsePackageMeminfo(output)
+      if (parsed === undefined) throw new Error(`\`dumpsys meminfo ${packageName}\` produced no process block on ${serial} — is ${packageName} running?`)
+      return DeviceBuild.jsonSafe({ serial, package_name: packageName, ...parsed })
+    },
+  })
+}
+
 function deviceBootTool() {
   return defineTool({
     name: 'device_boot',
@@ -1387,6 +1829,11 @@ function deviceBootTool() {
           avd: { type: 'string', required: true },
           booted: { type: 'boolean', required: true },
           alreadyRunning: { type: 'boolean', required: true },
+          presentationMeta: {
+            type: 'object',
+            additionalProperties: true,
+            description: 'Projected into ToolResultNode.meta for the conversation stream card.',
+          },
         },
       },
       render: (_args, value) => {
@@ -1403,7 +1850,10 @@ function deviceBootTool() {
         const name = await DeviceBuild.avdName(row.serial).catch(() => undefined)
         if (name === avd) {
           const booted = await DeviceBuild.waitForBoot(row.serial, timeout)
-          return { serial: row.serial, avd, booted, alreadyRunning: true }
+          return {
+            serial: row.serial, avd, booted, alreadyRunning: true,
+            presentationMeta: { kind: 'android-stream', device: { serial: row.serial, name: avd } },
+          }
         }
       }
       if (!DeviceBuild.emulatorBinary()) throw new Error('No SDK emulator binary found; cannot boot an AVD.')
@@ -1420,7 +1870,10 @@ function deviceBootTool() {
       if (!serial) throw new Error(`No emulator serial appeared for "${avd}" within ${timeout} ms.`)
       const booted = await DeviceBuild.waitForBoot(serial, Math.max(1000, deadline - Date.now()))
       if (!booted) throw new Error(`Emulator ${serial} ("${avd}") did not finish booting within ${timeout} ms.`)
-      return { serial, avd, booted: true, alreadyRunning: false }
+      return {
+        serial, avd, booted: true, alreadyRunning: false,
+        presentationMeta: { kind: 'android-stream', device: { serial, name: avd } },
+      }
     },
   })
 }
@@ -1609,6 +2062,11 @@ function deviceStreamTool(host, access) {
           streamUrl: { type: 'string' },
           width: { type: 'integer' },
           height: { type: 'integer' },
+          presentationMeta: {
+            type: 'object',
+            additionalProperties: true,
+            description: 'Projected into ToolResultNode.meta for the conversation stream card.',
+          },
         },
       },
       render: (_args, value) => {
@@ -1634,7 +2092,14 @@ function deviceStreamTool(host, access) {
       if (!online.some((device) => device.serial === serial)) throw new Error(`device ${serial} is not online; cannot stream it`)
       const info = await host.ensureStreaming({ serial })
       const signed = await access.signStreamToken(serial)
-      return { action, running: true, serial: info.serial, width: info.width, height: info.height, streamUrl: `${API_BASE}/stream?token=${encodeURIComponent(signed.token)}` }
+      return {
+        action, running: true, serial: info.serial, width: info.width, height: info.height, streamUrl: `${API_BASE}/stream?token=${encodeURIComponent(signed.token)}`,
+        presentationMeta: {
+          kind: 'android-stream',
+          device: { serial: info.serial },
+          streamRouteId: `dsh-mobilecode/stream/${info.serial}`,
+        },
+      }
     },
   })
 }
@@ -1697,6 +2162,11 @@ function deviceScreenTool(engine, vision) {
           },
           ocrError: { type: 'string' },
           image: Vision.IMAGE_REF_SCHEMA,
+          presentationMeta: {
+            type: 'object',
+            additionalProperties: true,
+            description: 'Projected into ToolResultNode.meta for the conversation screenshot card.',
+          },
         },
       },
       render: (_args, value) => {
@@ -1752,6 +2222,15 @@ function deviceScreenTool(engine, vision) {
       }
       const image = await Vision.maybeAttachScreenshot(vision, png, exec)
       if (image !== undefined) out.image = image
+      if (png) {
+        out.presentationMeta = {
+          kind: 'android-screenshot',
+          device: { serial },
+          path: png,
+        }
+      } else {
+        out.presentationMeta = { kind: 'android-screenshot', device: { serial } }
+      }
       return out
     },
   })
@@ -2115,6 +2594,14 @@ function guidance() {
     '  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.',
     '- device_status: one normalized snapshot of attached devices, AVDs, running/parked projects, Metro and preview servers.',
+    '- device_ui_rows: detect list/feed ROWS on the attached screen (Settings pages, feeds, inboxes) with per-row index, group,',
+    '  frame, aggregated label and parsed counters (e.g. "3万 粉丝" → 粉丝=30000). Use it before tapping a row.',
+    '- device_tap_row: tap inside a row by index at a row-relative position; optional expect_count {key, delta} verifies the',
+    '  counter changed by exactly delta after the tap (refused when the key is not visible first).',
+    '- device_meminfo: `dumpsys meminfo <pkg>` → TOTAL PSS/RSS/Swap-PSS + App Summary heap buckets + top categories. Use it to',
+    '  check a running app\'s footprint.',
+    '- device_backtrace: SIGQUIT an app process and read its newest /data/anr thread dump; falls back to the logcat crash buffer',
+    '  when /data/anr is unreadable (engine field says which). Deterministic crash/ANR capture for debugging.',
     '',
     'Expo and React Native projects are handled automatically: expo prebuild runs when needed, Metro starts for you,',
     'and the app is installed and launched on the booted simulator/emulator. Failed builds report the error and a log tail.',
@@ -2206,6 +2693,10 @@ export function apply(ctx, config) {
         deviceLogTool(engine),
         deviceStatusTool(engine),
         deviceInputTool(),
+        deviceUiRowsTool(),
+        deviceTapRowTool(),
+        deviceBacktraceTool(),
+        deviceMeminfoTool(),
       ].map((tool) => ctx.tools.register(tool))
       return () => { for (const dispose of disposers) dispose() }
     }, 'dsh-mobilecode: tools')