mobile-debug-mcp 0.6.0 → 0.8.0

package/README.md

@@ -98,6 +98,21 @@ Example WebUI MCP config using `npx --yes` and environment variables:
 
 All tools accept a JSON input payload and return a structured JSON response. **Every response includes a `device` object** (with information about the selected device/simulator used for the operation), plus the tool-specific output.
 
+### list_devices
+Enumerate connected Android devices and iOS simulators.
+
+Input (optional):
+```jsonc
+{ "platform": "android" | "ios" }
+```
+
+Response:
+```json
+{ "devices": [ { "id": "emulator-5554", "platform": "android", "osVersion": "11", "model": "sdk_gphone64_arm64", "simulator": true, "appInstalled": false } ] }
+```
+
+Use `list_devices` when multiple devices are attached to inspect metadata and pick a device explicitly by passing `deviceId` to subsequent tool calls.
+
 ### start_app
 Launch a mobile app.
 
@@ -226,6 +241,74 @@ Clear app storage (reset to fresh install state).
 }
 ```
 
+### install_app
+Install an app onto a connected device or simulator (APK for Android, .app/.ipa for iOS).
+
+**Input:**
+```jsonc
+{
+  "platform": "android" | "ios",
+  "appPath": "/path/to/app.apk_or_app.app_or_ipa", // Host path to the app file (Required)
+  "deviceId": "emulator-5554" // Optional: target specific device/simulator
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "installed": true,
+  "output": "Platform-specific installer output (adb/simctl/idb)",
+  "error": "Optional error message if installation failed"
+}
+```
+
+Notes:
+- Android: uses `adb install -r <apkPath>`. The APK must be accessible from the host running the MCP server.
+- iOS: attempts `xcrun simctl install` for simulators and falls back to `idb install` if available for physical devices. Ensure `XCRUN_PATH` and `IDB` are configured if using non-standard locations.
+- Installation output and errors are surfaced in the response for debugging.
+
+### start_log_stream / read_log_stream / stop_log_stream
+Start a live log stream for an Android app and poll the accumulated entries.
+
+start_log_stream starts a background adb logcat process filtered by the app PID. It returns immediately with success and creates a per-session NDJSON file of parsed log entries.
+
+read_log_stream retrieves recent parsed entries and includes crash detection metadata.
+
+Input (start_log_stream):
+```jsonc
+{
+  "packageName": "com.example.app", // Required
+  "level": "error" | "warn" | "info" | "debug", // Optional, defaults to "error"
+  "sessionId": "optional-session-id" // Optional - used to track stream per debugging session
+}
+```
+
+Input (read_log_stream):
+```jsonc
+{
+  "sessionId": "optional-session-id",
+  "limit": 100, // Optional, max number of entries to return (default 100)
+  "since": "2026-03-13T14:00:00Z" // Optional, ISO timestamp or epoch ms to return only newer entries
+}
+```
+
+Response (read_log_stream):
+```json
+{
+  "entries": [
+    { "timestamp": "2026-03-13T14:01:04.123Z", "level": "E", "tag": "AndroidRuntime", "message": "FATAL EXCEPTION: main", "crash": true, "exception": "NullPointerException" }
+  ],
+  "crash_summary": { "crash_detected": true, "exception": "NullPointerException", "sample": "FATAL EXCEPTION: main" }
+}
+```
+
+Notes:
+- The read_log_stream `since` parameter accepts ISO timestamps or epoch milliseconds. Use it to poll incrementally (pass last seen timestamp).
+- Crash detection is heuristic-based (looks for 'FATAL EXCEPTION' and Exception names). It helps agents decide to capture traces or stop tests quickly.
+- stop_log_stream stops the background adb process for the session.
+
+
 ### get_ui_tree
 Get the current UI hierarchy from the device. Returns a structured JSON representation of the screen content.
 
@@ -282,6 +365,150 @@ Get the currently visible activity on an Android device.
 }
 ```
 
