dsh-mobilecode 0.2.1 → 0.4.0

package/lib/frame-source.js

@@ -0,0 +1,274 @@
+/**
+ * dsh-mobilecode — in-process MJPEG-style frame pipeline for one Android device.
+ *
+ * Ported from ZSeven-W/dsh-android (frame-source.ts, MIT). No external stream
+ * helper and no inner loopback port: ONE persistent `adb exec-out` child runs a
+ * `screencap -p` loop on the device, this module splits the concatenated PNG
+ * output into frames, and the web routes serve the latest frame straight from
+ * memory as a `multipart/x-mixed-replace` body (PNG parts — Chromium and
+ * Firefox render those exactly like JPEG parts).
+ *
+ * The persistent child is the heart of the design: spawning adb per frame costs
+ * ~200 ms per screenshot (~5 fps ceiling), while one `while :; do screencap -p;
+ * done` child streams ~8 fps on an emulator with zero per-frame process cost.
+ * The child is intentionally dumb — it exits, this module reports it, and the
+ * host controller (android-stream.js) owns restart / keep-alive policy.
+ */
+
+import * as DeviceBuild from './device-build.js'
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+const IEND_TYPE = 0x49454e44 // 'IEND'
+/** A screencap frame larger than this means we lost sync; rescan. */
+const MAX_FRAME_BYTES = 64 * 1024 * 1024
+/** Bytes kept while hunting for a signature in garbage (stderr noise, …). */
+const MAX_UNSYNCED_BYTES = 1024 * 1024
+const STDERR_RING_LINES = 20
+const STDERR_LINE_MAX_CHARS = 240
+export const STREAM_BOUNDARY = 'dsh-mobilecode-frame'
+
+/** Pixel size of a PNG from its IHDR chunk, without decoding the image. */
+export function pngDimensions(buffer) {
+  if (buffer.length < 24) return undefined
+  if (!buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return undefined
+  if (buffer.readUInt32BE(12) !== 0x49484452) return undefined // 'IHDR'
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) }
+}
+
+/**
+ * Incremental splitter over a byte stream of back-to-back PNG images.
+ *
+ * PNG framing is self-describing (8-byte signature, then length-prefixed chunks
+ * until IEND), so frames are cut by walking chunk headers — no scanning of image
+ * data for markers, no false positives. When the stream derails the splitter
+ * drops bytes until the next signature instead of stalling.
+ */
+export class PngFrameSplitter {
+  #buffer = Buffer.alloc(0)
+
+  /** Feed bytes; returns every complete PNG that ended inside them. */
+  push(chunk) {
+    this.#buffer = this.#buffer.length === 0 ? chunk : Buffer.concat([this.#buffer, chunk])
+    const frames = []
+    for (;;) {
+      const start = this.#buffer.indexOf(PNG_SIGNATURE)
+      if (start < 0) {
+        if (this.#buffer.length > MAX_UNSYNCED_BYTES) {
+          this.#buffer = this.#buffer.subarray(this.#buffer.length - PNG_SIGNATURE.length)
+        }
+        return frames
+      }
+      if (start > 0) this.#buffer = this.#buffer.subarray(start)
+      const end = this.#frameEnd()
+      if (end === undefined) {
+        if (this.#buffer.length > MAX_FRAME_BYTES) {
+          this.#buffer = this.#buffer.subarray(1)
+          continue
+        }
+        return frames
+      }
+      frames.push(this.#buffer.subarray(0, end))
+      this.#buffer = this.#buffer.subarray(end)
+    }
+  }
+
+  /** Byte length of the complete PNG at the buffer start, if fully buffered. */
+  #frameEnd() {
+    let offset = PNG_SIGNATURE.length
+    for (;;) {
+      if (offset + 8 > this.#buffer.length) return undefined
+      const dataLength = this.#buffer.readUInt32BE(offset)
+      const type = this.#buffer.readUInt32BE(offset + 4)
+      if (dataLength > MAX_FRAME_BYTES) return undefined // corrupt header; caller rescans
+      const next = offset + 8 + dataLength + 4
+      if (next > this.#buffer.length) return undefined
+      if (type === IEND_TYPE) return next
+      offset = next
+    }
+  }
+}
+
+/**
+ * Owns the one persistent screencap child for one device serial and the
+ * latest-frame buffer every consumer reads from.
+ */
+export class AdbFrameLoop {
+  #child
+  #splitter = new PngFrameSplitter()
+  #latest
+  #sequence = 0
+  #stderrRing = []
+  #stderrPartial = ''
+  #frameWaiters = []
+  #stopped = false
+
+  constructor(serial, events = {}) {
+    this.serial = serial
+    this.events = events
+  }
+
+  get running() {
+    const child = this.#child
+    return child !== undefined && child.exitCode === null && child.signalCode === null
+  }
+
+  get latestFrame() {
+    return this.#latest
+  }
+
+  get stderrLines() {
+    return [...this.#stderrRing]
+  }
+
+  /** Spawn the screencap loop child (idempotent while running). */
+  start() {
+    if (this.running || this.#stopped) return
+    // `exec-out` skips the pty (binary-safe); the single-string command runs
+    // through the *device* shell, so one child produces frames forever.
+    const child = DeviceBuild.launch(
+      DeviceBuild.adb(),
+      ['-s', this.serial, 'exec-out', 'while :; do screencap -p; done'],
+      { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true },
+    )
+    this.#child = child
+    child.stdout?.on('data', (chunk) => {
+      for (const png of this.#splitter.push(chunk)) this.#acceptFrame(png)
+    })
+    child.stderr?.on('data', (chunk) => this.#recordStderr(chunk))
+    child.once('error', (error) => {
+      this.#recordStderr(Buffer.from(`spawn error: ${error.message}\n`))
+    })
+    child.once('close', (code, signal) => {
+      if (this.#child !== child) return
+      this.#child = undefined
+      const detail = signal !== null ? `killed by ${signal}` : `exit ${String(code)}`
+      if (!this.#stopped) this.events.onExit?.(detail)
+    })
+  }
+
+  /** Kill the child; the loop object can be started again later. */
+  stop() {
+    this.#stopped = true
+    const child = this.#child
+    this.#child = undefined
+    if (child !== undefined && child.exitCode === null && child.signalCode === null) {
+      child.kill('SIGTERM')
+      const hardKill = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL')
+      }, 2000)
+      hardKill.unref?.()
+    }
+    const waiters = this.#frameWaiters
+    this.#frameWaiters = []
+    if (this.#latest !== undefined) for (const waiter of waiters) waiter(this.#latest)
+  }
+
+  /** Allow a stopped loop to be started again (host restart path). */
+  reset() {
+    this.#stopped = false
+    this.#splitter = new PngFrameSplitter()
+  }
+
+  /** The next frame (or the latest one already buffered), bounded in time. */
+  waitForFrame(timeoutMs) {
+    const latest = this.#latest
+    if (latest !== undefined) return Promise.resolve(latest)
+    return new Promise((resolve) => {
+      let settled = false
+      const waiter = (frame) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        resolve(frame)
+      }
+      const timer = setTimeout(() => {
+        if (settled) return
+        settled = true
+        const index = this.#frameWaiters.indexOf(waiter)
+        if (index >= 0) this.#frameWaiters.splice(index, 1)
+        resolve(undefined)
+      }, timeoutMs)
+      timer.unref?.()
+      this.#frameWaiters.push(waiter)
+    })
+  }
+
+  #acceptFrame(png) {
+    const size = pngDimensions(png)
+    if (size === undefined) return
+    this.#sequence += 1
+    const frame = { png, width: size.width, height: size.height, sequence: this.#sequence, at: Date.now() }
+    this.#latest = frame
+    const waiters = this.#frameWaiters
+    this.#frameWaiters = []
+    for (const waiter of waiters) waiter(frame)
+    this.events.onFrame?.(frame)
+  }
+
+  #recordStderr(chunk) {
+    const text = this.#stderrPartial + chunk.toString('utf8')
+    const lines = text.split('\n')
+    this.#stderrPartial = lines.pop() ?? ''
+    for (const line of lines) {
+      const trimmed = line.trimEnd()
+      if (trimmed === '') continue
+      this.#stderrRing.push(trimmed.length > STDERR_LINE_MAX_CHARS ? `${trimmed.slice(0, STDERR_LINE_MAX_CHARS)}…` : trimmed)
+      if (this.#stderrRing.length > STDERR_RING_LINES) this.#stderrRing.shift()
+    }
+  }
+}
+
+/**
+ * Write one live multipart/x-mixed-replace response from a frame feed.
+ * Backpressure is latest-wins: when the client socket is saturated the writer
+ * skips frames instead of queueing them, so a slow tab never builds an
+ * unbounded buffer or watches a growing delay.
+ */
+export class MultipartFrameWriter {
+  #closed = false
+  #congested = false
+
+  constructor(res) {
+    this.res = res
+    res.writeHead(200, {
+      'content-type': `multipart/x-mixed-replace; boundary=${STREAM_BOUNDARY}`,
+      'cache-control': 'no-cache, no-store',
+      'x-content-type-options': 'nosniff',
+      'cross-origin-resource-policy': 'same-origin',
+      'referrer-policy': 'no-referrer',
+    })
+    res.on('drain', () => {
+      this.#congested = false
+    })
+  }
+
+  get closed() {
+    return this.#closed
+  }
+
+  /** Write one frame part; silently skipped while the socket is congested. */
+  writeFrame(frame) {
+    if (this.#closed || this.#congested) return
+    const header = `--${STREAM_BOUNDARY}\r\n`
+      + 'Content-Type: image/png\r\n'
+      + `Content-Length: ${frame.png.length}\r\n\r\n`
+    try {
+      this.res.write(header)
+      const flushed = this.res.write(frame.png)
+      this.res.write('\r\n')
+      if (!flushed) this.#congested = true
+    } catch {
+      this.close()
+    }
+  }
+
+  close() {
+    if (this.#closed) return
+    this.#closed = true
+    try {
+      this.res.end()
+    } catch {
+      // The socket may already be gone.
+    }
+  }
+}

package/lib/index.js

@@ -18,6 +18,10 @@
 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 * as Vision from './vision.js'
 import { DevicePreviewEngine } from './device-preview.js'
 import * as Setup from './setup.js'
 import { registerMobileSkill } from './skill.js'
@@ -70,11 +74,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 +304,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
 }
@@ -908,7 +1070,58 @@ function deviceLaunchAppTool() {
   })
 }
 
-function deviceScreenTool(engine) {
+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, vision) {
   return defineTool({
     name: 'device_screen',
     description: 'See what is on an attached Android device right now: captures the screen as a PNG file, dumps the UI ' +
@@ -965,6 +1178,7 @@ function deviceScreenTool(engine) {
             },
           },
           ocrError: { type: 'string' },
+          image: Vision.IMAGE_REF_SCHEMA,
         },
       },
       render: (_args, value) => {
@@ -988,10 +1202,13 @@ function deviceScreenTool(engine) {
           if (v.ocr.length > 40) lines.push(`  … and ${v.ocr.length - 40} more`)
         }
         if (!v.ui?.length && !v.ocr?.length) lines.push('No text found on screen.')
-        return [{ type: 'text', text: lines.join('\n') }]
+        const blocks = [{ type: 'text', text: lines.join('\n') }]
+        // When the routed model accepts images, the screenshot rides along as a
+        // real image block so the model SEES the screen (see lib/vision.js).
+        return Vision.appendImageBlock(blocks, v)
       },
     },
-    async execute(args) {
+    async execute(args, exec) {
       const serial = await requireAndroidDevice(args.serial)
       const png = await DeviceBuild.screenCapture(serial, args.directory)
       const [ui, foreground, size] = await Promise.all([
@@ -1015,6 +1232,8 @@ function deviceScreenTool(engine) {
           else out.ocrError = 'PaddleOCR returned no text (or failed silently)'
         }
       }
+      const image = await Vision.maybeAttachScreenshot(vision, png, exec)
+      if (image !== undefined) out.image = image
       return out
     },
   })
@@ -1360,6 +1579,8 @@ function guidance() {
     '- device_action: notifications / quick_settings / collapse / lock / wake / assistant / rotate.',
     '- device_boot / device_shutdown: boot an AVD by name and wait for boot / shut an emulator down (refuses physical devices).',
     '- device_apps / device_launch_app: list installed packages (never guess a package name) / launch one by package or unique substring.',
+    '- device_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.',
     '',
@@ -1388,8 +1609,12 @@ export function apply(ctx, config) {
   })
 
   const engine = new DevicePreviewEngine()
+  const streamHost = new AndroidStreamHost()
+  const streamAccess = new StreamAccess.StreamAccessController()
+  const vision = Vision.resolveVisionServices(ctx)
   const handle = {
     engine,
+    stream: streamHost,
     status: () => ({
       directories: [...new Set([...engine.builds.keys()].map((key) => key.split('\0')[0]))],
       servers: [...engine.servers.keys()],
@@ -1400,7 +1625,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
@@ -1411,6 +1636,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',
@@ -1426,7 +1652,7 @@ export function apply(ctx, config) {
       const disposers = [
         deviceRunTool(engine, config),
         deviceDetectTool(engine, config),
-        deviceScreenTool(engine),
+        deviceScreenTool(engine, vision),
         deviceUiTreeTool(),
         deviceTapElementTool(),
         deviceWaitForTool(),
@@ -1435,6 +1661,7 @@ export function apply(ctx, config) {
         deviceActionTool(),
         deviceAppsTool(),
         deviceLaunchAppTool(),
+        deviceStreamTool(streamHost, streamAccess),
         deviceLogTool(engine),
         deviceStatusTool(engine),
         deviceInputTool(),
@@ -1445,6 +1672,7 @@ export function apply(ctx, config) {
 
   ctx.effect(() => () => {
     disposeSkill()
+    void streamHost.dispose()
     void engine.dispose()
   }, 'dsh-mobilecode: engine')