dsh-mobilecode 0.2.0 → 0.3.0

package/lib/index.js

@@ -18,6 +18,9 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import * as DeviceBuild from './device-build.js'
 import * as UiTree from './uitree.js'
+import * as FrameSource from './frame-source.js'
+import * as StreamAccess from './stream-access.js'
+import { AndroidStreamHost, ROTATION_CYCLE } from './android-stream.js'
 import { DevicePreviewEngine } from './device-preview.js'
 import * as Setup from './setup.js'
 import { registerMobileSkill } from './skill.js'
@@ -70,11 +73,21 @@ function resolveDirectory(body, config) {
   return process.cwd()
 }
 
-function makeRoutes(engine, config) {
+function makeRoutes(engine, config, stream) {
   const guard = (req, res) => {
     if (!isLoopbackRequest(req)) { writeJson(res, 403, { error: 'forbidden: loopback-only' }); return false }
     return true
   }
+  // Stronger fence for the stream routes: loopback peer + loopback Host +
+  // Sec-Fetch-Site/Origin. POSTs (which mint capabilities) also require Origin.
+  const fence = (req, res, requireOrigin) => {
+    if (!StreamAccess.isTrustedRequest(req, requireOrigin)) { writeJson(res, 403, { error: 'forbidden: loopback trusted-browser only' }); return false }
+    return true
+  }
+  const isPost = (req, res) => {
+    if ((req.method ?? 'GET') !== 'POST') { writeJson(res, 405, { error: 'method not allowed' }); return false }
+    return true
+  }
   const platformOf = (value) => (value === 'ios' || value === 'android' ? value : undefined)
   const routes = [
     // GET /api/dsh-mobilecode?directory=... → current info (platforms, servers, builds, bundler).
@@ -290,6 +303,154 @@ function makeRoutes(engine, config) {
         writeJson(res, 405, { error: 'method not allowed' })
       },
     },
+    // ── live device stream (panel) ──────────────────────────────────────────
+    // GET /api/dsh-mobilecode/stream?token=… — live multipart/x-mixed-replace PNG
+    // stream from the in-process frame loop. The <img> GET carries no Origin, so
+    // the fence here is loopback-only (requireOrigin false).
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream',
+      handler: async (req, res) => {
+        if (!fence(req, res, false)) return
+        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 }
+        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)}` })
+          return
+        }
+        const writer = new FrameSource.MultipartFrameWriter(res)
+        let finished = false
+        const teardown = () => {
+          if (finished) return
+          finished = true
+          unsubscribe()
+          writer.close()
+          release()
+        }
+        const unsubscribe = stream.host.subscribeFrames((frame) => {
+          // Frames for a different serial (after a device switch) must not leak
+          // into a capability minted for the old device.
+          if (stream.host.streamedSerial === payload.serial) writer.writeFrame(frame)
+          else teardown()
+        })
+        res.on('error', teardown)
+        res.on('close', teardown)
+        const latest = stream.host.latestFrame
+        if (latest !== undefined) writer.writeFrame(latest)
+      },
+    },
+    // POST /api/dsh-mobilecode/stream/grant {device?} — mint a fresh stream URL.
+    // Only starts the loop for an ONLINE device; never boots an emulator, never
+    // yanks the stream from a different streaming device.
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/grant',
+      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, { error: 'no device is streaming; pass a serial' }); return }
+          if (!StreamAccess.SERIAL_PATTERN.test(serial)) { writeJson(res, 400, { error: 'device must be an adb device serial' }); 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 }
+          }
+          await stream.host.ensureStreaming({ serial })
+          const signed = await stream.access.signStreamToken(serial)
+          writeJson(res, 200, { ok: true, streamUrl: `${API_BASE}/stream?token=${encodeURIComponent(signed.token)}`, expiresAt: signed.expiresAt, device: serial })
+        } catch (error) {
+          writeJson(res, 502, { error: `the device stream failed to start: ${error instanceof Error ? error.message : String(error)}` })
+        }
+      },
+    },
+    // POST /api/dsh-mobilecode/stream/status {device?} — read-only snapshot;
+    // never starts a stream and never mints tokens.
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/status',
+      handler: async (req, res) => {
+        if (!fence(req, res, true) || !isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        const status = stream.host.status()
+        const filter = body.device
+        const running = status.running && status.serial !== undefined && (filter === undefined || filter === '' || status.serial === filter)
+        if (!running) { writeJson(res, 200, { ok: true, running: false }); return }
+        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.
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/devices',
+      handler: async (req, res) => {
+        if (!fence(req, res, true) || !isPost(req, res)) return
+        await readBody(req, res)
+        try {
+          const devices = await stream.host.listDevices()
+          const streamed = stream.host.streamedSerial
+          writeJson(res, 200, { ok: true, devices: devices.map((device) => ({ ...device, ...(device.serial === streamed ? { streaming: true } : {}) })) })
+        } catch (error) {
+          writeJson(res, 503, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    // POST /api/dsh-mobilecode/stream/control {device, action} — one control op.
+    // tap/drag coordinates are NORMALIZED 0..1 of the streamed frame.
+    {
+      kind: 'exact',
+      path: API_BASE + '/stream/control',
+      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 = body.device
+        if (typeof serial !== 'string' || !StreamAccess.SERIAL_PATTERN.test(serial)) { writeJson(res, 400, { 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 }
+        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 (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 }
+        }
+        const release = stream.host.acquire()
+        try {
+          let result = { ok: true }
+          switch (action.kind) {
+            case 'tap': await stream.host.tap(serial, action.x, action.y); break
+            case 'drag': await stream.host.drag(serial, { fromX: action.fromX, fromY: action.fromY, toX: action.toX, toY: action.toY, ...(typeof action.durationMs === 'number' ? { duration: Math.min(5, action.durationMs / 1000) } : {}) }); break
+            case 'button': await stream.host.button(serial, action.name); break
+            case 'type': await stream.host.type(serial, action.text); break
+            case 'rotate': {
+              const current = await stream.host.getRotation(serial)
+              const next = ROTATION_CYCLE[(ROTATION_CYCLE.indexOf(current) + 1) % ROTATION_CYCLE.length]
+              await stream.host.rotate(serial, next)
+              result = { ok: true, rotation: next }
+              break
+            }
+            default: writeJson(res, 400, { 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)}` })
+        } finally {
+          release()
+        }
+      },
+    },
   ]
   return routes
 }