+### wait_for_element
+Wait until a UI element with matching text appears on screen or timeout is reached. Useful for handling loading states or transitions.
+
+**Input:**
+```jsonc
+{
+  "platform": "android" | "ios",
+  "text": "Home", // Text to wait for
+  "timeout": 5000, // Max wait time in ms (default 10000)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "found": true,
+  "element": { /* UIElement object if found */ }
+}
+```
+
+If the element is not found within the timeout, `found` will be `false`. If a system error occurs (e.g., ADB failure), an `error` field will be present.
+
+```json
+{
+  "device": { /* device info */ },
+  "found": false,
+  "error": "Optional error message"
+}
+```
+
+### tap
+Simulate a finger tap on the device screen at specific coordinates.
+
+Platform support and constraints:
+- Android: Implemented via `adb shell input tap` and works when `adb` is available in PATH or configured via `ADB_PATH`.
+- iOS: Requires Facebook's `idb` tooling. The iOS implementation uses `idb` to deliver UI events and is simulator-oriented (works reliably on a booted simulator). Physical device support depends on `idb` capabilities and a running `idb_companion` on the target device; it may not work in all environments.
+
+Prerequisites for iOS (if you intend to use tap on iOS):
+```bash
+brew tap facebook/fb
+brew install idb-companion
+pip3 install fb-idb
+```
+Ensure `idb` and `idb_companion` are in your PATH. If you use non-standard tool locations, set `XCRUN_PATH` and/or `ADB_PATH` environment variables as appropriate.
+
+Behavior notes:
+- The tool is a primitive input: it only sends a tap at the provided coordinates. It does not inspect or interpret the UI.
+- If `idb` is missing or the simulator/device is not available, the tool will return an error explaining the failure.
+
+**Input:**
+```jsonc
+{
+  "platform": "android" | "ios", // Optional, defaults to "android"
+  "x": 200, // X coordinate (Required)
+  "y": 400, // Y coordinate (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "success": true,
+  "x": 200,
+  "y": 400
+}
+```
+
+If the tap fails (e.g., missing `adb`/`idb`, device not found), `success` will be `false` and an `error` field will be present.
+
+### swipe
+Simulate a swipe gesture on an Android device.
+
+**Input:**
+```jsonc
+{
+  "platform": "android", // Optional, defaults to "android"
+  "x1": 500, // Start X (Required)
+  "y1": 1500, // Start Y (Required)
+  "x2": 500, // End X (Required)
+  "y2": 500, // End Y (Required)
+  "duration": 300, // Duration in ms (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "success": true,
+  "start": [500, 1500],
+  "end": [500, 500],
+  "duration": 300
+}
+```
+
+If the swipe fails, `success` will be `false` and an `error` field will be present.
+
+### type_text
+Type text into the currently focused input field on an Android device.
+
+**Input:**
+```jsonc
+{
+  "platform": "android", // Optional, defaults to "android"
+  "text": "hello world", // Text to type (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "success": true,
+  "text": "hello world"
+}
+```
+
+If the command fails, `success` will be `false` and an `error` field will be present.
+
+### press_back
+Simulate pressing the Android Back button.
+
+**Input:**
+```jsonc
+{
+  "platform": "android", // Optional
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "success": true
+}
+```
+
 ---
 
 ## Recommended Workflow
@@ -290,8 +517,9 @@ Get the currently visible activity on an Android device.
 2. Use `start_app` to launch the app.
 3. Use `get_logs` to read the latest logs.
 4. Use `capture_screenshot` to visually inspect the app if needed.
-5. Use `reset_app_data` to clear state if debugging fresh install scenarios.
-6. Use `restart_app` to quickly reboot the app during development cycles.
+5. Use `wait_for_element` to ensure the app is in the expected state before proceeding (e.g., after login).
+6. Use `reset_app_data` to clear state if debugging fresh install scenarios.
+7. Use `restart_app` to quickly reboot the app during development cycles.
 
 ---
 

package/dist/android/interact.js

