dsh-mobilecode 0.7.0 → 0.8.0

package/lib/index.js

@@ -24,6 +24,7 @@ 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 { MeshHub } from './mesh-hub.js'
 import * as Setup from './setup.js'
 import { registerMobileSkill } from './skill.js'
 import { existsSync, readFileSync } from 'node:fs'
@@ -92,6 +93,38 @@ function makeRoutes(engine, config, stream) {
     if ((req.method ?? 'GET') !== 'POST') { writeJson(res, 405, { error: 'method not allowed' }); return false }
     return true
   }
+  // Mesh fence: game clients are plain HTTP stacks (OkHttp/Unity/curl) that
+  // never send browser headers — they must only prove a loopback peer plus a
+  // Host the emulator NAT actually presents (10.0.2.2) or loopback. Anything
+  // that DOES look like a browser request (Origin / Sec-Fetch-*) additionally
+  // passes the trusted-browser stream fence, so a random web page can never
+  // join a game session or read its messages.
+  const meshGuard = (req, res) => {
+    if (!StreamAccess.isLoopbackRemoteAddress(req.socket?.remoteAddress)) {
+      writeJson(res, 403, { code: 'forbidden', error: 'the mesh is loopback-only (emulators reach it via 10.0.2.2)' })
+      return false
+    }
+    if (req.headers.origin !== undefined || req.headers['sec-fetch-site'] !== undefined || req.headers['sec-fetch-mode'] !== undefined) {
+      return fence(req, res, false)
+    }
+    let hostname = ''
+    try { hostname = new URL('http://' + String(req.headers.host ?? '')).hostname } catch { hostname = '' }
+    const trusted = hostname === 'localhost' || hostname === '::1' || hostname === '[::1]'
+      || hostname.startsWith('127.') || hostname === '10.0.2.2' || hostname === '10.0.3.2'
+    if (!trusted) { writeJson(res, 403, { code: 'forbidden', error: `unexpected Host "${hostname}" for a mesh client` }); return false }
+    return true
+  }
+  const meshAuth = (req, url, body) => {
+    const id = body?.id ?? url.searchParams.get('id') ?? req.headers['x-mesh-peer']
+    const token = body?.token ?? url.searchParams.get('token') ?? req.headers['x-mesh-token']
+    if (typeof id !== 'string' || !stream.mesh.verify(id, typeof token === 'string' ? token : '')) return undefined
+    return stream.mesh.peers.get(id)
+  }
+  const meshUnauthorized = (res) => writeJson(res, 401, { code: 'token_invalid', error: 'POST /mesh/join first, then pass your id + token' })
+  const meshFail = (res, error) => {
+    const status = ({ unknown_peer: 404, unknown_session: 409, not_member: 403, too_large: 413 })[error?.code] ?? 400
+    writeJson(res, status, { code: error?.code ?? 'bad_request', error: error instanceof Error ? error.message : String(error) })
+  }
   const platformOf = (value) => (value === 'ios' || value === 'android' ? value : undefined)
   const routes = [
     // GET /api/dsh-mobilecode?directory=... → current info (platforms, servers, builds, bundler).
@@ -531,6 +564,10 @@ function makeRoutes(engine, config, stream) {
         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 }
+        if (serial !== stream.host.streamedSerial) {
+          const online = await stream.host.listDevices()
+          if (!online.some((device) => device.serial === serial)) { writeJson(res, 409, { code: 'device_not_found', error: `device ${serial} is not online` }); return }
+        }
         try {
           await DeviceBuild.adbRun(serial, ['shell', ...argv])
           writeJson(res, 200, { ok: true, action, device: serial })
@@ -586,6 +623,118 @@ function makeRoutes(engine, config, stream) {
         }
       },
     },