@@ -583,9 +744,21 @@ function deviceInputTool() {
         }
         case 'text': {
           if (typeof args.text !== 'string' || args.text.length === 0) throw new Error('action=text requires a non-empty text string.')
-          const escaped = args.text.replace(/\s/g, '%s')
-          await DeviceBuild.exec(DeviceBuild.adb(), adbArgs(['input', 'text', escaped])).exit
-          return { serial, action, sent: `text "${args.text}"` }
+          if (DeviceBuild.isAsciiInput(args.text)) {
+            await DeviceBuild.exec(DeviceBuild.adb(), adbArgs(['input', 'text', DeviceBuild.escapeInputText(args.text)])).exit
+            return { serial, action, sent: `text "${args.text}"` }
+          }
+          // Non-ASCII (CJK, emoji, accented) cannot go through `input text`; the
+          // ADBKeyboard IME is the only adb path. Refuse with the fix, never mangle.
+          if (!(await DeviceBuild.adbKeyboardReady(serial))) {
+            throw new Error(
+              `device_input cannot type non-ASCII text ("${args.text}") over plain adb. Install ADBKeyboard `
+              + 'on the device (https://github.com/senzhk/ADBKeyBoard), enable it (ime enable/set '
+              + 'com.android.adbkeyboard/.AdbIME), then retry — this tool then types via its base64 broadcast.',
+            )
+          }
+          await DeviceBuild.typeViaAdbKeyboard(serial, args.text)
+          return { serial, action, sent: `text "${args.text}" (ADBKeyboard)` }
         }
         case 'key': {
           const raw = String(args.key ?? '')
@@ -601,6 +774,352 @@ function deviceInputTool() {
   })
 }
 