@@ -1,5 +1,92 @@
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js";
+import { AndroidObserve } from "./observe.js";
 export class AndroidInteract {
+    observe = new AndroidObserve();
+    async waitForElement(text, timeout, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            try {
+                const tree = await this.observe.getUITree(deviceId);
+                if (tree.error) {
+                    return { device: deviceInfo, found: false, error: tree.error };
+                }
+                const element = tree.elements.find(e => e.text === text);
+                if (element) {
+                    return { device: deviceInfo, found: true, element };
+                }
+            }
+            catch (e) {
+                // Ignore errors during polling and retry
+                console.error("Error polling UI tree:", e);
+            }
+            const elapsed = Date.now() - startTime;
+            const remaining = timeout - elapsed;
+            if (remaining <= 0)
+                break;
+            await new Promise(resolve => setTimeout(resolve, Math.min(500, remaining)));
+        }
+        return { device: deviceInfo, found: false };
+    }
+    async tap(x, y, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId);
+            return { device: deviceInfo, success: true, x, y };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async swipe(x1, y1, x2, y2, duration, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId);
+            return { device: deviceInfo, success: true, start: [x1, y1], end: [x2, y2], duration };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async typeText(text, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            // Encode spaces as %s to ensure proper input handling by adb shell input text
+            const encodedText = text.replace(/\s/g, '%s');
+            // Note: 'input text' might fail with some characters or if keyboard isn't ready, but it's the standard ADB way.
+            await execAdb(['shell', 'input', 'text', encodedText], deviceId);
+            return { device: deviceInfo, success: true, text };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, text, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async pressBack(deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'input', 'keyevent', '4'], deviceId);
+            return { device: deviceInfo, success: true };
+        }
+        catch (e) {
+            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);
+        try {
+            const output = await execAdb(['install', '-r', apkPath], deviceId);
+            return { device: deviceInfo, installed: true, output };
+        }
+        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);

package/dist/android/utils.js

@@ -67,16 +67,323 @@ export function getDeviceInfo(deviceId, metadata = {}) {
 }
 export async function getAndroidDeviceMetadata(appId, deviceId) {
     try {
+        // If no deviceId provided, try to auto-detect a single connected device
+        let resolvedDeviceId = deviceId;
+        if (!resolvedDeviceId) {
+            try {
+                const devicesOutput = await execAdb(['devices']);
+                // Parse lines like: "<serial>\tdevice"
+                const lines = devicesOutput.split('\n').map(l => l.trim()).filter(Boolean);
+                const deviceLines = lines.slice(1) // skip header
+                    .map(l => l.split('\t'))
+                    .filter(parts => parts.length >= 2 && parts[1] === 'device')
+                    .map(parts => parts[0]);
+                if (deviceLines.length === 1) {
+                    resolvedDeviceId = deviceLines[0];
+                }
+            }
+            catch (e) {
+                // ignore and continue without resolvedDeviceId
+            }
+        }
         // Run these in parallel to avoid sequential timeouts
         const [osVersion, model, simOutput] = await Promise.all([
-            execAdb(['shell', 'getprop', 'ro.build.version.release'], deviceId).catch(() => ''),
-            execAdb(['shell', 'getprop', 'ro.product.model'], deviceId).catch(() => ''),
-            execAdb(['shell', 'getprop', 'ro.kernel.qemu'], deviceId).catch(() => '0')
+            execAdb(['shell', 'getprop', 'ro.build.version.release'], resolvedDeviceId).catch(() => ''),
+            execAdb(['shell', 'getprop', 'ro.product.model'], resolvedDeviceId).catch(() => ''),
+            execAdb(['shell', 'getprop', 'ro.kernel.qemu'], resolvedDeviceId).catch(() => '0')
         ]);
         const simulator = simOutput === '1';
-        return { platform: 'android', id: deviceId || 'default', osVersion, model, simulator };
+        return { platform: 'android', id: resolvedDeviceId || 'default', osVersion, model, simulator };
     }
     catch (e) {
         return { platform: 'android', id: deviceId || 'default', osVersion: '', model: '', simulator: false };
     }
 }
