mobile-debug-mcp 0.10.0 → 0.12.0

package/README.md

@@ -1,13 +1,15 @@
-# Mobile Debug MCP
+# Mobile Dev Agent Tools
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 
+> **Note:** iOS support is currently only tested on simulator. Please use with caution and report any issues.
+
 ## Requirements
 
 - Node.js >= 18
-- Android SDK (adb) for Android support
+- [Android SDK](https://developer.android.com/studio) (adb) for Android support
 - Xcode command-line tools for iOS support
-- Optional: idb for enhanced iOS device support
+- [idb](https://github.com/facebook/idb) for iOS device support
 
 ## Configuration example
 
@@ -17,13 +19,17 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
     "mobile-debug": {
       "command": "npx",
       "args": ["--yes","mobile-debug-mcp","server"],
-      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun" }
+      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun", "IDB_PATH": "/path/to/idb" }
     }
   }
 }
 ```
 ## Usage
-//TODO add examples
+
+Example: 
+After a crash tell the agent the following:
+
+I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
 
 ## Docs
 
@@ -33,3 +39,12 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
 ## License
 
 MIT
+
+## IDB/ADB healthcheck and diagnostics
+
+The agent provides healthcheck and optional auto-install scripts for iOS (idb) and Android (adb).
+
+- Run `npm run healthcheck` to verify idb is available. Set `MCP_AUTO_INSTALL_IDB=true` to allow the installer to run in CI or non-interactive environments.
+- Override detection with `IDB_PATH` or `ADB_PATH` environment variables.
+- Tools now return structured diagnostics on failures: { exitCode, stdout, stderr, command, args, envSnapshot, suggestedFixes } which helps agents decide corrective actions.
+

package/dist/android/diagnostics.js

@@ -0,0 +1,24 @@
+import { spawnSync } from 'child_process';
+import { getAdbCmd } from './utils.js';
+import { makeEnvSnapshot } from '../utils/diagnostics.js';
+export function execAdbWithDiagnostics(args, deviceId) {
+    const adbArgs = deviceId ? ['-s', deviceId, ...args] : args;
+    const timeout = 120000;
+    const res = spawnSync(getAdbCmd(), adbArgs, { encoding: 'utf8', timeout });
+    const runResult = {
+        exitCode: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout || '',
+        stderr: res.stderr || '',
+        envSnapshot: makeEnvSnapshot(['PATH', 'ADB_PATH', 'HOME', 'JAVA_HOME']),
+        command: getAdbCmd(),
+        args: adbArgs,
+        suggestedFixes: []
+    };
+    if (res.status !== 0) {
+        if ((runResult.stderr || '').includes('device not found'))
+            runResult.suggestedFixes.push('Ensure device is connected and adb is authorized (adb devices)');
+        if ((runResult.stderr || '').includes('No such file or directory'))
+            runResult.suggestedFixes.push('Verify ADB_PATH or that adb is installed');
+    }
+    return { runResult };
+}

package/dist/android/interact.js

@@ -1,10 +1,5 @@
-import { execAdb, getAndroidDeviceMetadata, getDeviceInfo, spawnAdb } from "./utils.js";
-import { detectJavaHome } from "../utils/java.js";
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js";
 import { AndroidObserve } from "./observe.js";
-import { promises as fs } from "fs";
-import { spawn } from "child_process";
-import path from "path";
-import { existsSync } from "fs";
 export class AndroidInteract {
     observe = new AndroidObserve();
     async waitForElement(text, timeout, deviceId) {
@@ -81,143 +76,4 @@ export class AndroidInteract {
             return { device: deviceInfo, success: false, error: e instanceof Error ? e.message : String(e) };
         }
     }
-    async installApp(apkPath, deviceId) {
-        const metadata = await getAndroidDeviceMetadata("", deviceId);
-        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        // Helper to recursively find first APK under a directory
-        async function findApk(dir) {
-            const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
-            for (const e of entries) {
-                const full = path.join(dir, e.name);
-                if (e.isDirectory()) {
-                    const found = await findApk(full);
-                    if (found)
-                        return found;
-                }
-                else if (e.isFile() && full.endsWith('.apk')) {
-                    return full;
-                }
-            }
-            return undefined;
-        }
-        try {
-            let apkToInstall = apkPath;
-            // If a directory is provided, attempt to build via Gradle
-            const stat = await fs.stat(apkPath).catch(() => null);
-            if (stat && stat.isDirectory()) {
-                const gradlewPath = path.join(apkPath, 'gradlew');
-                const gradleCmd = existsSync(gradlewPath) ? './gradlew' : 'gradle';
-                await new Promise(async (resolve, reject) => {
-                    // Auto-detect and set JAVA_HOME (prefer JDK 17) so builds don't require manual environment setup
-                    const detectedJavaHome = await detectJavaHome().catch(() => undefined);
-                    const env = Object.assign({}, process.env);
-                    if (detectedJavaHome) {
-                        // Override existing JAVA_HOME if detection found a preferably compatible JDK (e.g., JDK 17).
-                        if (env.JAVA_HOME !== detectedJavaHome) {
-                            env.JAVA_HOME = detectedJavaHome;
-                            // Also ensure the JDK bin is on PATH so tools like jlink/javac are resolved from the detected JDK
-                            env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`;
-                            console.debug('[android] Overriding JAVA_HOME with detected path:', detectedJavaHome);
-                        }
-                    }
-                    // Sanitize environment so user shell init scripts are less likely to override our JAVA_HOME.
-                    try {
-                        // Remove obvious shell profile hints; avoid touching SDKMAN symlinks or on-disk state.
-                        delete env.SHELL;
-                    }
-                    catch { }
-                    // If we detected a compatible JDK, instruct Gradle to use it and avoid daemon reuse
-                    // Prepare gradle invocation
-                    const gradleArgs = ['assembleDebug'];
-                    if (detectedJavaHome) {
-                        gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`);
-                        gradleArgs.push('--no-daemon');
-                        env.GRADLE_JAVA_HOME = detectedJavaHome;
-                    }
-                    // Prefer invoking the wrapper directly without a shell to avoid user profile shims (sdkman) re-setting JAVA_HOME
-                    const wrapperPath = path.join(apkPath, 'gradlew');
-                    const useWrapper = existsSync(wrapperPath);
-                    const execCmd = useWrapper ? wrapperPath : gradleCmd;
-                    const spawnOpts = { cwd: apkPath, env };
-                    // When using wrapper, ensure it's executable and invoke directly (no shell)
-                    if (useWrapper) {
-                        // Ensure the wrapper is executable; swallow errors from chmod (best-effort).
-                        await fs.chmod(wrapperPath, 0o755).catch(() => { });
-                        spawnOpts.shell = false;
-                    }
-                    else {
-                        // if using system 'gradle' allow shell to resolve platform PATH
-                        spawnOpts.shell = true;
-                    }
-                    const proc = spawn(execCmd, gradleArgs, spawnOpts);
-                    let stderr = '';
-                    proc.stderr?.on('data', d => stderr += d.toString());
-                    proc.on('close', code => {
-                        if (code === 0)
-                            resolve();
-                        else
-                            reject(new Error(stderr || `Gradle build failed with code ${code}`));
-                    });
-                    proc.on('error', err => reject(err));
-                });
-                const built = await findApk(apkPath);
-                if (!built)
-                    throw new Error('Could not locate built APK after running Gradle');
-                apkToInstall = built;
-            }
-            // Try normal adb install with streaming attempt
-            try {
-                const res = await spawnAdb(['install', '-r', apkToInstall], deviceId);
-                if (res.code === 0) {
-                    return { device: deviceInfo, installed: true, output: res.stdout };
-                }
-                // fallthrough to fallback
-            }
-            catch (e) {
-                // Log and continue to fallback
-                console.debug('[android] adb install failed, attempting push+pm fallback:', e instanceof Error ? e.message : String(e));
-            }
-            // Fallback: push APK to device and use pm install -r
-            const basename = path.basename(apkToInstall);
-            const remotePath = `/data/local/tmp/${basename}`;
-            await execAdb(['push', apkToInstall, remotePath], deviceId);
-            const pmOut = await execAdb(['shell', 'pm', 'install', '-r', remotePath], deviceId);
-            // cleanup remote file
-            try {
-                await execAdb(['shell', 'rm', remotePath], deviceId);
-            }
-            catch { }
-            return { device: deviceInfo, installed: true, output: pmOut };
-        }
-        catch (e) {
-            return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e) };
-        }
-    }
-    async startApp(appId, deviceId) {
-        const metadata = await getAndroidDeviceMetadata(appId, deviceId);
-        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
-        return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 };
-    }
-    async terminateApp(appId, deviceId) {
-        const metadata = await getAndroidDeviceMetadata(appId, deviceId);
-        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
-        return { device: deviceInfo, appTerminated: true };
-    }
-    async restartApp(appId, deviceId) {
-        await this.terminateApp(appId, deviceId);
-        const startResult = await this.startApp(appId, deviceId);
-        return {
-            device: startResult.device,
-            appRestarted: startResult.appStarted,
-            launchTimeMs: startResult.launchTimeMs
-        };
-    }
-    async resetAppData(appId, deviceId) {
-        const metadata = await getAndroidDeviceMetadata(appId, deviceId);
-        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
-        return { device: deviceInfo, dataCleared: output === 'Success' };
-    }
 }

package/dist/android/manage.js

@@ -0,0 +1,162 @@
+import { promises as fs } from 'fs';
+import { spawn } from 'child_process';
+import path from 'path';
+import { existsSync } from 'fs';
+import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from './utils.js';
+import { execAdbWithDiagnostics } from './diagnostics.js';
+import { detectJavaHome } from '../utils/java.js';
+export class AndroidManage {
+    async build(projectPath, _variant) {
+        void _variant;
+        try {
+            // Always use the shared prepareGradle utility for consistent env/setup
+            const { execCmd, gradleArgs, spawnOpts } = await (await import('./utils.js')).prepareGradle(projectPath);
+            await new Promise((resolve, reject) => {
+                const proc = spawn(execCmd, gradleArgs, spawnOpts);
+                let stderr = '';
+                proc.stderr?.on('data', d => stderr += d.toString());
+                proc.on('close', code => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(stderr || `Gradle failed with code ${code}`));
+                });
+                proc.on('error', err => reject(err));
+            });
+            const apk = await findApk(projectPath);
+            if (!apk)
+                return { error: 'Could not find APK after build' };
+            return { artifactPath: apk };
+        }
+        catch (e) {
+            return { error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async installApp(apkPath, deviceId) {
+        const metadata = await getAndroidDeviceMetadata('', deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        let apkToInstall = apkPath;
+        try {
+            const stat = await fs.stat(apkPath).catch(() => null);
+            if (stat && stat.isDirectory()) {
+                const detectedJavaHome = await detectJavaHome().catch(() => undefined);
+                const env = Object.assign({}, process.env);
+                if (detectedJavaHome) {
+                    if (env.JAVA_HOME !== detectedJavaHome) {
+                        env.JAVA_HOME = detectedJavaHome;
+                        env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`;
+                        console.debug('[android-run] Overriding JAVA_HOME with detected path:', detectedJavaHome);
+                    }
+                }
+                try {
+                    delete env.SHELL;
+                }
+                catch { }
+                const gradleArgs = ['assembleDebug'];
+                if (detectedJavaHome) {
+                    gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`);
+                    gradleArgs.push('--no-daemon');
+                    env.GRADLE_JAVA_HOME = detectedJavaHome;
+                }
+                const wrapperPath = path.join(apkPath, 'gradlew');
+                const useWrapper = existsSync(wrapperPath);
+                const execCmd = useWrapper ? wrapperPath : 'gradle';
+                const spawnOpts = { cwd: apkPath, env };
+                if (useWrapper) {
+                    await fs.chmod(wrapperPath, 0o755).catch(() => { });
+                    spawnOpts.shell = false;
+                }
+                else
+                    spawnOpts.shell = true;
+                const proc = spawn(execCmd, gradleArgs, spawnOpts);
+                let stderr = '';
+                await new Promise((resolve, reject) => {
+                    proc.stderr?.on('data', d => stderr += d.toString());
+                    proc.on('close', code => {
+                        if (code === 0)
+                            resolve();
+                        else
+                            reject(new Error(stderr || `Gradle build failed with code ${code}`));
+                    });
+                    proc.on('error', err => reject(err));
+                });
+                const built = await findApk(apkPath);
+                if (!built)
+                    throw new Error('Could not locate built APK after running Gradle');
+                apkToInstall = built;
+            }
+            try {
+                const res = await spawnAdb(['install', '-r', apkToInstall], deviceId);
+                if (res.code === 0) {
+                    return { device: deviceInfo, installed: true, output: res.stdout };
+                }
+            }
+            catch (e) {
+                console.debug('[android-run] adb install failed, attempting push+pm fallback:', e instanceof Error ? e.message : String(e));
+            }
+            const basename = path.basename(apkToInstall);
+            const remotePath = `/data/local/tmp/${basename}`;
+            await execAdb(['push', apkToInstall, remotePath], deviceId);
+            const pmOut = await execAdb(['shell', 'pm', 'install', '-r', remotePath], deviceId);
+            try {
+                await execAdb(['shell', 'rm', remotePath], deviceId);
+            }
+            catch { }
+            return { device: deviceInfo, installed: true, output: pmOut };
+        }
+        catch (e) {
+            // gather diagnostics for attempted adb operations
+            const basename = path.basename(apkToInstall);
+            const remotePath = `/data/local/tmp/${basename}`;
+            const installDiag = execAdbWithDiagnostics(['install', '-r', apkToInstall], deviceId);
+            const pushDiag = execAdbWithDiagnostics(['push', apkToInstall, remotePath], deviceId);
+            const pmDiag = execAdbWithDiagnostics(['shell', 'pm', 'install', '-r', remotePath], deviceId);
+            return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: { installDiag, pushDiag, pmDiag } };
+        }
+    }
+    async startApp(appId, deviceId) {
+        const metadata = await getAndroidDeviceMetadata(appId, deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
+            return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 };
+        }
+        catch (e) {
+            const diag = execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
+            return { device: deviceInfo, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
+    }
+    async terminateApp(appId, deviceId) {
+        const metadata = await getAndroidDeviceMetadata(appId, deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
+            return { device: deviceInfo, appTerminated: true };
+        }
+        catch (e) {
+            const diag = execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId);
+            return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
+    }
+    async restartApp(appId, deviceId) {
+        await this.terminateApp(appId, deviceId);
+        const startResult = await this.startApp(appId, deviceId);
+        return {
+            device: startResult.device,
+            appRestarted: startResult.appStarted,
+            launchTimeMs: startResult.launchTimeMs
+        };
+    }
+    async resetAppData(appId, deviceId) {
+        const metadata = await getAndroidDeviceMetadata(appId, deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
+            return { device: deviceInfo, dataCleared: output === 'Success' };
+        }
+        catch (e) {
+            const diag = execAdbWithDiagnostics(['shell', 'pm', 'clear', appId], deviceId);
+            return { device: deviceInfo, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
+    }
+}

package/dist/android/observe.js

@@ -1,91 +1,10 @@
 import { spawn } from "child_process";
 import { XMLParser } from "fast-xml-parser";
-import { ADB, execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js";
-// --- Helper Functions Specific to Observe ---
-const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-function parseBounds(bounds) {
-    const match = bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
-    if (match) {
-        return [parseInt(match[1]), parseInt(match[2]), parseInt(match[3]), parseInt(match[4])];
-    }
-    return [0, 0, 0, 0];
-}
-function getCenter(bounds) {
-    const [x1, y1, x2, y2] = bounds;
-    return [Math.floor((x1 + x2) / 2), Math.floor((y1 + y2) / 2)];
-}
-async function getScreenResolution(deviceId) {
-    try {
-        const output = await execAdb(['shell', 'wm', 'size'], deviceId);
-        const match = output.match(/Physical size: (\d+)x(\d+)/);
-        if (match) {
-            return { width: parseInt(match[1]), height: parseInt(match[2]) };
-        }
-    }
-    catch {
-        // ignore
-    }
-    return { width: 0, height: 0 };
-}
-function traverseNode(node, elements, parentIndex = -1, depth = 0) {
-    if (!node)
-        return -1;
-    let currentIndex = -1;
-    // Check if it's a valid node with attributes we care about
-    if (node['@_class']) {
-        const text = node['@_text'] || null;
-        const contentDescription = node['@_content-desc'] || null;
-        const clickable = node['@_clickable'] === 'true';
-        const bounds = parseBounds(node['@_bounds'] || '[0,0][0,0]');
-        // Filtering Logic:
-        // Keep if clickable OR has visible text OR has content description
-        const isUseful = clickable || (text && text.length > 0) || (contentDescription && contentDescription.length > 0);
-        if (isUseful) {
-            const element = {
-                text,
-                contentDescription,
-                type: node['@_class'] || 'unknown',
-                resourceId: node['@_resource-id'] || null,
-                clickable,
-                enabled: node['@_enabled'] === 'true',
-                visible: true,
-                bounds,
-                center: getCenter(bounds),
-                depth
-            };
-            if (parentIndex !== -1) {
-                element.parentId = parentIndex;
-            }
-            elements.push(element);
-            currentIndex = elements.length - 1;
-        }
-    }
-    // If current node was skipped (not useful or no class), children inherit parentIndex
-    // If current node was added, children use currentIndex
-    const nextParentIndex = currentIndex !== -1 ? currentIndex : parentIndex;
-    const nextDepth = currentIndex !== -1 ? depth + 1 : depth;
-    const childrenIndices = [];
-    // Traverse children
-    if (node.node) {
-        if (Array.isArray(node.node)) {
-            node.node.forEach((child) => {
-                const childIndex = traverseNode(child, elements, nextParentIndex, nextDepth);
-                if (childIndex !== -1)
-                    childrenIndices.push(childIndex);
-            });
-        }
-        else {
-            const childIndex = traverseNode(node.node, elements, nextParentIndex, nextDepth);
-            if (childIndex !== -1)
-                childrenIndices.push(childIndex);
-        }
-    }
-    // Update current element with children if it was added
-    if (currentIndex !== -1 && childrenIndices.length > 0) {
-        elements[currentIndex].children = childrenIndices;
-    }
-    return currentIndex;
-}
+import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "./utils.js";
+import { createWriteStream } from "fs";
+import { promises as fsPromises } from "fs";
+import path from "path";
+const activeLogStreams = new Map();
 export class AndroidObserve {
     async getDeviceMetadata(appId, deviceId) {
         return getAndroidDeviceMetadata(appId, deviceId);
@@ -148,7 +67,7 @@ export class AndroidObserve {
             };
         }
         catch (e) {
-            const errorMessage = `Failed to get UI tree. ADB Path: '${ADB}'. Error: ${e instanceof Error ? e.message : String(e)}`;
+            const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
             console.error(errorMessage);
             return {
                 device: deviceInfo,
@@ -196,7 +115,7 @@ export class AndroidObserve {
             // Need to construct ADB args manually since spawn handles it
             const args = deviceId ? ['-s', deviceId, 'exec-out', 'screencap', '-p'] : ['exec-out', 'screencap', '-p'];
             // Using spawn for screencap as well to ensure consistent process handling
-            const child = spawn(ADB, args);
+            const child = spawn(getAdbCmd(), args);
             const chunks = [];
             let stderr = '';
             child.stdout.on('data', (chunk) => {
@@ -310,4 +229,130 @@ export class AndroidObserve {
             };
         }
     }
+    async startLogStream(packageName, level = 'error', deviceId, sessionId = '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 = { 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 = ['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();
+                activeLogStreams.delete(sessionId);
+            });
+            activeLogStreams.set(sessionId, { proc, file });
+            return { success: true, stream_started: true };
+        }
+        catch (e) {
+            return { success: false, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async stopLogStream(sessionId = 'default') {
+        const entry = activeLogStreams.get(sessionId);
+        if (!entry)
+            return { success: true };
+        try {
+            entry.proc.kill();
+        }
+        catch { }
+        activeLogStreams.delete(sessionId);
+        return { success: true };
+    }
+    async readLogStream(sessionId = 'default', limit = 100, since) {
+        // Prefer active stream if present, otherwise fall back to a well-known NDJSON file for the session
+        const entry = activeLogStreams.get(sessionId);
+        let file;
+        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);
+                    if (typeof obj._iso === 'undefined') {
+                        let iso = 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 = 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 } };
+        }
+    }
 }