mobile-debug-mcp 0.34.0 → 0.36.0

package/src/manage/ios.ts

@@ -1,315 +1,70 @@
+import { checkDebuggerGuard } from '../debugger/guard.js'
+import { buildIOS } from './ios/build.js'
+import type { IOSBuildOptions } from './ios/build-types.js'
+export type { IOSBuildOptions } from './ios/build-types.js'
 import { evidenceDispatch } from '../observe/evidence.js'
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js'
 import { promises as fs } from "fs"
-import { spawn, spawnSync } from "child_process"
+import { spawn } from "child_process"
 import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, InstallAppResponse } from "../types.js"
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "../utils/ios/utils.js"
 import { iOSObserve } from "../observe/ios.js"
-import path from "path"
-
-type BuildEnv = Record<string, string | undefined>
-
-export interface IOSBuildOptions {
-  workspace?: string
-  project?: string
-  scheme?: string
-  destinationUDID?: string
-  derivedDataPath?: string
-  buildJobs?: number
-  forceClean?: boolean
-  xcodeCmd?: string
-  env?: BuildEnv
-}
 
 export class iOSManage {
-  async build(projectPath: string, optsOrVariant?: string | IOSBuildOptions): Promise<{ artifactPath: string, output?: string } | { error: string, diagnostics?: any }> {
-    // Support legacy variant string as second arg
-    const opts: IOSBuildOptions = typeof optsOrVariant === 'string' ? {} : (optsOrVariant || {})
-    const env = { ...process.env, ...(opts.env || {}) }
-
-    try {
-      // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
-      async function findProject(root: string, maxDepth = 4): Promise<{ dir: string, workspace?: string, proj?: string } | null> {
-        try {
-          const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => [])
-          for (const e of ents) {
-            // .xcworkspace and .xcodeproj are directories on disk (bundles), not regular files
-            if (e.name.endsWith('.xcworkspace')) return { dir: root, workspace: e.name }
-            if (e.name.endsWith('.xcodeproj')) return { dir: root, proj: e.name }
-          }
-        } catch {}
-
-        if (maxDepth <= 0) return null
+  async build(projectPath: string, optsOrVariant?: string | IOSBuildOptions) { return buildIOS(projectPath, optsOrVariant) }
 
-        try {
-          const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => [])
-          for (const e of ents) {
-            if (e.isDirectory()) {
-              const candidate = await findProject(path.join(root, e.name), maxDepth - 1)
-              if (candidate) return candidate
-            }
-          }
-        } catch {}
-
-        return null
-      }
-
-      // Resolve projectPath to an absolute path to avoid cwd-relative resolution issues
-      const absProjectPath = path.resolve(projectPath)
-
-      // If caller supplied explicit workspace/project, prefer those and set projectRootDir accordingly
-      let projectRootDir = absProjectPath
-      let workspace: string | undefined = opts.workspace
-      let proj: string | undefined = opts.project
-
-      if (workspace) {
-        // normalize workspace path and set root to its parent
-        workspace = path.isAbsolute(workspace) ? workspace : path.join(absProjectPath, workspace)
-        projectRootDir = path.dirname(workspace)
-        workspace = path.basename(workspace)
-      } else if (proj) {
-        proj = path.isAbsolute(proj) ? proj : path.join(absProjectPath, proj)
-        projectRootDir = path.dirname(proj)
-        proj = path.basename(proj)
-      } else {
-        const projectInfo = await findProject(absProjectPath, 4)
-        if (!projectInfo) return { error: 'No Xcode project or workspace found' }
-        projectRootDir = projectInfo.dir || absProjectPath
-        workspace = projectInfo.workspace
-        proj = projectInfo.proj
-      }
-
-      // Determine destination: prefer explicit option, then env var, otherwise use booted simulator UDID
-      let destinationUDID = opts.destinationUDID || env.MCP_XCODE_DESTINATION_UDID || env.MCP_XCODE_DESTINATION || ''
-      if (!destinationUDID) {
-        try {
-          const meta = await getIOSDeviceMetadata('booted')
-          if (meta && meta.id) destinationUDID = meta.id
-        } catch {}
-      }
+  async installApp(appPath: string, deviceId: string = "booted"): Promise<InstallAppResponse> {
+    const device = await getIOSDeviceMetadata(deviceId)
 
-      // Determine xcode command early so it can be used when detecting schemes
-      const xcodeCmd = opts.xcodeCmd || env.XCODEBUILD_PATH || 'xcodebuild'
+    try {
+      const toInstall = await this.installBundle(appPath)
 
-      // Determine available schemes by querying xcodebuild -list rather than guessing
-      async function detectScheme(xcodeCmdInner: string, workspacePath?: string, projectPathFull?: string, cwd?: string): Promise<string | null> {
+      try {
+        const res = await execCommand(['simctl', 'install', deviceId, toInstall], deviceId)
+        return { device, installed: true, output: res.output }
+      } catch (e) {
+        // Gather diagnostics for simctl failure
+        const diag = execCommandWithDiagnostics(['simctl', 'install', deviceId, toInstall], deviceId)
         try {
-          const args = workspacePath ? ['-list', '-workspace', workspacePath] : ['-list', '-project', projectPathFull!]
-          // Run xcodebuild directly to list schemes
-          const res = spawnSync(xcodeCmdInner, args, { cwd: cwd || projectRootDir, encoding: 'utf8', timeout: 20000 })
-          const out = res.stdout || ''
-          const schemesMatch = out.match(/Schemes:\s*\n([\s\S]*?)(?:\n\n|$)/m)
-          if (schemesMatch) {
-            const block = schemesMatch[1]
-            const schemes = block.split(/\n/).map(s => s.trim()).filter(Boolean)
-            if (schemes.length) return schemes[0]
+          const child = spawn(getIdbCmd(), ['list-targets', '--json'])
+          const idbExists = await new Promise<boolean>((resolve) => {
+            child.on('error', () => resolve(false));
+            child.on('close', (code) => resolve(code === 0));
+          });
+          if (idbExists) {
+            // attempt idb install via spawn but include diagnostics
+            await installWithIdb(toInstall, device.id)
+            return { device, installed: true }
           }
-        } catch {}
-        return null
-      }
-
-      // Prepare build flags and paths (support incremental builds)
-      let buildArgs: string[]
-      let chosenScheme: string | null = opts.scheme || null
-
-      // Derived data and result bundle (agent-configurable)
-      const derivedDataPath = opts.derivedDataPath || env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData')
-      // Use unique result bundle path by default to avoid collisions
-      const resultBundlePath = env.MCP_XCODE_RESULTBUNDLE_PATH || path.join(projectRootDir, 'build', 'xcresults', `ResultBundle-${Date.now()}-${Math.random().toString(36).slice(2)}.xcresult`)
-      const xcodeJobs = typeof opts.buildJobs === 'number' ? opts.buildJobs : (parseInt(env.MCP_XCODE_JOBS || '', 10) || 4)
-      const forceClean = typeof opts.forceClean === 'boolean' ? opts.forceClean : env.MCP_FORCE_CLEAN === '1'
-
-      // ensure result dirs exist
-      await fs.mkdir(path.dirname(resultBundlePath), { recursive: true }).catch(() => {})
-      await fs.mkdir(derivedDataPath, { recursive: true }).catch(() => {})
-      // remove any pre-existing result bundle path to avoid xcodebuild complaining
-      await fs.rm(resultBundlePath, { recursive: true, force: true }).catch(() => {})
-
-      if (workspace) {
-        const workspacePath = path.join(projectRootDir, workspace)
-        if (!chosenScheme) chosenScheme = await detectScheme(xcodeCmd, workspacePath, undefined, projectRootDir)
-        const scheme = chosenScheme || workspace.replace(/\.xcworkspace$/, '')
-        buildArgs = ['-workspace', workspacePath, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build']
-      } else {
-        const projectPathFull = path.join(projectRootDir, proj!)
-        if (!chosenScheme) chosenScheme = await detectScheme(xcodeCmd, undefined, projectPathFull, projectRootDir)
-        const scheme = chosenScheme || proj!.replace(/\.xcodeproj$/, '')
-        buildArgs = ['-project', projectPathFull, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build']
-      }
-
-      // Insert clean if explicitly requested via env or opts
-      if (forceClean) {
-        const idx = buildArgs.indexOf('build')
-        if (idx >= 0) buildArgs.splice(idx, 0, 'clean')
-      }
-
-      // If we have a destination UDID, add an explicit destination to avoid xcodebuild picking an ambiguous target
-      if (destinationUDID) {
-        buildArgs.push('-destination', `platform=iOS Simulator,id=${destinationUDID}`)
-      }
-
-      // Add derived data and result bundle for diagnostics and faster incremental builds
-      buildArgs.push('-derivedDataPath', derivedDataPath)
-      buildArgs.push('-resultBundlePath', resultBundlePath)
-      // parallelisation and jobs
-      buildArgs.push('-parallelizeTargets')
-      buildArgs.push('-jobs', String(xcodeJobs))
-
-      // Prepare results directory for backwards-compatible logs
-      const resultsDir = path.join(projectPath, 'build-results')
-      // Remove any stale results to avoid xcodebuild complaining about existing result bundles
-      await fs.rm(resultsDir, { recursive: true, force: true }).catch(() => {})
-      await fs.mkdir(resultsDir, { recursive: true }).catch(() => {})
-
-
-      const XCODEBUILD_TIMEOUT = parseInt(env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000 // default 3 minutes
-      const MAX_RETRIES = parseInt(env.MCP_XCODEBUILD_RETRIES || '', 10) || 1
-
-      const tries = MAX_RETRIES + 1
-      let lastStdout = ''
-      let lastStderr = ''
-      let lastErr: any = null
-
-      for (let attempt = 1; attempt <= tries; attempt++) {
-        // Run xcodebuild with a watchdog
-          const res = await new Promise<{ code: number | null, stdout: string, stderr: string, killedByWatchdog?: boolean }>((resolve) => {
-          const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir, env })
-          let stdout = ''
-          let stderr = ''
-
-          proc.stdout?.on('data', d => stdout += d.toString())
-          proc.stderr?.on('data', d => stderr += d.toString())
-
-          let killed = false
-          const to = setTimeout(() => {
-            killed = true
-            try { proc.kill('SIGKILL') } catch {}
-          }, XCODEBUILD_TIMEOUT)
-
-          proc.on('close', (code) => {
-            clearTimeout(to)
-            resolve({ code, stdout, stderr, killedByWatchdog: killed })
-          })
-          proc.on('error', (err) => {
-            clearTimeout(to)
-            resolve({ code: null, stdout, stderr: String(err), killedByWatchdog: killed })
-          })
-        })
-
-        lastStdout = res.stdout
-        lastStderr = res.stderr
-
-        if (res.code === 0) {
-          // success — clear any previous error and stop retrying
-          lastErr = null
-          break
-        }
-
-        // record the failure for reporting
-        lastErr = new Error(res.stderr || `xcodebuild failed with code ${res.code}`)
-        // Attach exit code and watchdog info so diagnostics can include them
-        ;(lastErr as any).code = res.code
-        ;(lastErr as any).exitCode = res.code
-        ;(lastErr as any).killedByWatchdog = !!res.killedByWatchdog
-
-        // write logs for diagnostics (helpful whether killed or not)
-        try {
-          await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stdout.log`), res.stdout).catch(() => {})
-          await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stderr.log`), res.stderr).catch(() => {})
-        } catch {}
-
-        // If killed by watchdog and there are remaining attempts, continue to retry
-        if (res.killedByWatchdog && attempt < tries) {
-          continue
-        }
-
-        // no more retries or not a watchdog kill — break to report lastErr
-        if (attempt >= tries) break
-      }
-
-      if (lastErr) {
-        // Include diagnostics and result bundle path when available; provide structured info useful for agents
-        const invokedCommand = `${xcodeCmd} ${buildArgs.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`
-          const envSnapshot = { PATH: env.PATH }
-        return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}`, diagnostics: { exitCode: (lastErr as any).code || null, invokedCommand, cwd: projectRootDir, envSnapshot } }
+        } catch { }
+        return { device, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
       }
-
-      // Try to locate built .app. First search project tree, then DerivedData if necessary
-      const built = await findAppBundle(projectPath)
-      if (built) return { artifactPath: built }
-
-      // Fallback: search DerivedData for matching product
-      const dd = path.join(process.env.HOME || '', 'Library', 'Developer', 'Xcode', 'DerivedData')
-      try {
-        const entries = await fs.readdir(dd).catch(() => [])
-        for (const e of entries) {
-          const candidate = path.join(dd, e)
-          const found = await findAppBundle(candidate).catch(() => undefined)
-          if (found) return { artifactPath: found }
-        }
-      } catch {}
-
-      return { error: 'Could not find .app after build' }
     } catch (e) {
-      return { error: e instanceof Error ? e.message : String(e) }
+      return { device, installed: false, error: e instanceof Error ? e.message : String(e) }
     }
   }
 
-  async installApp(appPath: string, deviceId: string = "booted"): Promise<InstallAppResponse> {
-    const device = await getIOSDeviceMetadata(deviceId)
+  private async installBundle(appPath: string): Promise<string> {
+    let toInstall = appPath
 
-    try {
-      let toInstall = appPath
-
-      const stat = await fs.stat(appPath).catch(() => null)
-      if (stat && stat.isDirectory()) {
-        if (appPath.endsWith('.app')) {
-          toInstall = appPath
+    const stat = await fs.stat(appPath).catch(() => null)
+    if (stat && stat.isDirectory()) {
+      if (appPath.endsWith('.app')) {
+        toInstall = appPath
+      } else {
+        const found = await findAppBundle(appPath)
+        if (found) {
+          toInstall = found
         } else {
-          const found = await findAppBundle(appPath)
-          if (found) {
-            toInstall = found
-          } else {
-            // Reuse the existing build() implementation to avoid duplicating the xcodebuild logic
-            const buildRes = await this.build(appPath)
-            if ((buildRes as any).error) throw new Error((buildRes as any).error)
-            toInstall = (buildRes as any).artifactPath
-          }
+          // Reuse the existing build() implementation to avoid duplicating the xcodebuild logic
+          const buildRes = await this.build(appPath)
+          if ('error' in buildRes) throw new Error(buildRes.error)
+          toInstall = buildRes.artifactPath
         }
       }
-
-      try {
-          const res = await execCommand(['simctl', 'install', deviceId, toInstall], deviceId)
-          return { device, installed: true, output: res.output }
-        } catch (e) {
-          // Gather diagnostics for simctl failure
-          const diag = execCommandWithDiagnostics(['simctl', 'install', deviceId, toInstall], deviceId)
-          try {
-            const child = spawn(getIdbCmd(), ['list-targets', '--json'])
-            const idbExists = await new Promise<boolean>((resolve) => {
-              child.on('error', () => resolve(false));
-              child.on('close', (code) => resolve(code === 0));
-            });
-            if (idbExists) {
-              // attempt idb install via spawn but include diagnostics
-              await new Promise<void>((resolve, reject) => {
-                const proc = spawn(getIdbCmd(), ['install', toInstall, '--udid', device.id]);
-                let stderr = '';
-                proc.stderr.on('data', d => stderr += d.toString());
-                proc.on('close', code => {
-                  if (code === 0) resolve();
-                  else reject(new Error(stderr || `idb install failed with code ${code}`));
-                });
-                proc.on('error', err => reject(err));
-              });
-              return { device, installed: true }
-            }
-          } catch {}
-          return { device, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
-        }
-    } catch (e) {
-      return { device, installed: false, error: e instanceof Error ? e.message : String(e) }
     }
+
+    return toInstall
   }
 
   async startApp(bundleId: string, deviceId: string = "booted", observe = true): Promise<StartAppResponse> {
@@ -336,7 +91,7 @@ export class iOSManage {
     } catch (e: unknown) {
       const device = await getIOSDeviceMetadata(deviceId)
       const diagnostics = hasFiniteBudget() ? undefined : execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId)
-      return { device, appStarted: false, launchTimeMs: performance.now() - started, error: e instanceof Error ? e.message : String(e), ...(diagnostics ? { diagnostics } : {}) } as any
+      return { device, appStarted: false, launchTimeMs: performance.now() - started, error: e instanceof Error ? e.message : String(e), ...(diagnostics ? { diagnostics } : {}) }
     }
   }
 
@@ -350,7 +105,7 @@ export class iOSManage {
     } catch (e: unknown) {
       const diag = hasFiniteBudget() ? undefined : execCommandWithDiagnostics(['simctl', 'terminate', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
-      return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), ...(diag ? { diagnostics: diag } : {}) } as any
+      return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), ...(diag ? { diagnostics: diag } : {}) }
     }
   }
 
@@ -387,19 +142,33 @@ export class iOSManage {
         const libraryPath = `${dataPath}/Library`
         const documentsPath = `${dataPath}/Documents`
         const tmpPath = `${dataPath}/tmp`
-        await fs.rm(libraryPath, { recursive: true, force: true }).catch(() => {})
-        await fs.rm(documentsPath, { recursive: true, force: true }).catch(() => {})
-        await fs.rm(tmpPath, { recursive: true, force: true }).catch(() => {})
-        await fs.mkdir(libraryPath, { recursive: true }).catch(() => {})
-        await fs.mkdir(documentsPath, { recursive: true }).catch(() => {})
-        await fs.mkdir(tmpPath, { recursive: true }).catch(() => {})
+        await fs.rm(libraryPath, { recursive: true, force: true }).catch(() => { })
+        await fs.rm(documentsPath, { recursive: true, force: true }).catch(() => { })
+        await fs.rm(tmpPath, { recursive: true, force: true }).catch(() => { })
+        await fs.mkdir(libraryPath, { recursive: true }).catch(() => { })
+        await fs.mkdir(documentsPath, { recursive: true }).catch(() => { })
+        await fs.mkdir(tmpPath, { recursive: true }).catch(() => { })
         return { device, dataCleared: true }
       } catch (e) {
         throw new Error(`Failed to clear data for ${bundleId}: ${e instanceof Error ? e.message : String(e)}`)
       }
     } catch (e: unknown) {
       const diag = execCommandWithDiagnostics(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId)
-      return { device, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
+      return { device, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
     }
   }
 }
+
+async function installWithIdb(toInstall: string, deviceId: string) {
+  await new Promise<void>((resolve, reject) => {
+    checkDebuggerGuard(true)
+    const proc = spawn(getIdbCmd(), ['install', toInstall, '--udid', deviceId]);
+    let stderr = '';
+    proc.stderr.on('data', d => stderr += d.toString());
+    proc.on('close', code => {
+      if (code === 0) resolve();
+      else reject(new Error(stderr || `idb install failed with code ${code}`));
+    });
+    proc.on('error', err => reject(err));
+  });
+}

package/src/observe/android/context.ts

@@ -0,0 +1 @@
+export const activeLogStreams: Map<string, { proc: import('node:child_process').ChildProcess, file: string, device?: { platform: 'android' | 'ios'; id: string } }> = new Map()

package/src/observe/android/current-screen.ts

@@ -0,0 +1,63 @@
+import { GetCurrentScreenResponse } from "../../types.js"
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../../utils/android/utils.js"
+export async function collectGetCurrentScreen(deviceId?: string): Promise<GetCurrentScreenResponse> {
+  const metadata = await getAndroidDeviceMetadata("", deviceId)
+  const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+  try {
+    const output = await execAdb(['shell', 'dumpsys', 'activity', 'activities'], deviceId, { timeout: 10000 })
+    const lines = output.split('\n');
+    let resumedLine = lines.find(line => /^\s*mResumedActivity:/.test(line));
+
+    if (!resumedLine) {
+      resumedLine = lines.find(line => /^\s*ResumedActivity:/.test(line));
+    }
+
+    if (!resumedLine) {
+      return {
+        device: deviceInfo,
+        package: "",
+        activity: "",
+        shortActivity: "",
+        error: "Could not find 'mResumedActivity' in dumpsys output"
+      }
+    }
+
+    const match = resumedLine.match(/ActivityRecord\{[^ ]*(?:\s+[^ ]+)*\s+([^\/ ]+)\/([^ \{}]+)[^}]*\}/);
+
+    if (match) {
+      const packageName = match[1];
+      let activityName = match[2];
+
+      if (activityName.startsWith('.')) {
+        activityName = packageName + activityName;
+      }
+
+      const shortActivity = activityName.split('.').pop() || activityName;
+
+      return {
+        device: deviceInfo,
+        package: packageName,
+        activity: activityName,
+        shortActivity: shortActivity
+      };
+    } else {
+      return {
+        device: deviceInfo,
+        package: "",
+        activity: "",
+        shortActivity: "",
+        error: `Found resumed activity line but failed to parse: '${resumedLine.trim()}'`
+      }
+    }
+
+  } catch (e) {
+    return {
+      device: deviceInfo,
+      package: "",
+      activity: "",
+      shortActivity: "",
+      error: e instanceof Error ? e.message : String(e)
+    };
+  }
+}

package/src/observe/android/fingerprint.ts

@@ -0,0 +1,13 @@
+import { computeScreenFingerprint } from "../../utils/ui/index.js"
+import type { AndroidObserve } from '../android.js'
+export async function collectGetScreenFingerprint(source: Pick<AndroidObserve, 'getUITree' | 'getCurrentScreen'>, deviceId?: string): Promise<{ fingerprint: string | null; activity?: string; error?: string; captured_at_ms?: number }> {
+  try {
+    const tree = await source.getUITree(deviceId)
+    if (!tree || tree.error) return { fingerprint: null, error: tree.error }
+
+    const current = await source.getCurrentScreen(deviceId).catch(() => null)
+    return { ...computeScreenFingerprint(tree, current, 'android', 50), captured_at_ms: tree.captured_at_ms }
+  } catch (e) {
+    return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
+  }
+}

package/src/observe/android/log-stream.ts

@@ -0,0 +1,127 @@
+import type { StreamLogEntry } from '../logs/model.js'
+import { spawn } from "child_process"
+import { getAdbCmd, execAdb, parseLogLine } from "../../utils/android/utils.js"
+import { createWriteStream } from "fs"
+import { promises as fsPromises } from "fs"
+import path from "path"
+import { activeLogStreams } from './context.js'
+export async function startLogStream(packageName: string, level: 'error' | 'warn' | 'info' | 'debug' = 'error', deviceId?: string, sessionId: string = 'default') {
+  try {
+    const pidOutput = await execAdb(['shell', 'pidof', packageName], deviceId).catch(() => '')
+    const pid = (pidOutput || '').trim()
+    if (!pid) return { success: false, error: 'app_not_running' }
+
+    const levelMap: Record<string, string> = { error: '*:E', warn: '*:W', info: '*:I', debug: '*:D' }
+    const filter = levelMap[level] || levelMap['error']
+
+    if (activeLogStreams.has(sessionId)) {
+      try { activeLogStreams.get(sessionId)!.proc.kill() } catch { }
+      activeLogStreams.delete(sessionId)
+    }
+
+    const args = [...(deviceId ? ['-s', deviceId] : []), 'logcat', `--pid=${pid}`, filter]
+    const proc = spawn(getAdbCmd(), args)
+
+    const tmpDir = process.env.TMPDIR || '/tmp'
+    const file = path.join(tmpDir, `mobile-debug-log-${sessionId}.ndjson`)
+    const stream = createWriteStream(file, { flags: 'a' })
+
+    proc.stdout.on('data', (chunk) => {
+      const text = chunk.toString()
+      const lines = text.split(/\r?\n/).filter(Boolean)
+      for (const l of lines) {
+        const entry = parseLogLine(l)
+        stream.write(JSON.stringify(entry) + '\n')
+      }
+    })
+
+    proc.stderr.on('data', (chunk) => {
+      const text = chunk.toString()
+      const lines = text.split(/\r?\n/).filter(Boolean)
+      for (const l of lines) {
+        const entry = { timestamp: '', level: 'E', tag: 'adb', message: l }
+        stream.write(JSON.stringify(entry) + '\n')
+      }
+    })
+
+    proc.on('close', () => {
+      stream.end()
+      if (activeLogStreams.get(sessionId)?.proc === proc) activeLogStreams.delete(sessionId)
+    })
+
+    activeLogStreams.set(sessionId, { proc, file, device: { platform: 'android', id: deviceId ?? '' } })
+    return { success: true, stream_started: true }
+  } catch (e) {
+    return { success: false, error: e instanceof Error ? e.message : String(e) }
+  }
+}
+
+export async function stopLogStream(sessionId: string = 'default') {
+  const entry = activeLogStreams.get(sessionId)
+  if (!entry) return { success: true }
+  try { entry.proc.kill() } catch { }
+  activeLogStreams.delete(sessionId)
+  return { success: true }
+}
+
+export async function collectReadLogStream(sessionId: string = 'default', limit: number = 100, since?: string) {
+  const entry = activeLogStreams.get(sessionId)
+  let file: string | undefined
+  if (entry && entry.file) file = entry.file
+  else {
+    const tmpDir = process.env.TMPDIR || '/tmp'
+    const candidate = path.join(tmpDir, `mobile-debug-log-${sessionId}.ndjson`)
+    file = candidate
+  }
+
+  try {
+    const data = await fsPromises.readFile(file, 'utf8').catch(() => '')
+    if (!data) return { entries: [], crash_summary: { crash_detected: false } }
+    const lines = data.split(/\r?\n/).filter(Boolean)
+
+    const parsed = lines.map(l => {
+      try {
+        const obj = JSON.parse(l) as StreamLogEntry
+        if (typeof obj._iso === 'undefined') {
+          let iso: string | null = null
+          if (obj.timestamp) {
+            const d = new Date(obj.timestamp)
+            if (!isNaN(d.getTime())) iso = d.toISOString()
+          }
+          obj._iso = iso
+        }
+        if (typeof obj.crash === 'undefined') {
+          const msg = (obj.message || '').toString()
+          const exMatch = msg.match(/\b([A-Za-z0-9_$.]+Exception)\b/)
+          if (/FATAL EXCEPTION/i.test(msg) || exMatch) {
+            obj.crash = true
+            if (exMatch) obj.exception = exMatch[1]
+          } else {
+            obj.crash = false
+          }
+        }
+        return obj
+      } catch {
+        return { message: l, _iso: null, crash: false }
+      }
+    })
+
+    let filtered = parsed
+    if (since) {
+      let sinceMs: number | null = null
+      if (/^\d+$/.test(since)) sinceMs = Number(since)
+      else {
+        const sDate = new Date(since)
+        if (!isNaN(sDate.getTime())) sinceMs = sDate.getTime()
+      }
+      if (sinceMs !== null) filtered = parsed.filter(p => p._iso && (new Date(p._iso).getTime() >= sinceMs))
+    }
+
+    const entries = filtered.slice(-Math.max(0, limit))
+    const crashEntry = entries.find(e => e.crash)
+    const crash_summary = crashEntry ? { crash_detected: true, exception: crashEntry.exception, sample: crashEntry.message } : { crash_detected: false }
+    return { entries, crash_summary }
+  } catch {
+    return { entries: [], crash_summary: { crash_detected: false } }
+  }
+}