+export async function listAndroidDevices(appId) {
+    try {
+        const devicesOutput = await execAdb(['devices', '-l']);
+        const lines = devicesOutput.split('\n').map(l => l.trim()).filter(Boolean);
+        // Skip header if present (some adb versions include 'List of devices attached')
+        const deviceLines = lines.filter(l => !l.startsWith('List of devices')).map(l => l);
+        const serials = deviceLines.map(line => line.split(/\s+/)[0]).filter(Boolean);
+        const infos = await Promise.all(serials.map(async (serial) => {
+            try {
+                const [osVersion, model, simOutput] = await Promise.all([
+                    execAdb(['shell', 'getprop', 'ro.build.version.release'], serial).catch(() => ''),
+                    execAdb(['shell', 'getprop', 'ro.product.model'], serial).catch(() => ''),
+                    execAdb(['shell', 'getprop', 'ro.kernel.qemu'], serial).catch(() => '0')
+                ]);
+                const simulator = simOutput === '1';
+                let appInstalled = false;
+                if (appId) {
+                    try {
+                        const pm = await execAdb(['shell', 'pm', 'path', appId], serial);
+                        appInstalled = !!(pm && pm.includes('package:'));
+                    }
+                    catch {
+                        appInstalled = false;
+                    }
+                }
+                return { platform: 'android', id: serial, osVersion, model, simulator, appInstalled };
+            }
+            catch {
+                return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false };
+            }
+        }));
+        return infos;
+    }
+    catch (e) {
+        return [];
+    }
+}
+// Log stream management (one stream per session)
+import { createWriteStream, promises as fsPromises } from 'fs';
+import path from 'path';
+const activeLogStreams = new Map();
+// Test helper to register a pre-existing NDJSON file as the active stream for a session (used by unit tests)
+export function _setActiveLogStream(sessionId, file) {
+    activeLogStreams.set(sessionId, { proc: { kill: () => { } }, file });
+}
+export function _clearActiveLogStream(sessionId) {
+    activeLogStreams.delete(sessionId);
+}
+// Robust log line parser supporting multiple logcat formats
+export function parseLogLine(line) {
+    // Collapse internal newlines so multiline stack traces are parseable as a single entry
+    const rawLine = line;
+    const normalizedLine = rawLine.replace(/\r?\n/g, ' ');
+    const entry = { timestamp: '', level: '', tag: '', message: rawLine, _iso: null, crash: false };
+    const nowYear = new Date().getFullYear();
+    const tryIso = (ts) => {
+        if (!ts)
+            return null;
+        // If it's already ISO
+        if (/^\d{4}-\d{2}-\d{2}T/.test(ts))
+            return ts;
+        // If format MM-DD HH:MM:SS(.sss)
+        const m = ts.match(/^(\d{2})-(\d{2})\s+(\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)$/);
+        if (m) {
+            const month = m[1];
+            const day = m[2];
+            const time = m[3];
+            const candidate = `${nowYear}-${month}-${day}T${time}`;
+            const d = new Date(candidate);
+            if (!isNaN(d.getTime()))
+                return d.toISOString();
+        }
+        // If format YYYY-MM-DD HH:MM:SS(.sss)
+        const m2 = ts.match(/^(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)$/);
+        if (m2) {
+            const candidate = `${m2[1]}T${m2[2]}`;
+            const d = new Date(candidate);
+            if (!isNaN(d.getTime()))
+                return d.toISOString();
+        }
+        return null;
+    };
+    // Patterns to try (ordered)
+    const patterns = [
+        // MM-DD HH:MM:SS.mmm PID TID LEVEL/Tag: msg
+        { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\/([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'tid', 'level', 'tag', 'msg'] },
+        // MM-DD HH:MM:SS.mmm PID TID LEVEL Tag: msg  (space between level and tag)
+        { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\s+([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'tid', 'level', 'tag', 'msg'] },
+        // YYYY-MM-DD full date with PID TID LEVEL/Tag
+        { re: /^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\/([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'tid', 'level', 'tag', 'msg'] },
+        // YYYY-MM-DD with space separation
+        { re: /^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\s+([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'tid', 'level', 'tag', 'msg'] },
+        // MM-DD PID LEVEL/Tag: msg
+        { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+([VDIWE])\/([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'level', 'tag', 'msg'] },
+        // MM-DD PID LEVEL Tag: msg (space)
+        { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+([VDIWE])\s+([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'level', 'tag', 'msg'] },
+        // Short form LEVEL/Tag: msg
+        { re: /^([VDIWE])\/([^\(\:]+)(?:\([0-9]+\))?:\s*(.*)$/, groups: ['level', 'tag', 'msg'] },
+        // Short form LEVEL Tag: msg
+        { re: /^([VDIWE])\s+([^\(\:]+)(?:\([0-9]+\))?:\s*(.*)$/, groups: ['level', 'tag', 'msg'] },
+    ];
+    for (const p of patterns) {
+        const m = normalizedLine.match(p.re);
+        if (m) {
+            const g = p.groups;
+            const vals = {};
+            for (let i = 0; i < g.length; i++)
+                vals[g[i]] = m[i + 1];
+            const ts = vals.ts;
+            if (ts) {
+                const iso = tryIso(ts);
+                if (iso) {
+                    entry.timestamp = ts;
+                    entry._iso = iso;
+                }
+                else {
+                    entry.timestamp = ts;
+                }
+            }
+            if (vals.level)
+                entry.level = vals.level;
+            if (vals.tag)
+                entry.tag = vals.tag.trim();
+            entry.message = vals.msg || entry.message;
+            // Crash heuristics
+            const msg = (entry.message || '').toString();
+            const crash = /FATAL EXCEPTION/i.test(msg) || /\b([A-Za-z0-9_$.]+Exception)\b/.test(msg);
+            if (crash) {
+                entry.crash = true;
+                const exMatch = msg.match(/\b([A-Za-z0-9_$.]+Exception)\b/);
+                if (exMatch)
+                    entry.exception = exMatch[1];
+            }
+            return entry;
+        }
+    }
+    // No pattern matched: attempt to extract level/tag like '... E/Tag: msg'
+    const alt = normalizedLine.match(/([VDIWE])\/([^:]+):\s*(.*)$/);
+    if (alt) {
+        entry.level = alt[1];
+        entry.tag = alt[2].trim();
+        entry.message = alt[3];
+        const msg = entry.message;
+        const crash = /FATAL EXCEPTION/i.test(msg) || /\b([A-Za-z0-9_$.]+Exception)\b/.test(msg);
+        if (crash) {
+            entry.crash = true;
+            const exMatch = msg.match(/\b([A-Za-z0-9_$.]+Exception)\b/);
+            if (exMatch)
+                entry.exception = exMatch[1];
+        }
+    }
+    return entry;
+}
+export async function startAndroidLogStream(packageName, level = 'error', deviceId, sessionId = 'default') {
+    try {
+        // Determine PID
+        const pidOutput = await execAdb(['shell', 'pidof', packageName], deviceId).catch(() => '');
+        const pid = (pidOutput || '').trim();
+        if (!pid) {
+            return { success: false, error: 'app_not_running' };
+        }
+        // Map level to logcat filter
+        const levelMap = { error: '*:E', warn: '*:W', info: '*:I', debug: '*:D' };
+        const filter = levelMap[level] || levelMap['error'];
+        // Prevent multiple streams per session
+        if (activeLogStreams.has(sessionId)) {
+            // stop existing
+            try {
+                activeLogStreams.get(sessionId).proc.kill();
+            }
+            catch (e) { }
+            activeLogStreams.delete(sessionId);
+        }
+        // Start logcat process
+        const args = ['logcat', `--pid=${pid}`, filter];
+        const proc = spawn(ADB, args);
+        // Prepare output file
+        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) => {
+            // write stderr lines as message with level 'E'
+            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', (code) => {
+            stream.end();
+            activeLogStreams.delete(sessionId);
+        });
+        activeLogStreams.set(sessionId, { proc, file });
+        return { success: true, stream_started: true };
+    }
+    catch (err) {
+        return { success: false, error: 'log_stream_start_failed' };
+    }
+}
+export async function stopAndroidLogStream(sessionId = 'default') {
+    const entry = activeLogStreams.get(sessionId);
+    if (!entry)
+        return { success: true };
+    try {
+        entry.proc.kill();
+    }
+    catch (e) { }
+    activeLogStreams.delete(sessionId);
+    return { success: true };
+}
+export async function readLogStreamLines(sessionId = 'default', limit = 100, since) {
+    const entry = activeLogStreams.get(sessionId);
+    if (!entry)
+        return { entries: [] };
+    try {
+        const data = await fsPromises.readFile(entry.file, 'utf8').catch(() => '');
+        if (!data)
+            return { entries: [], crash_summary: { crash_detected: false } };
+        const lines = data.split(/\r?\n/).filter(Boolean);
+        // Parse NDJSON lines into objects. Prefer fields written by parseLogLine. For backward compatibility, if _iso or crash are missing, enrich minimally here (avoid duplicating full parse logic).
+        const parsed = lines.map(l => {
+            try {
+                const obj = JSON.parse(l);
+                // Ensure _iso: if missing, try to derive using Date()
+                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;
+                }
+                // Ensure crash flag: if missing, run minimal heuristic
+                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 };
+            }
+        });
+        // Filter by since if provided (accept ISO or epoch ms)
+        let filtered = parsed;
+        if (since) {
+            let sinceMs = null;
+            // If numeric string
+            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));
+            }
+        }
+        // Return the last `limit` entries (most recent)
+        const entries = filtered.slice(-Math.max(0, limit));
+        // Crash summary
+        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 (e) {
+        return { entries: [], crash_summary: { crash_detected: false } };
+    }
+}