+    // ── mesh (v0.8.0) ─ LocalSend-style rendezvous for co-op testing. Emulators
+    // cannot multicast through their isolated slirp NATs, but every one reaches
+    // the host at 10.0.2.2, so the hub lives on these routes. A game joins once
+    // (its serial pins a stable random callsign), links with a peer, then sends
+    // and polls JSON through the hub — which doubles as the agent's observation
+    // window (mesh_log) and network-condition injector (mesh_tune).
+    {
+      kind: 'exact',
+      path: API_BASE + '/mesh/join',
+      handler: async (req, res) => {
+        if (!meshGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        try {
+          const { peer, token } = stream.mesh.join({ serial: body.serial, name: body.name, role: body.role })
+          writeJson(res, 200, { ok: true, peer, token })
+        } catch (error) {
+          meshFail(res, error)
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/mesh/peers',
+      handler: async (req, res) => {
+        if (!meshGuard(req, res)) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const me = meshAuth(req, url, undefined)
+        if (!me) { meshUnauthorized(res); return }
+        writeJson(res, 200, { ok: true, me, ...stream.mesh.status() })
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/mesh/link',
+      handler: async (req, res) => {
+        if (!meshGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const me = meshAuth(req, url, body)
+        if (!me) { meshUnauthorized(res); return }
+        try {
+          const queries = Array.isArray(body.with) ? body.with : []
+          const session = stream.mesh.link([me.name, ...queries])
+          writeJson(res, 200, {
+            ok: true,
+            session: {
+              id: session.id,
+              members: session.members.map((id) => stream.mesh.peers.get(id)?.name ?? id),
+              policy: session.policy,
+            },
+          })
+        } catch (error) {
+          meshFail(res, error)
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/mesh/send',
+      handler: async (req, res) => {
+        if (!meshGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const me = meshAuth(req, url, body)
+        if (!me) { meshUnauthorized(res); return }
+        try {
+          const result = stream.mesh.send({ session: body.session, from: me.id, body: body.body })
+          writeJson(res, 200, { ok: true, ...result })
+        } catch (error) {
+          meshFail(res, error)
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/mesh/poll',
+      handler: async (req, res) => {
+        if (!meshGuard(req, res)) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const me = meshAuth(req, url, undefined)
+        if (!me) { meshUnauthorized(res); return }
+        const after = Number(url.searchParams.get('after')) || 0
+        const wait = Math.min(Number(url.searchParams.get('wait')) || 0, 30_000)
+        let result = stream.mesh.poll(me.id, after)
+        if (result.messages.length === 0 && wait > 0) {
+          await stream.mesh.waitFor(me.id, wait)
+          result = stream.mesh.poll(me.id, after)
+        }
+        writeJson(res, 200, { ok: true, ...result })
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/mesh/leave',
+      handler: async (req, res) => {
+        if (!meshGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const me = meshAuth(req, url, body)
+        if (!me) { meshUnauthorized(res); return }
+        stream.mesh.leave(me.id)
+        writeJson(res, 200, { ok: true })
+      },
+    },
   ]
   return routes
 }
@@ -1647,7 +1796,8 @@ function deviceBacktraceTool() {
     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.',
+      'back to the logcat crash buffer and says so (engine field: "anr-trace" | "logcat-crash"). SIGQUIT refusal (system-uid or ' +
+      'non-debuggable process) degrades to the crash buffer with an explanatory note instead of failing. 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).' },
@@ -1695,22 +1845,32 @@ function deviceBacktraceTool() {
       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),
-          })
+      // SIGQUIT: the ART runtime writes the thread dump to /data/anr/. The adb
+      // shell user cannot signal system-uid / non-debuggable processes on
+      // enforcing builds (EPERM) — degrade honestly instead of throwing.
+      let sigquit = true
+      try {
+        await DeviceBuild.adbRun(serial, ['shell', 'kill', '-3', String(pid)])
+      } catch {
+        sigquit = false
+      }
+      let newest
+      if (sigquit) {
+        await new Promise((resolve) => setTimeout(resolve, 1200))
+        const listing = await DeviceBuild.adbRun(serial, ['shell', 'ls', '-t', '/data/anr']).catch(() => undefined)
+        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.
@@ -1724,7 +1884,9 @@ function deviceBacktraceTool() {
           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.`,
+          note: sigquit
+            ? `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.`
+            : `SIGQUIT refused for pid ${pid} — the adb shell user cannot signal this process (system uid or non-debuggable app on an enforcing build), so no fresh thread dump exists; the logcat crash buffer has no matching FATAL lines either. Target a debuggable app for a live dump, or use an adb-rooted device.`,
           lines: [],
         })
       }
@@ -1810,6 +1972,572 @@ function deviceMeminfoTool() {
   })
 }
 
+// ── display, fleet, co-op observation + mesh tools (v0.8.0) ─────────────────
+
+/** Drop null/undefined fields so strict output schemas stay satisfiable. */
+function clean(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== null && value !== undefined))
+}
+
+function deviceDisplayTool() {
+  return defineTool({
+    name: 'device_display',
+    description: 'Read or change a device display metrics: DPI (wm density) and pixel resolution (wm size). ' +
+      'action=get reports physical + current override; action=set applies overrides (density and/or width+height); ' +
+      'action=reset restores physical values for both. Layouts reflow instantly — re-observe with device_screen ' +
+      'after a change, and remember input coordinates follow the new resolution.',
+    parameters: {
+      serial: { type: 'string', description: 'Android device serial. Omit to use the first attached device.' },
+      action: { type: 'string', enum: ['get', 'set', 'reset'], description: 'Defaults to get.' },
+      density: { type: 'integer', description: 'DPI to set (action=set), 80..800 — e.g. 420 for a phone, 260 for a tablet-ish look.' },
+      width: { type: 'integer', description: 'Resolution width px to set (action=set, requires height).' },
+      height: { type: 'integer', description: 'Resolution height px to set (action=set, requires width).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          serial: { type: 'string', required: true },
+          action: { type: 'string', required: true },
+          density: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { physical: { type: 'integer' }, override: { type: 'integer' } },
+          },
+          size: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              physical: { type: 'object', additionalProperties: false, properties: { width: { type: 'integer', required: true }, height: { type: 'integer', required: true } } },
+              override: { type: 'object', additionalProperties: false, properties: { width: { type: 'integer', required: true }, height: { type: 'integer', required: true } } },
+            },
+          },
+          applied: { type: 'array', items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { serial: '', action: 'get' }
+        const d = v.density ?? {}
+        const s = v.size ?? {}
+        const dpi = `DPI ${d.override ?? d.physical ?? '?'}${d.override ? ` (physical ${d.physical}, overridden)` : ''}`
+        const px = s.physical ? `${s.override?.width ?? s.physical.width}x${s.override?.height ?? s.physical.height}${s.override ? ` (physical ${s.physical.width}x${s.physical.height})` : ''}` : 'size unknown'
+        const applied = v.applied?.length ? ` → applied: ${v.applied.join(', ')}` : ''
+        return [{ type: 'text', text: `${v.serial} [${v.action}]: ${dpi} · ${px}${applied}` }]
+      },
+    },
+    async execute(args) {
+      const serial = await requireAndroidDevice(args.serial)
+      const action = args.action ?? 'get'
+      const applied = []
+      if (action === 'set') {
+        const { density, width, height } = args
+        if (density == null && width == null && height == null) throw new Error('action=set needs density and/or width+height (or use get/reset).')
+        if ((width == null) !== (height == null)) throw new Error('setting resolution needs BOTH width and height.')
+        if (density != null && (density < 80 || density > 800)) throw new Error('density must be within 80..800.')
+        if (width != null && (width < 100 || width > 10_000 || height < 100 || height > 10_000)) throw new Error('resolution sides must each be 100..10000 px.')
+        if (width != null) {
+          await DeviceBuild.adbRun(serial, ['shell', 'wm', 'size', `${width}x${height}`])
+          applied.push(`size ${width}x${height}`)
+        }
+        if (density != null) {
+          await DeviceBuild.adbRun(serial, ['shell', 'wm', 'density', String(density)])
+          applied.push(`density ${density}`)
+        }
+      } else if (action === 'reset') {
+        await DeviceBuild.adbRun(serial, ['shell', 'wm', 'density', 'reset'])
+        await DeviceBuild.adbRun(serial, ['shell', 'wm', 'size', 'reset'])
+        applied.push('density reset', 'size reset')
+      }
+      const [densityText, sizeText] = await Promise.all([
+        DeviceBuild.adbRun(serial, ['shell', 'wm', 'density']),
+        DeviceBuild.adbRun(serial, ['shell', 'wm', 'size']),
+      ])
+      return {
+        serial,
+        action,
+        density: clean(DeviceBuild.parseWmDensity(densityText)),
+        size: clean(DeviceBuild.parseWmSize(sizeText)),
+        ...(applied.length ? { applied } : {}),
+      }
+    },
+  })
+}
+
+/** Prefer the newest API level when picking a default system image. */
+function newestImage(images) {
+  const apiOf = (id) => Number(/android-(\d+)/.exec(id)?.[1] ?? 0)
+  return [...images].sort((a, b) => apiOf(a) - apiOf(b)).at(-1)
+}
+
+function deviceAvdCreateTool() {
+  return defineTool({
+    name: 'device_avd_create',
+    description: 'Create a second virtual device (the co-op partner) via avdmanager. clone_from copies an existing ' +
+      'AVD\'s full hardware config (same image, DPI, RAM, SoC) so both players behave identically; otherwise pass an ' +
+      'explicit image id + device profile. This only creates the AVD — boot it with device_boot (a running emulator ' +
+      'holds 5554, so device #2 lands on emulator-5556 automatically), then wire the two together with the mesh.',
+    parameters: {
+      name: { type: 'string', description: 'New AVD name (letters/digits/._-, up to 64).' },
+      clone_from: { type: 'string', description: 'Existing AVD whose config.ini to clone (recommended for parity).' },
+      image: { type: 'string', description: 'System-image package id (e.g. system-images;android-35;google_apis;x86_64). Defaults to the clone source\'s image, else the newest installed.' },
+      device: { type: 'string', description: 'avdmanager hardware profile when not cloning (default pixel_7).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          name: { type: 'string', required: true },
+          imageId: { type: 'string', required: true },
+          configPath: { type: 'string', required: true },
+          clonedFrom: { type: 'string' },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { name: '', imageId: '', configPath: '' }
+        return [{ type: 'text', text: `Created AVD "${v.name}" (${v.imageId}${v.clonedFrom ? `, cloned hardware from ${v.clonedFrom}` : ''}) — boot it with device_boot.` }]
+      },
+    },
+    async execute(args) {
+      const name = String(args.name ?? '').trim()
+      if (!/^[A-Za-z0-9._-]{1,64}$/.test(name)) throw new Error('AVD name must match [A-Za-z0-9._-]{1,64}.')
+      if (!DeviceBuild.avdmanagerBinary()) throw new Error('avdmanager not found — install SDK cmdline-tools (sdkmanager --install "cmdline-tools;latest").')
+      const avds = await DeviceBuild.androidAvds()
+      if (avds.includes(name)) throw new Error(`AVD "${name}" already exists — boot it with device_boot or choose another name.`)
+      let cloneConfig
+      let imageId = typeof args.image === 'string' && args.image.includes(';') ? args.image.trim() : undefined
+      if (args.clone_from) {
+        if (!avds.includes(args.clone_from)) throw new Error(`clone_from "${args.clone_from}" is not a known AVD (see device_status.avds).`)
+        try { cloneConfig = readFileSync(DeviceBuild.avdConfigPath(args.clone_from), 'utf8') } catch { throw new Error(`could not read config.ini for "${args.clone_from}".`) }
+        if (!imageId) {
+          const sysdir = /^\s*image\.sysdir\.1\s*=\s*(.+)$/m.exec(cloneConfig)?.[1]?.trim()
+          if (sysdir) imageId = sysdir.replace(/\\/g, '/').replace(/\/+$/, '').split('/').join(';')
+        }
+      }
+      if (!imageId) {
+        const images = await DeviceBuild.installedSystemImages()
+        if (images.length === 0) throw new Error('no system images installed — install one first: sdkmanager --install "system-images;android-35;google_apis;x86_64".')
+        imageId = newestImage(images)
+      }
+      const created = await DeviceBuild.createAvd({ name, imageId, deviceProfile: imageId && !cloneConfig ? (args.device ?? 'pixel_7') : undefined, cloneConfigText: cloneConfig })
+      return { name, imageId, configPath: created.configPath, ...(args.clone_from ? { clonedFrom: args.clone_from } : {}) }
+    },
+  })
+}
+
+/**
+ * Pure adb-argv builder for one device_batch step (exported for offline tests).
+ * Throws with the offending step named when the parameters do not fit the action.
+ */
+export function buildInputArgv(step) {
+  const action = step?.action ?? 'tap'
+  const int = (value) => (typeof value === 'number' && Number.isFinite(value) ? Math.round(value) : undefined)
+  switch (action) {
+    case 'tap': {
+      const x = int(step.x)
+      const y = int(step.y)
+      if (x === undefined || y === undefined) throw new Error('step action=tap needs numeric x and y.')
+      return { argv: ['shell', 'input', 'tap', String(x), String(y)], sent: `tap ${x},${y}` }
+    }
+    case 'swipe': {
+      const x = int(step.x)
+      const y = int(step.y)
+      const x2 = int(step.x2)
+      const y2 = int(step.y2)
+      if ([x, y, x2, y2].some((value) => value === undefined)) throw new Error('step action=swipe needs numeric x, y, x2, y2.')
+      const duration = int(step.duration) ?? 200
+      return { argv: ['shell', 'input', 'swipe', String(x), String(y), String(x2), String(y2), String(duration)], sent: `swipe ${x},${y}→${x2},${y2}` }
+    }
+    case 'text': {
+      const text = step.text
+      if (typeof text !== 'string' || text === '') throw new Error('step action=text needs a non-empty text string.')
+      if (!DeviceBuild.isAsciiInput(text)) throw new Error(`batch action=text is ASCII-only (non-ASCII needs the ADBKeyboard path — use device_input): "${text}".`)
+      return { argv: ['shell', 'input', 'text', DeviceBuild.escapeInputText(text)], sent: `text "${text}"` }
+    }
+    case 'key': {
+      const raw = String(step.key ?? '')
+      const code = /^\d+$/.test(raw) ? Number(raw) : KEYCODES[raw.toLowerCase()]
+      if (!code) throw new Error(`unknown key "${raw}" in batch step.`)
+      return { argv: ['shell', 'input', 'keyevent', String(code)], sent: `key ${raw}` }
+    }
+    default:
+      throw new Error(`unknown step action "${action}" — use tap, swipe, text or key.`)
+  }
+}
+
+function deviceBatchTool() {
+  return defineTool({
+    name: 'device_batch',
+    description: 'Fire several input actions at once across devices — the co-op primitive for "both players press ' +
+      'attack on the same frame". All steps dispatch concurrently (separate adb connections, spawned in parallel, so ' +
+      'cross-device skew is a few milliseconds), each step carries the same fields device_input uses plus its own ' +
+      'serial (omit serial to target the first device). A failing step never blocks the others; the per-step results ' +
+      'say what landed. Follow with device_pair_capture to watch what both screens did.',
+    parameters: {
+      steps: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: true,
+          properties: {
+            serial: { type: 'string' },
+            action: { type: 'string', enum: ['tap', 'swipe', 'text', 'key'] },
+            x: { type: 'integer' }, y: { type: 'integer' }, x2: { type: 'integer' }, y2: { type: 'integer' },
+            duration: { type: 'integer' }, text: { type: 'string' }, key: { type: 'string' },
+          },
+        },
+        description: '1..16 input steps, e.g. [{serial:"emulator-5554",action:"tap",x:540,y:1200},{serial:"emulator-5556",action:"key",key:"space"}].',
+      },
+      settle_ms: { type: 'integer', description: 'After the last dispatch, wait this long (0..10000, default 0) so the game can react before you observe.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          results: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                index: { type: 'integer', required: true },
+                serial: { type: 'string', required: true },
+                ok: { type: 'boolean', required: true },
+                sent: { type: 'string' },
+                error: { type: 'string' },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { ok: false, results: [] }
+        const lines = v.results.map((r) => `  #${r.index} ${r.serial}: ${r.ok ? r.sent : `FAILED — ${r.error}`}`)
+        return [{ type: 'text', text: `device_batch ${v.ok ? 'all landed' : 'had failures'}:\n${lines.join('\n')}` }]
+      },
+    },
+    async execute(args) {
+      const steps = Array.isArray(args.steps) ? args.steps : []
+      if (steps.length === 0 || steps.length > 16) throw new Error('steps must hold 1..16 input actions.')
+      const planned = steps.map((step, index) => ({ index, step, ...buildInputArgv(step) }))
+      let fallback
+      for (const item of planned) {
+        if (typeof item.step.serial === 'string' && item.step.serial !== '') item.serial = item.step.serial
+        else { fallback ??= await requireAndroidDevice(undefined); item.serial = fallback }
+      }
+      const results = await Promise.all(planned.map(async (item) => {
+        try {
+          await DeviceBuild.adbRun(item.serial, item.argv)
+          return { index: item.index, serial: item.serial, ok: true, sent: item.sent }
+        } catch (error) {
+          return { index: item.index, serial: item.serial, ok: false, error: error instanceof Error ? error.message : String(error) }
+        }
+      }))
+      const settle = Math.min(Math.max(args.settle_ms ?? 0, 0), 10_000)
+      if (settle > 0) await new Promise((resolve) => setTimeout(resolve, settle))
+      return { ok: results.every((r) => r.ok), results }
+    },
+  })
+}
+
+/** One device's screen state for device_pair_capture (mirrors device_screen's parts). */
+async function captureForPair(serial, directory, wantOcr) {
+  const [png, ui, foreground, size] = await Promise.all([
+    DeviceBuild.screenCapture(serial, directory).catch(() => undefined),
+    DeviceBuild.uiDump(serial).catch(() => []),
+    DeviceBuild.foregroundActivity(serial).catch(() => undefined),
+    captureScreenSize(serial).catch(() => undefined),
+  ])
+  const out = { serial, ui, ...(foreground ? { foreground } : {}), ...(png ? { screenshot: png } : {}) }
+  if (png && size) { out.width = size.width; out.height = size.height }
+  if (wantOcr) {
+    if (!png) out.ocrError = 'screenshot failed'
+    else {
+      const ocr = await DeviceBuild.ocrImage(png).catch(() => [])
+      if (ocr.length > 0) out.ocr = ocr
+      else out.ocrError = 'PaddleOCR returned no text'
+    }
+  }
+  return out
+}
+
+function devicePairCaptureTool(vision) {
+  return defineTool({
+    name: 'device_pair_capture',
+    description: 'Watch two devices at the same instant: one call captures BOTH screens (PNG + uiautomator digest, ' +
+      'optional OCR) in parallel and attaches both screenshots as real image blocks, so a vision model sees both ' +
+      'players in a single glance. This is the co-op observation primitive — call it right after device_batch (or any ' +
+      'mesh_send) to watch the reaction on both sides.',
+    parameters: {
+      serials: { type: 'array', items: { type: 'string' }, description: 'Exactly two device serials. Defaults to the first two attached devices.' },
+      ocr: { type: 'boolean', description: 'Run PaddleOCR on both screenshots (default false — slower). UI trees usually suffice.' },
+      directory: { type: 'string', description: 'Where to store the PNGs (default: temp).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          devices: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                serial: { type: 'string', required: true },
+                screenshot: { type: 'string' },
+                width: { type: 'integer' },
+                height: { type: 'integer' },
+                foreground: { type: 'string' },
+                ui: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true }, resourceId: { type: 'string' }, bounds: { type: 'array', items: { type: 'integer' } } } } },
+                ocr: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true }, confidence: { type: 'number' }, box: { type: 'array', items: { type: 'integer' } } } } },
+                ocrError: { type: 'string' },
+              },
+            },
+          },
+          images: { type: 'array', items: Vision.IMAGE_REF_SCHEMA },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { devices: [] }
+        const blocks = [{ type: 'text', text: 'Pair capture (both devices, same instant):' }]
+        for (const device of v.devices) {
+          blocks.push({
+            type: 'text',
+            text: [
+              `▶ ${device.serial}${device.foreground ? ` — foreground: ${device.foreground}` : ''}${device.screenshot ? ` [${device.screenshot}${device.width ? ` ${device.width}x${device.height}` : ''}]` : ''}`,
+              ...(device.ui ?? []).slice(0, 25).map((item) => `    - ${item.text}${item.resourceId ? ` [${item.resourceId}]` : ''}${item.bounds ? ` @${item.bounds.join(',')}` : ''}`),
+              ...((device.ui?.length ?? 0) > 25 ? [`    … and ${device.ui.length - 25} more`] : []),
+              ...(device.ocr ?? []).slice(0, 15).map((item) => `    “${item.text}” (${Math.round(item.confidence * 100)}%)`),
+              ...(device.ocrError ? [`    OCR unavailable: ${device.ocrError}`] : []),
+            ].join('\n'),
+          })
+        }
+        return Vision.appendImageBlock(blocks, v)
+      },
+    },
+    async execute(args, exec) {
+      let serials = (Array.isArray(args.serials) ? args.serials : []).filter((s) => typeof s === 'string' && s !== '').slice(0, 2)
+      if (serials.length < 2) {
+        const rows = await DeviceBuild.devices()
+        const online = [...new Set([...serials, ...rows.filter((r) => r.state === 'device').map((r) => r.serial)])]
+        serials = online.slice(0, 2)
+      }
+      if (serials.length < 2) throw new Error(`device_pair_capture needs two devices — found ${serials.length}. Boot a second with device_boot, then mesh-link them.`)
+      const wantOcr = args.ocr === true
+      const devices = await Promise.all(serials.map((serial) => captureForPair(serial, args.directory, wantOcr)))
+      const images = (await Promise.all(devices.map((device) => Vision.maybeAttachScreenshot(vision, device.screenshot, exec)))).filter((image) => image !== undefined)
+      return { devices, ...(images.length > 0 ? { images } : {}) }
+    },
+  })
+}
+
+const MESH_POLICY_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    latencyMs: { type: 'integer', required: true },
+    jitterMs: { type: 'integer', required: true },
+    dropPct: { type: 'number', required: true },
+    dupPct: { type: 'number', required: true },
+    throttleKbps: { type: 'integer', required: true },
+  },
+}
+const MESH_PEER_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    id: { type: 'string', required: true },
+    name: { type: 'string', required: true },
+    role: { type: 'string', required: true },
+    joinedAt: { type: 'integer', required: true },
+    lastSeen: { type: 'integer', required: true },
+    serial: { type: 'string' },
+  },
+}
+const MESH_SESSION_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    id: { type: 'string', required: true },
+    members: { type: 'array', items: { type: 'string' }, required: true },
+    policy: MESH_POLICY_SCHEMA,
+    pending: { type: 'integer', required: true },
+  },
+}
+
+function meshStatusTool(mesh) {
+  return defineTool({
+    name: 'mesh_status',
+    description: 'Inspect the host mesh hub: every peer that joined from a device (a random callsign pinned to its ' +
+      'serial, LocalSend-style), every session with its members, live network policy and undelivered mail. Devices ' +
+      'reach this hub at http://10.0.2.2:<dsh-port>/api/dsh-mobilecode/mesh/* — games POST join {serial?,name?}, ' +
+      'then link/send/poll with the returned id+token.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          peers: { type: 'array', items: MESH_PEER_SCHEMA, required: true },
+          sessions: { type: 'array', items: MESH_SESSION_SCHEMA, required: true },
+          messageSeq: { type: 'integer', required: true },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { peers: [], sessions: [], messageSeq: 0 }
+        const lines = [
+          `mesh: ${v.peers.length} peer(s), ${v.sessions.length} session(s), ${v.messageSeq} message(s) so far`,
+          ...v.peers.map((peer) => `  ● ${peer.name}${peer.serial ? ` (${peer.serial})` : ''} [${peer.role}] last-seen ${new Date(peer.lastSeen).toISOString().slice(11, 19)}`),
+          ...v.sessions.map((s) => `  ◈ ${s.id}: ${s.members.join(' ↔')} — ${JSON.stringify(s.policy)}${s.pending ? ` (${s.pending} undelivered)` : ''}`),
+        ]
+        return [{ type: 'text', text: lines.join('\n') }]
+      },
+    },
+    async execute() {
+      const status = mesh.status()
+      return { peers: status.peers.map(clean), sessions: status.sessions, messageSeq: status.messageSeq }
+    },
+  })
+}
+
+function meshSendTool(mesh) {
+  return defineTool({
+    name: 'mesh_send',
+    description: 'Inject a JSON message into a mesh session AS an existing peer ("ghost" the other player) — the ' +
+      'fastest way to drive a co-op test without touching the app: the receiving game gets it from /mesh/poll ' +
+      'exactly as if its partner sent it, and the hub applies the session latency/drop/dup policy on delivery. ' +
+      'Every injection is logged (via: agent) so you can see how each side reacts.',
+    parameters: {
+      session: { type: 'string', description: 'Session id from mesh_status.' },
+      from: { type: 'string', description: 'Peer name / id to speak as (must be a session member).' },
+      body: { type: 'object', additionalProperties: true, description: 'JSON payload delivered verbatim to the other members.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          seq: { type: 'integer', required: true },
+          delivered: { type: 'integer', required: true },
+          dropped: { type: 'integer', required: true },
+          duplicated: { type: 'integer', required: true },
+          readyAt: { type: 'integer' },
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { seq: 0, delivered: 0, dropped: 0, duplicated: 0 }
+        return [{ type: 'text', text: `mesh message #${v.seq}: delivered ${v.delivered}, dropped ${v.dropped}, duplicated ${v.duplicated}${v.readyAt ? ` (due ${new Date(v.readyAt).toISOString().slice(11, 23)})` : ''}` }]
+      },
+    },
+    async execute(args) {
+      const result = mesh.send({ session: args.session, from: args.from, body: args.body ?? null, via: 'agent' })
+      return clean(result)
+    },
+  })
+}
+
+function meshLogTool(mesh) {
+  return defineTool({
+    name: 'mesh_log',
+    description: 'Read the mesh message log — every join/link/send/drop/dup/tune event with timestamps, sequence ' +
+      'numbers, byte sizes and the acting peer. This is the wire between the players: watch the game talk, spot ' +
+      'policy drops, and correlate traffic bursts with what device_pair_capture shows on both screens.',
+    parameters: {
+      session: { type: 'string', description: 'Only entries for this session id (default: all).' },
+      limit: { type: 'integer', description: 'Most recent N entries (default 50, max 500).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { entries: { type: 'array', items: { type: 'object', additionalProperties: true }, required: true } },
+      },
+      render: (_args, value) => {
+        const entries = value?.entries ?? []
+        const text = entries.length === 0
+          ? 'mesh log is empty'
+          : entries.map((e) => `  ${new Date(e.ts).toISOString().slice(11, 23)} ${e.kind} ${JSON.stringify(Object.fromEntries(Object.entries(e).filter(([k]) => !['seq', 'ts', 'kind'].includes(k))))}`).join('\n')
+        return [{ type: 'text', text: `mesh log (${entries.length} entries):\n${text}` }]
+      },
+    },
+    async execute(args) {
+      return { entries: mesh.log({ session: args.session, limit: args.limit }) }
+    },
+  })
+}
+
+function meshTuneTool(mesh) {
+    return defineTool({
+    name: 'mesh_tune',
+    description: 'Set the network conditions a mesh session delivers under: latencyMs delay, jitterMs random extra ' +
+      'delay, dropPct random message loss, dupPct random duplicates, throttleKbps size-proportional delay (8000 bytes ' +
+      'at 8 Kbps = +1000 ms). Applied per send to every recipient, zero means OFF. This is the desync-testing lever: ' +
+      'make player B lag 400 ms with 100 ms jitter and watch the game handle it — no app code changes.',
+    parameters: {
+      session: { type: 'string', description: 'Session id from mesh_status.' },
+      latencyMs: { type: 'integer', description: 'Fixed per-message delay, 0..5000.' },
+      jitterMs: { type: 'integer', description: 'Random extra delay 0..jitterMs, 0..5000.' },
+      dropPct: { type: 'number', description: 'Chance each recipient-copy is dropped, 0..100.' },
+      dupPct: { type: 'number', description: 'Chance each delivered copy is duplicated, 0..100.' },
+      throttleKbps: { type: 'integer', description: 'Bandwidth cap: adds bytes*8/kbps ms per message. 0 = unlimited.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          session: { type: 'string', required: true },
+          policy: MESH_POLICY_SCHEMA,
+        },
+      },
+      render: (_args, value) => {
+        const v = value ?? { session: '', policy: {} }
+        return [{ type: 'text', text: `session ${v.session} policy → ${JSON.stringify(v.policy)}` }]
+      },
+    },
+    async execute(args) {
+      const policy = mesh.tune(args.session, {
+        latencyMs: args.latencyMs, jitterMs: args.jitterMs, dropPct: args.dropPct, dupPct: args.dupPct, throttleKbps: args.throttleKbps,
+      })
+      return { session: args.session, policy }
+    },
+  })
+}
+
+function meshResetTool(mesh) {
+  return defineTool({
+    name: 'mesh_reset',
+    description: 'Clear mesh state: pass a session id to dissolve that one session, or nothing to wipe ALL peers and ' +
+      'sessions and the log. Devices re-join with /mesh/join afterwards (their callsigns stay pinned to serial), so a ' +
+      'reset between test runs is cheap.',
+    parameters: {
+      session: { type: 'string', description: 'Dissolve only this session (default: full wipe).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { cleared: { type: 'string', required: true } },
+      },
+      render: (_args, value) => [{ type: 'text', text: `mesh cleared: ${value?.cleared ?? '?'}` }],
+    },
+    async execute(args) {
+      if (typeof args.session === 'string' && args.session !== '') {
+        mesh.unlink(args.session)
+        return { cleared: `session ${args.session}` }
+      }
+      mesh.reset()
+      return { cleared: 'everything (peers, sessions, log)' }
+    },
+  })
+}
+
 function deviceBootTool() {
   return defineTool({
     name: 'device_boot',
@@ -2602,6 +3330,28 @@ function guidance() {
     '  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.',
+    '- device_display: read or set a device\'s DPI (wm density) and pixel resolution (wm size) — action get/set/reset.',
+    '  Use it to test layout scaling, or to make two devices share a viewport. Re-observe with device_screen after a change.',
+    '- device_avd_create: create a second virtual device (clone_from copies an existing AVD\'s full hardware config so both',
+    '  players behave identically). Boot it with device_boot; a running emulator holds 5554 so device #2 lands on 5556.',
+    '- device_batch: fire 1..16 input actions concurrently across devices (each step carries its own serial) — the co-op',
+    '  primitive for "both players press attack on the same frame". Per-step results; a failing step never blocks others.',
+    '- device_pair_capture: capture BOTH devices\' screens in one call (parallel PNG + UI digests, both attached as real',
+    '  image blocks) — the way to watch two players at the same instant. Add ocr:true only when UI trees are not enough.',
+    '',
+    'Co-op mesh (v0.8.0) — two emulators cannot multicast-discover each other through their isolated NATs, so the plugin',
+    'hosts a LocalSend-style JSON pub/sub hub. Any app inside an emulator reaches it at http://10.0.2.2:<dsh-port>' +
+    '/api/dsh-mobilecode/mesh/join — POST {serial?,name?} to join (the hub assigns a random callsign like "amber-fox",',
+    'stable per serial, and a token), POST /mesh/link {with:[names]} to form a session, then POST /mesh/send and GET',
+    '/mesh/poll?id&token&after&wait to exchange JSON. The hub is also your observation window and network simulator:',
+    '- mesh_status: who has joined, which sessions exist, live per-session policy and undelivered mail.',
+    '- mesh_send: inject a message as any peer (the other game receives it from /mesh/poll as if its partner sent it).',
+    '- mesh_log: every join/link/send/drop/dup/tune event with timestamps, sizes and latency — the wire between players.',
+    '- mesh_tune: set a session\'s latencyMs / jitterMs / dropPct / dupPct / throttleKbps to desync-test the pair',
+    '  (e.g. latency 400 + jitter 100 on player B) without touching app code.',
+    '- mesh_reset: dissolve one session or wipe everything between test runs.',
+    'Typical co-op loop: device_avd_create + device_boot a clone → both apps join → mesh_link → device_batch inputs at',
+    'both, device_pair_capture to watch, mesh_log to see the traffic, mesh_tune to inject real-world network pain.',
     '',
     '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.',
@@ -2630,10 +3380,12 @@ export function apply(ctx, config) {
   const engine = new DevicePreviewEngine()
   const streamHost = new AndroidStreamHost()
   const streamAccess = new StreamAccess.StreamAccessController()
+  const mesh = new MeshHub()
   const vision = Vision.resolveVisionServices(ctx)
   const handle = {
     engine,
     stream: streamHost,
+    mesh,
     status: () => ({
       directories: [...new Set([...engine.builds.keys()].map((key) => key.split('\0')[0]))],
       servers: [...engine.servers.keys()],
@@ -2644,7 +3396,7 @@ export function apply(ctx, config) {
   if (typeof ctx.provide === 'function') ctx.provide('mobilecode', handle)
   else ctx.mobilecode = handle
 
-  const routes = makeRoutes(engine, config, { host: streamHost, access: streamAccess })
+  const routes = makeRoutes(engine, config, { host: streamHost, access: streamAccess, mesh })
   let disposeRoutes
   let disposeTools
   let disposeSection
@@ -2697,6 +3449,15 @@ export function apply(ctx, config) {
         deviceTapRowTool(),
         deviceBacktraceTool(),
         deviceMeminfoTool(),
+        deviceDisplayTool(),
+        deviceAvdCreateTool(),
+        deviceBatchTool(),
+        devicePairCaptureTool(vision),
+        meshStatusTool(mesh),
+        meshSendTool(mesh),
+        meshLogTool(mesh),
+        meshTuneTool(mesh),
+        meshResetTool(mesh),
       ].map((tool) => ctx.tools.register(tool))
       return () => { for (const dispose of disposers) dispose() }
     }, 'dsh-mobilecode: tools')