+/** OCR the current screen and report whether `wantedLower` appears; undefined when OCR is unavailable. */
+async function ocrHasText(serial, wantedLower) {
+  if (!DeviceBuild.ocrPython()) return undefined
+  const png = await DeviceBuild.screenCapture(serial)
+  if (!png) return undefined
+  const ocr = await DeviceBuild.ocrImage(png).catch(() => [])
+  return ocr.some((item) => String(item.text).toLowerCase().includes(wantedLower))
+}
+
+function deviceWaitForTool() {
+  return defineTool({
+    name: 'device_wait_for',
+    description: 'Wait for on-screen text to appear or disappear. Polls the uiautomator tree every ~600 ms; when the tree ' +
+      'carries no labels (WebView/Compose/canvas) it falls back to local PaddleOCR. A timeout is a normal matched:false ' +
+      'result, never an error — one call replaces an agent-side poll loop.',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      text: { type: 'string', description: 'Text to wait for (case-insensitive substring).' },
+      mode: { type: 'string', enum: ['appear', 'disappear'], description: 'appear (default) waits for the text; disappear waits for it to go away.' },
+      timeout_ms: { type: 'integer', description: 'Max wait in ms (default 10000, max 60000).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          text: { type: 'string', required: true },
+          mode: { type: 'string', required: true },
+          matched: { type: 'boolean', required: true },
+          waited_ms: { type: 'integer', required: true },
+          source: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', text: '', mode: 'appear', matched: false, waited_ms: 0, source: 'ui_tree' }
+        return [{ type: 'text', text: `${v.matched ? 'MATCHED' : 'TIMEOUT'}: "${v.text}" ${v.mode} (${v.source}) after ${v.waited_ms}ms on ${v.serial}` }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const text = String(args.text ?? '').trim()
+      if (text === '') throw new Error('device_wait_for requires a non-empty text.')
+      const mode = args.mode === 'disappear' ? 'disappear' : 'appear'
+      const timeout = Math.min(Math.max(args.timeout_ms ?? 10_000, 500), 60_000)
+      const wanted = text.toLowerCase()
+      const start = Date.now()
+      const deadline = start + timeout
+      let source = 'ui_tree'
+      for (;;) {
+        let labels
+        try {
+          labels = UiTree.collectLabels((await UiTree.readUiTree(serial)).roots)
+        } catch {
+          labels = undefined
+        }
+        let present
+        if (labels !== undefined && labels.length > 0) {
+          source = 'ui_tree'
+          present = labels.some((label) => label.toLowerCase().includes(wanted))
+        } else {
+          const ocr = await ocrHasText(serial, wanted)
+          if (ocr === undefined) { source = 'ui_tree'; present = false }
+          else { source = 'ocr'; present = ocr }
+        }
+        const matched = mode === 'appear' ? present : !present
+        const waited = Math.min(timeout, Date.now() - start)
+        if (matched) return { serial, text, mode, matched: true, waited_ms: waited, source }
+        if (Date.now() >= deadline) return { serial, text, mode, matched: false, waited_ms: timeout, source }
+        await new Promise((resolve) => setTimeout(resolve, source === 'ocr' ? 2000 : 600))
+      }
+    },
+  })
+}
+
+function deviceBootTool() {
+  return defineTool({
+    name: 'device_boot',
+    description: 'Boot an Android emulator AVD by name (from device_status.avds) and wait until it finishes booting. ' +
+      'If an emulator for that AVD is already running it is adopted. This is the device-centric boot — device_run is the ' +
+      'project-centric build+install+launch.',
+    parameters: {
+      avd: { type: 'string', description: 'AVD name to boot.' },
+      timeout_ms: { type: 'integer', description: 'Max wait for boot in ms (default 180000, max 600000).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          avd: { type: 'string', required: true },
+          booted: { type: 'boolean', required: true },
+          alreadyRunning: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', avd: '', booted: false, alreadyRunning: false }
+        return [{ type: 'text', text: `${v.alreadyRunning ? 'Adopted running' : 'Booted'} emulator ${v.serial} (AVD ${v.avd}), boot completed: ${v.booted}` }]
+      },
+    },
+    async execute(args) {
+      const avd = String(args.avd ?? '').trim()
+      if (avd === '') throw new Error('device_boot requires an avd name (see device_status.avds).')
+      const timeout = Math.min(Math.max(args.timeout_ms ?? 180_000, 5_000), 600_000)
+      const rows = await DeviceBuild.devices()
+      for (const row of rows.filter((item) => item.state === 'device' && item.serial.startsWith('emulator-'))) {
+        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 }
+        }
+      }
+      if (!DeviceBuild.emulatorBinary()) throw new Error('No SDK emulator binary found; cannot boot an AVD.')
+      const before = new Set(rows.map((item) => item.serial))
+      if (!DeviceBuild.bootEmulator(avd)) throw new Error(`Could not launch the emulator for AVD "${avd}".`)
+      const deadline = Date.now() + timeout
+      let serial
+      while (Date.now() < deadline) {
+        const now = await DeviceBuild.devices()
+        const fresh = now.find((item) => item.serial.startsWith('emulator-') && !before.has(item.serial))
+        if (fresh) { serial = fresh.serial; break }
+        await new Promise((resolve) => setTimeout(resolve, 1000))
+      }
+      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 }
+    },
+  })
+}
+
+function deviceShutdownTool() {
+  return defineTool({
+    name: 'device_shutdown',
+    description: 'Shut down an emulator (`adb emu kill`). Refuses physical devices — adb has no power-off verb for phones.',
+    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 },
+          shutdown: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `Shut down emulator ${value?.serial}` }],
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const isEmulator = serial.startsWith('emulator-') || (await DeviceBuild.avdName(serial).catch(() => undefined)) !== undefined
+      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
+      return { serial, shutdown: true }
+    },
+  })
+}
+
+const DEVICE_ACTIONS = {
+  notifications: ['cmd', 'statusbar', 'expand-notifications'],
+  quick_settings: ['cmd', 'statusbar', 'expand-settings'],
+  collapse: ['cmd', 'statusbar', 'collapse'],
+  lock: ['input', 'keyevent', '223'],
+  wake: ['input', 'keyevent', '224'],
+  assistant: ['am', 'start', '-a', 'android.intent.action.ASSIST'],
+}
+
+function deviceActionTool() {
+  return defineTool({
+    name: 'device_action',
+    description: 'Device-level actions beyond touches: open the notification shade or quick settings, collapse the shade, ' +
+      'lock or wake the screen, launch the assistant, or rotate the display (cycles 0→90→180→270 and pins auto-rotate off).',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      action: { type: 'string', enum: [...Object.keys(DEVICE_ACTIONS), 'rotate'], description: 'Which device action to perform.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          action: { type: 'string', required: true },
+          rotation: { type: 'integer' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value?.rotation !== undefined ? `${value.action} on ${value.serial} → rotation ${value.rotation * 90}°` : `${value?.action} on ${value?.serial}` }],
+    },
+    async execute(args) {
+      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 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
+        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
+      return { serial, action }
+    },
+  })
+}
+
+function deviceAppsTool() {
+  return defineTool({
+    name: 'device_apps',
+    description: 'List installed Android packages (third-party by default; include_system=true adds platform apps). ' +
+      'Use it to find the real package name before device_launch_app — never guess one.',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      include_system: { type: 'boolean', description: 'Include system/platform packages (default false).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          count: { type: 'integer', required: true },
+          packages: { type: 'array', required: true, items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', count: 0, packages: [] }
+        const shown = v.packages.slice(0, 60).join('\n  ')
+        return [{ type: 'text', text: `${v.serial}: ${v.count} packages\n  ${shown}${v.count > 60 ? `\n  … and ${v.count - 60} more` : ''}` }]
+      },
+    },
+    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 packages = output
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('package:'))
+        .map((line) => line.slice('package:'.length).trim())
+      return { serial, count: packages.length, packages: packages.slice(0, 200) }
+    },
+  })
+}
+
+function deviceLaunchAppTool() {
+  return defineTool({
+    name: 'device_launch_app',
+    description: 'Launch an installed app by package name (or a unique substring of it). relaunch=true force-stops it first ' +
+      'for a cold start. Resolves the exact package via `pm list packages` so a wrong guess fails loudly instead of ' +
+      'opening the wrong app.',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      package: { type: 'string', description: 'Package name or a unique substring of it.' },
+      relaunch: { type: 'boolean', description: 'Force-stop the app first (cold start).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          package: { type: 'string', required: true },
+          launched: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `Launched ${value?.package} on ${value?.serial}` }],
+    },
+    async execute(args) {
+      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 all = listOut
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('package:'))
+        .map((line) => line.slice('package:'.length).trim())
+      if (!all.includes(pkg)) {
+        const matches = all.filter((item) => item.toLowerCase().includes(pkg.toLowerCase()))
+        if (matches.length === 0) throw new Error(`No installed package matches "${pkg}". Run device_apps to list them.`)
+        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}).`)
+      return { serial, package: pkg, launched: true }
+    },
+  })
+}
+
+function deviceStreamTool(host, access) {
+  return defineTool({
+    name: 'device_stream',
+    description: 'Drive the live device screen stream the Devices panel shows. action=start begins the frame loop for an ' +
+      'online device and returns a signed streamUrl; status reports whether it is running; stop tears it down. This is a ' +
+      'human-panel feature — agents that just need to see the screen should use device_screen or device_ui_tree instead.',
+    parameters: {
+      action: { type: 'string', enum: ['status', 'start', 'stop'], description: 'What to do (default status).' },
+      serial: { type: 'string', description: 'Device serial (start needs an online device; omit to use the first attached one).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          action: { type: 'string', required: true },
+          running: { type: 'boolean', required: true },
+          serial: { type: 'string' },
+          streamUrl: { type: 'string' },
+          width: { type: 'integer' },
+          height: { type: 'integer' },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { action: 'status', running: false }
+        const text = v.action === 'start' && v.streamUrl
+          ? `Streaming ${v.serial} (${v.width}x${v.height}) — ${v.streamUrl}`
+          : `Stream ${v.action}: running=${v.running}${v.serial ? ` (${v.serial})` : ''}`
+        return [{ type: 'text', text }]
+      },
+    },
+    async execute(args) {
+      const action = args.action ?? 'status'
+      if (action === 'stop') {
+        await host.stop()
+        return { action, running: false }
+      }
+      if (action === 'status') {
+        const s = host.status()
+        return { action, running: s.running, ...(s.serial !== undefined ? { serial: s.serial } : {}), ...(s.width !== undefined ? { width: s.width, height: s.height } : {}) }
+      }
+      const serial = await requireAndroidDevice(args.serial)
+      const online = await host.listDevices()
+      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)}` }
+    },
+  })
+}
+
 function deviceScreenTool(engine) {
   return defineTool({
     name: 'device_screen',
@@ -715,7 +1234,9 @@ function deviceScreenTool(engine) {
 
 async function captureScreenSize(serial) {
   const output = await DeviceBuild.capture(DeviceBuild.adb(), ['-s', serial, 'shell', 'wm', 'size'])
-  const match = /Physical size:\s*(\d+)x(\d+)/.exec(output)
+  // 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)
   return match ? { width: Number(match[1]), height: Number(match[2]) } : undefined
 }
 
@@ -1042,8 +1563,17 @@ function guidance() {
     '  text, and pixel bounds. Narrow with filter/max_depth; on a textless surface (WebView, Compose, canvas) use device_screen.',
     '- device_tap_element: tap a control by resource_id or text/content-desc, with one-call verification via',
     '  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_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_screen → device_input → device_screen.',
+    '  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',
+    '  (CJK, emoji) goes through the ADBKeyboard IME when installed, and is refused with the install hint otherwise.',
+    '- 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_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.',
     '- device_status: one normalized snapshot of attached devices, AVDs, running/parked projects, Metro and preview servers.',
     '',
@@ -1072,8 +1602,11 @@ export function apply(ctx, config) {
   })
 
   const engine = new DevicePreviewEngine()
+  const streamHost = new AndroidStreamHost()
+  const streamAccess = new StreamAccess.StreamAccessController()
   const handle = {
     engine,
+    stream: streamHost,
     status: () => ({
       directories: [...new Set([...engine.builds.keys()].map((key) => key.split('\0')[0]))],
       servers: [...engine.servers.keys()],
@@ -1084,7 +1617,7 @@ export function apply(ctx, config) {
   if (typeof ctx.provide === 'function') ctx.provide('mobilecode', handle)
   else ctx.mobilecode = handle
 
-  const routes = makeRoutes(engine, config)
+  const routes = makeRoutes(engine, config, { host: streamHost, access: streamAccess })
   let disposeRoutes
   let disposeTools
   let disposeSection
@@ -1095,6 +1628,7 @@ export function apply(ctx, config) {
     if (disposeRoutes !== undefined) { disposeRoutes(); disposeRoutes = undefined }
     if (disposeTools !== undefined) { disposeTools(); disposeTools = undefined }
     if (!value.enabled) return
+    streamHost.startKeepAlive()
     if (value.announceToAgent) {
       disposeSection = ctx.systemPrompt.section({
         name: 'plugin:dsh-mobilecode',
@@ -1113,6 +1647,13 @@ export function apply(ctx, config) {
         deviceScreenTool(engine),
         deviceUiTreeTool(),
         deviceTapElementTool(),
+        deviceWaitForTool(),
+        deviceBootTool(),
+        deviceShutdownTool(),
+        deviceActionTool(),
+        deviceAppsTool(),
+        deviceLaunchAppTool(),
+        deviceStreamTool(streamHost, streamAccess),
         deviceLogTool(engine),
         deviceStatusTool(engine),
         deviceInputTool(),
@@ -1123,6 +1664,7 @@ export function apply(ctx, config) {
 
   ctx.effect(() => () => {
     disposeSkill()
+    void streamHost.dispose()
     void engine.dispose()
   }, 'dsh-mobilecode: engine')