mobile-debug-mcp 0.21.2 → 0.21.3

package/dist/interact/index.js

@@ -219,6 +219,23 @@ export class ToolsInteract {
         // Backwards-compatible wrapper that delegates to the core waitForUICore implementation
         return await ToolsInteract.waitForUICore({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId });
     }
+    // Helper: normalize various log objects into plain message strings for comparison
+    static _logsToMessages(logsArr) {
+        if (!Array.isArray(logsArr))
+            return [];
+        return logsArr.map((l) => {
+            if (typeof l === 'string')
+                return l;
+            if (l && (l.message || l.msg))
+                return l.message || l.msg;
+            try {
+                return JSON.stringify(l);
+            }
+            catch {
+                return String(l);
+            }
+        });
+    }
     static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }) {
         const start = Date.now();
         let lastFingerprint = null;
@@ -275,7 +292,9 @@ export class ToolsInteract {
                 initialFingerprint = fpRes.fingerprint ?? null;
             if (gl) {
                 const logsArr = Array.isArray(gl.logs) ? gl.logs : [];
-                baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null;
+                // Normalize to last message string for baseline comparison
+                const msgs = ToolsInteract._logsToMessages(logsArr);
+                baselineLastLine = msgs.length ? msgs[msgs.length - 1] : null;
             }
         }
         catch (err) {
@@ -354,13 +373,15 @@ export class ToolsInteract {
                     }
                     const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
                     const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : [];
+                    // Normalize to messages for comparison
+                    const msgs = ToolsInteract._logsToMessages(logsArr);
                     let startIndex = 0;
                     if (baselineLastLine) {
-                        const idx = logsArr.lastIndexOf(baselineLastLine);
+                        const idx = msgs.lastIndexOf(baselineLastLine);
                         startIndex = idx >= 0 ? idx + 1 : 0;
                     }
-                    for (let i = startIndex; i < logsArr.length; i++) {
-                        const line = logsArr[i];
+                    for (let i = startIndex; i < msgs.length; i++) {
+                        const line = msgs[i];
                         if (q && String(line).includes(q)) {
                             const now2 = Date.now();
                             return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: line }, matchSource: 'log-snapshot', timestamp: now2, type: 'log', observed_state: true };

package/dist/observe/android.js

@@ -80,23 +80,98 @@ export class AndroidObserve {
             };
         }
     }
-    async getLogs(appId, lines = 200, deviceId) {
+    async getLogs(filters = {}) {
+        const { appId, deviceId, pid, tag, level, contains, since_seconds, limit } = filters;
         const metadata = await getAndroidDeviceMetadata(appId || "", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            const stdout = await execAdb(['logcat', '-d', '-t', lines.toString(), '-v', 'threadtime'], deviceId);
-            const allLogs = stdout.split('\n');
-            let filteredLogs = allLogs;
+            const effectiveLimit = typeof limit === 'number' && limit > 0 ? limit : 50;
+            // If appId provided, try to get pid to filter at source
+            let pidArg = null;
             if (appId) {
-                const matchingLogs = allLogs.filter(line => line.includes(appId));
-                if (matchingLogs.length > 0) {
-                    filteredLogs = matchingLogs;
+                try {
+                    const pidOut = await execAdb(['shell', 'pidof', appId], deviceId).catch(() => '');
+                    const pidTrim = (pidOut || '').trim();
+                    if (pidTrim)
+                        pidArg = pidTrim.split('\n')[0];
                 }
-                else {
-                    filteredLogs = allLogs;
+                catch (err) {
+                    // Log a warning so failures to detect PID are visible during debugging
+                    try {
+                        console.warn(`getLogs: pid detection failed for appId=${appId}:`, err instanceof Error ? err.message : String(err));
+                    }
+                    catch { }
                 }
             }
-            return { device: deviceInfo, logs: filteredLogs, logCount: filteredLogs.length };
+            const args = ['logcat', '-d', '-v', 'threadtime'];
+            // Apply pid filter via --pid if available
+            if (pidArg)
+                args.push(`--pid=${pidArg}`);
+            else if (pid)
+                args.push(`--pid=${pid}`);
+            // Apply tag/level filter if provided
+            if (tag && level) {
+                // Map verbose/debug/info/warn/error to single-letter levels
+                const levelMap = { 'VERBOSE': 'V', 'DEBUG': 'D', 'INFO': 'I', 'WARN': 'W', 'ERROR': 'E' };
+                const L = (levelMap[(level || '').toUpperCase()] || 'V');
+                args.push(`${tag}:${L}`);
+            }
+            else {
+                // Default: show all levels
+                args.push('*:V');
+            }
+            // Use -t to limit lines (apply early)
+            args.push('-t', effectiveLimit.toString());
+            const stdout = await execAdb(args, deviceId);
+            const allLines = stdout ? stdout.split(/\r?\n/).filter(Boolean) : [];
+            // Parse lines into structured entries
+            const parsed = allLines.map(l => {
+                const entry = parseLogLine(l);
+                // normalize level
+                const levelChar = (entry.level || '').toUpperCase();
+                const levelMapChar = { 'V': 'VERBOSE', 'D': 'DEBUG', 'I': 'INFO', 'W': 'WARN', 'E': 'ERROR' };
+                const normLevel = levelMapChar[levelChar] || (entry.level && String(entry.level).toUpperCase()) || 'INFO';
+                const iso = entry._iso || (() => {
+                    const d = new Date(entry.timestamp || '');
+                    if (!isNaN(d.getTime()))
+                        return d.toISOString();
+                    return null;
+                })();
+                let pidNum = null;
+                if (entry.pid)
+                    pidNum = Number(entry.pid);
+                else if (pidArg)
+                    pidNum = Number(pidArg);
+                const pidVal = (pidNum !== null && !isNaN(pidNum)) ? pidNum : null;
+                return { timestamp: iso, level: normLevel, tag: entry.tag || '', pid: pidVal, message: entry.message || '' };
+            });
+            // Apply client-side filters: contains, since_seconds
+            let filtered = parsed;
+            if (contains)
+                filtered = filtered.filter(e => e.message && e.message.includes(contains));
+            if (since_seconds) {
+                const sinceMs = Date.now() - (since_seconds * 1000);
+                filtered = filtered.filter(e => {
+                    if (!e.timestamp)
+                        return false;
+                    const t = new Date(e.timestamp).getTime();
+                    return t >= sinceMs;
+                });
+            }
+            // If appId provided and no pidArg, try to filter by appId substring in message/tag
+            if (appId && !pidArg) {
+                const matched = filtered.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)));
+                if (matched.length > 0)
+                    filtered = matched;
+            }
+            // Ensure ordering oldest -> newest (by timestamp when available)
+            filtered.sort((a, b) => {
+                const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0;
+                const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0;
+                return ta - tb;
+            });
+            const limited = filtered.slice(-Math.max(0, effectiveLimit));
+            return { device: deviceInfo, logs: limited, logCount: limited.length };
         }
         catch (e) {
             console.error("Error fetching logs:", e);

package/dist/observe/index.js

@@ -33,19 +33,30 @@ export class ToolsObserve {
         // getCurrentScreen is Android-specific
         return await observe.getCurrentScreen(resolved.id);
     }
-    static async getLogsHandler({ platform, appId, deviceId, lines }) {
+    static async getLogsHandler({ platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines }) {
         const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId, appId);
+        const filters = { appId, deviceId: resolved.id, pid, tag, level, contains, since_seconds, limit: limit ?? lines };
+        // Validate filters
+        if (level && !['VERBOSE', 'DEBUG', 'INFO', 'WARN', 'ERROR'].includes(level.toString().toUpperCase())) {
+            return { device: resolved, logs: [], crashLines: [], logCount: 0, error: { code: 'INVALID_FILTER', message: `Unsupported level filter: ${level}` } };
+        }
         if (observe instanceof AndroidObserve) {
-            const response = await observe.getLogs(appId, lines ?? 200, resolved.id);
+            const response = await observe.getLogs(filters);
             const logs = Array.isArray(response.logs) ? response.logs : [];
-            const crashLines = logs.filter(line => line.includes('FATAL EXCEPTION'));
-            return { device: response.device, logs, crashLines };
+            const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message));
+            const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds);
+            if (anyFilterApplied && logs.length === 0)
+                return { device: response.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } };
+            return { device: response.device, logs, crashLines, logCount: response.logCount };
         }
         else {
-            const resp = await observe.getLogs(appId, resolved.id);
+            const resp = await observe.getLogs(filters);
             const logs = Array.isArray(resp.logs) ? resp.logs : [];
-            const crashLines = logs.filter(l => l.includes('FATAL EXCEPTION'));
-            return { device: resp.device, logs, crashLines };
+            const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message));
+            const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds);
+            if (anyFilterApplied && logs.length === 0)
+                return { device: resp.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } };
+            return { device: resp.device, logs, crashLines, logCount: resp.logCount };
         }
     }
     static async startLogStreamHandler({ platform, packageName, level, sessionId, deviceId }) {
@@ -154,9 +165,20 @@ export class ToolsObserve {
                 if (!entries || entries.length === 0) {
                     const gl = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines: logLines });
                     const raw = (gl && gl.logs) ? gl.logs : [];
-                    entries = raw.slice(-Math.max(0, logLines)).map(line => {
-                        const level = /\b(FATAL EXCEPTION|ERROR| E )\b/i.test(line) ? 'ERROR' : /\b(WARN| W )\b/i.test(line) ? 'WARN' : 'INFO';
-                        return { timestamp: null, level, message: line };
+                    // raw may be structured entries or strings
+                    entries = raw.slice(-Math.max(0, logLines)).map(item => {
+                        if (!item)
+                            return { timestamp: null, level: 'INFO', message: '' };
+                        if (typeof item === 'string') {
+                            const level = /\b(FATAL EXCEPTION|ERROR| E )\b/i.test(item) ? 'ERROR' : /\b(WARN| W )\b/i.test(item) ? 'WARN' : 'INFO';
+                            return { timestamp: null, level, message: item };
+                        }
+                        const msg = item.message || item.msg || JSON.stringify(item);
+                        const levelRaw = item.level || item.levelName || item._level || '';
+                        const level = (levelRaw && String(levelRaw)).toUpperCase() || (/\bERROR\b/i.test(msg) ? 'ERROR' : /\bWARN\b/i.test(msg) ? 'WARN' : 'INFO');
+                        const ts = item.timestamp || item._iso || null;
+                        const tsNum = (ts && typeof ts === 'string') ? (isNaN(new Date(ts).getTime()) ? null : new Date(ts).getTime()) : (typeof ts === 'number' ? ts : null);
+                        return { timestamp: tsNum, level, message: msg };
                     });
                 }
                 else {

package/dist/observe/ios.js

@@ -88,20 +88,128 @@ export class iOSObserve {
     async getDeviceMetadata(deviceId = "booted") {
         return getIOSDeviceMetadata(deviceId);
     }
-    async getLogs(appId, deviceId = "booted") {
-        const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog', '--last', '1m'];
+    async getLogs(filters = {}) {
+        const { appId, deviceId = 'booted', pid, tag, level, contains, since_seconds, limit } = filters;
+        const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog'];
+        // Default to last N seconds if no since_seconds provided; limit lines handled after parsing
+        const effectiveLimit = typeof limit === 'number' && limit > 0 ? limit : 50;
+        if (since_seconds) {
+            // log show accepts --last <time>
+            args.push('--last', `${since_seconds}s`);
+        }
+        else {
+            // default to last 60s to keep quick
+            args.push('--last', '60s');
+        }
         if (appId) {
             validateBundleId(appId);
+            // constrain to subsystem or process matching appId
             args.push('--predicate', `subsystem contains "${appId}" or process == "${appId}"`);
         }
-        const result = await execCommand(args, deviceId);
-        const device = await getIOSDeviceMetadata(deviceId);
-        const logs = result.output ? result.output.split('\n') : [];
-        return {
-            device,
-            logs,
-            logCount: logs.length,
-        };
+        else if (tag) {
+            // predicate by subsystem/category
+            args.push('--predicate', `subsystem contains "${tag}"`);
+        }
+        try {
+            const result = await execCommand(args, deviceId);
+            const device = await getIOSDeviceMetadata(deviceId);
+            const rawLines = result.output ? result.output.split(/\r?\n/).filter(Boolean) : [];
+            // Parse lines into structured entries. iOS log format: timestamp [PID:tid] <level> subsystem:category: message
+            const parsed = rawLines.map(line => {
+                // Example: 2023-08-12 12:34:56.789012+0000  pid  <Debug>  MyApp[123:456]  <info>  MySubsystem: MyCategory: Message here
+                // Simpler approach: try to extract ISO timestamp at start
+                let ts = null;
+                const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d+)?)/);
+                if (tsMatch) {
+                    const d = new Date(tsMatch[1]);
+                    if (!isNaN(d.getTime()))
+                        ts = d.toISOString();
+                }
+                // level mapping
+                let lvl = 'INFO';
+                const lvlMatch = line.match(/\b(Debug|Info|Default|Error|Fault|Warning)\b/i);
+                if (lvlMatch) {
+                    const map = { 'debug': 'DEBUG', 'info': 'INFO', 'default': 'DEBUG', 'error': 'ERROR', 'fault': 'ERROR', 'warning': 'WARN' };
+                    lvl = map[(lvlMatch[1] || '').toLowerCase()] || 'INFO';
+                }
+                // subsystem/category -> tag
+                let tagVal = '';
+                const tagMatch = line.match(/\s([A-Za-z0-9_./-]+):\s/);
+                if (tagMatch)
+                    tagVal = tagMatch[1];
+                // pid extraction
+                let pidNum = null;
+                const pidMatch = line.match(/\[(\d+):\d+\]/);
+                if (pidMatch)
+                    pidNum = Number(pidMatch[1]);
+                // message: extract robustly after the subsystem/category token when available
+                let message = line;
+                if (tagMatch) {
+                    // tagMatch[0] includes the delimiter (e.g. " MySubsystem: ") — use it to find the message start
+                    const marker = tagMatch[0];
+                    const idx = line.indexOf(marker);
+                    if (idx !== -1) {
+                        message = line.slice(idx + marker.length).trim();
+                    }
+                    else {
+                        // fallback: try to trim off common prefixes (timestamp, pid, level) and keep the rest
+                        const afterPidMatch = line.match(/\]\s+/);
+                        if (afterPidMatch) {
+                            const afterPidIdx = line.indexOf(afterPidMatch[0]) + afterPidMatch[0].length;
+                            message = line.slice(afterPidIdx).trim();
+                        }
+                        else {
+                            // remove leading level tokens like <Debug> and keep remainder
+                            message = line.replace(/^.*?<.*?>\s*/, '').trim();
+                        }
+                    }
+                }
+                else {
+                    // No tag found — strip obvious prefixes and keep remainder (preserve colons in message)
+                    message = line.replace(/^.*?<.*?>\s*/, '').trim();
+                }
+                return { timestamp: ts, level: lvl, tag: tagVal, pid: pidNum, message };
+            });
+            // Apply contains filter
+            let filtered = parsed;
+            if (contains)
+                filtered = filtered.filter(e => e.message && e.message.includes(contains));
+            // Apply since_seconds already applied by log show, but double-check timestamps
+            if (since_seconds) {
+                const sinceMs = Date.now() - (since_seconds * 1000);
+                filtered = filtered.filter(e => e.timestamp && (new Date(e.timestamp).getTime() >= sinceMs));
+            }
+            // level filter
+            if (level) {
+                const L = level.toUpperCase();
+                filtered = filtered.filter(e => e.level && e.level.toUpperCase() === L);
+            }
+            // tag filter
+            if (tag)
+                filtered = filtered.filter(e => e.tag && e.tag.includes(tag));
+            // pid filter
+            if (pid)
+                filtered = filtered.filter(e => e.pid === pid);
+            // If appId present but no predicate returned lines, try substring match
+            if (appId && filtered.length === 0) {
+                const matched = parsed.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)));
+                if (matched.length > 0)
+                    filtered = matched;
+            }
+            // Order oldest -> newest
+            filtered.sort((a, b) => {
+                const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0;
+                const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0;
+                return ta - tb;
+            });
+            const limited = filtered.slice(-Math.max(0, effectiveLimit));
+            return { device, logs: limited, logCount: limited.length };
+        }
+        catch (err) {
+            console.error('iOS getLogs failed:', err);
+            const device = await getIOSDeviceMetadata(deviceId);
+            return { device, logs: [], logCount: 0 };
+        }
     }
     async captureScreenshot(deviceId = "booted") {
         const device = await getIOSDeviceMetadata(deviceId);

package/dist/server.js

@@ -148,7 +148,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "get_logs",
-            description: "Get recent logs from Android or iOS simulator. Returns device metadata and the log output.",
+            description: "Get recent logs from Android or iOS simulator. Returns device metadata and structured logs suitable for AI consumption.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -164,9 +164,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         type: "string",
                         description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected."
                     },
+                    pid: { type: "number", description: "Filter by process id" },
+                    tag: { type: "string", description: "Filter by tag (Android) or subsystem/category (iOS)" },
+                    level: { type: "string", description: "Log level filter (VERBOSE, DEBUG, INFO, WARN, ERROR)" },
+                    contains: { type: "string", description: "Substring to match in log message" },
+                    since_seconds: { type: "number", description: "Only return logs from the last N seconds" },
+                    limit: { type: "number", description: "Override default number of returned lines" },
                     lines: {
                         type: "number",
-                        description: "Number of log lines (android only)"
+                        description: "Legacy - number of log lines (android only)"
                     }
                 },
                 required: ["platform"]
@@ -563,12 +569,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
         if (name === "get_logs") {
-            const { platform, appId, deviceId, lines } = args;
-            const res = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines });
+            const { platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines } = args;
+            const res = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines });
+            const filtered = !!(pid || tag || level || contains || since_seconds || appId);
             return {
                 content: [
-                    { type: 'text', text: JSON.stringify({ device: res.device, result: { lines: res.logs.length, crashLines: res.crashLines.length > 0 ? res.crashLines : undefined } }, null, 2) },
-                    { type: 'text', text: (res.logs || []).join('\n') }
+                    { type: 'text', text: JSON.stringify({ device: res.device, result: { count: res.logCount, filtered, crashLines: (res.crashLines || []) } }, null, 2) },
+                    { type: 'text', text: JSON.stringify({ logs: res.logs }, null, 2) }
                 ]
             };
         }

package/dist/utils/cli/ios/run-ios-smoke.js

@@ -13,7 +13,7 @@ async function main() {
         const shot = await obs.captureScreenshot(deviceId);
         console.log('screenshot OK? size:', shot && shot.screenshot ? shot.screenshot.length : 0);
         console.log('[3] getLogs');
-        const logs = await obs.getLogs(appId, undefined);
+        const logs = await obs.getLogs({ appId, deviceId });
         console.log('logs count:', logs.logCount);
         console.log('[4] terminateApp');
         const term = await manage.terminateApp(appId, deviceId);

package/docs/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.21.3]
+- Added structured logs
+
 ## [0.21.2]
 - Fixed screenshots not working, imnproved tool
 

package/docs/tools/observe.md

@@ -3,27 +3,32 @@
 Tools that retrieve device state, logs, screenshots and UI hierarchies.
 
 ## get_logs
-Fetch recent logs from the app or device.
 
-Input:
+Fetch recent logs as structured entries optimized for AI agents.
+
+Input (example):
 
 ```json
-{ "platform": "android", "appId": "com.example.app", "deviceId": "emulator-5554", "lines": 200 }
+{ "platform": "android|ios", "appId": "com.example.app", "deviceId": "emulator-5554", "pid": 1234, "tag": "MyTag", "level": "ERROR", "contains": "timeout", "since_seconds": 60, "limit": 50 }
 ```
 
-Response (metadata):
+Defaults:
+
+- No filters → return the most recent 50 log entries (app-scoped if appId provided), across all levels.
+
+Response (structured):
 
 ```json
-{ "entries": 200, "crash_summary": { "crash_detected": false } }
+{ "device": { "platform": "android", "id": "emulator-5554" }, "logs": [ { "timestamp": "2026-03-30T16:00:00.000Z", "level": "ERROR", "tag": "MyTag", "pid": 1234, "message": "Something failed" } ], "count": 1, "filtered": true }
 ```
 
-Followed by a raw log plain text block.
-
 Notes:
-- Android log parsing includes basic crash detection (searching for "FATAL EXCEPTION" and exception names).
-- Use `lines` to control how many log lines are returned from `adb logcat`.
 
----
+- Each log entry: timestamp (ISO), level (VERBOSE|DEBUG|INFO|WARN|ERROR), tag (string), pid (number|null), message (string).
+- Logs ordered oldest → newest. count equals number of entries returned. filtered is true if any filter was applied.
+- Supported filters: pid, tag, level, contains, since_seconds, limit.
+- Platform behaviour: Android uses `adb logcat` with source-side filters where possible; iOS uses unified logging (`log show`/simctl) and maps subsystem/category → tag.
+- Errors are returned as structured objects with `error.code` and `error.message`. Possible codes: LOGS_UNAVAILABLE, INVALID_FILTER, PLATFORM_NOT_SUPPORTED, INTERNAL_ERROR.
 
 ## capture_screenshot
 Capture screen. Returns JSON metadata then an image/png block with base64 PNG data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.21.2",
+  "version": "0.21.3",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/interact/index.ts

@@ -223,6 +223,16 @@ export class ToolsInteract {
     return await ToolsInteract.waitForUICore({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId })
   }
 
+  // Helper: normalize various log objects into plain message strings for comparison
+  private static _logsToMessages(logsArr: any[]): string[] {
+    if (!Array.isArray(logsArr)) return []
+    return logsArr.map((l: any) => {
+      if (typeof l === 'string') return l
+      if (l && (l.message || l.msg)) return l.message || l.msg
+      try { return JSON.stringify(l) } catch { return String(l) }
+    })
+  }
+
   static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }: { platform?: 'android' | 'ios', previousFingerprint: string, timeoutMs?: number, pollIntervalMs?: number, deviceId?: string }) {
     const start = Date.now()
     let lastFingerprint: string | null = null
@@ -279,7 +289,9 @@ export class ToolsInteract {
       if (fpRes && typeof fpRes === 'object') initialFingerprint = (fpRes as ScreenFingerprintResponse).fingerprint ?? null
       if (gl) {
         const logsArr = Array.isArray((gl as any).logs) ? (gl as any).logs : []
-        baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null
+        // Normalize to last message string for baseline comparison
+        const msgs = ToolsInteract._logsToMessages(logsArr)
+        baselineLastLine = msgs.length ? msgs[msgs.length - 1] : null
       }
     } catch (err) {
       try { console.warn('waitForUI: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err)) } catch { }
@@ -348,13 +360,15 @@ export class ToolsInteract {
 
             const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 }) as any
             const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : []
+            // Normalize to messages for comparison
+            const msgs = ToolsInteract._logsToMessages(logsArr)
             let startIndex = 0
             if (baselineLastLine) {
-              const idx = logsArr.lastIndexOf(baselineLastLine)
+              const idx = msgs.lastIndexOf(baselineLastLine)
               startIndex = idx >= 0 ? idx + 1 : 0
             }
-            for (let i = startIndex; i < logsArr.length; i++) {
-              const line = logsArr[i]
+            for (let i = startIndex; i < msgs.length; i++) {
+              const line = msgs[i]
               if (q && String(line).includes(q)) {
                 const now2 = Date.now()
                 return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: line }, matchSource: 'log-snapshot', timestamp: now2, type: 'log', observed_state: true }

package/src/observe/android.ts

@@ -93,26 +93,97 @@ export class AndroidObserve {
     }
   }
 
-  async getLogs(appId?: string, lines = 200, deviceId?: string): Promise<GetLogsResponse> {
+  async getLogs(filters: { appId?: string, deviceId?: string, pid?: number, tag?: string, level?: string, contains?: string, since_seconds?: number, limit?: number } = {}): Promise<GetLogsResponse> {
+    const { appId, deviceId, pid, tag, level, contains, since_seconds, limit } = filters
     const metadata = await getAndroidDeviceMetadata(appId || "", deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
     try {
-      const stdout = await execAdb(['logcat', '-d', '-t', lines.toString(), '-v', 'threadtime'], deviceId)
-      const allLogs = stdout.split('\n')
-      
-      let filteredLogs = allLogs
+      const effectiveLimit = typeof limit === 'number' && limit > 0 ? limit : 50
+
+      // If appId provided, try to get pid to filter at source
+      let pidArg: string | null = null
       if (appId) {
-         const matchingLogs = allLogs.filter(line => line.includes(appId))
-         
-         if (matchingLogs.length > 0) {
-           filteredLogs = matchingLogs
-         } else {
-           filteredLogs = allLogs
-         }
+        try {
+          const pidOut = await execAdb(['shell', 'pidof', appId], deviceId).catch(() => '')
+          const pidTrim = (pidOut || '').trim()
+          if (pidTrim) pidArg = pidTrim.split('\n')[0]
+        } catch (err) {
+          // Log a warning so failures to detect PID are visible during debugging
+          try { console.warn(`getLogs: pid detection failed for appId=${appId}:`, err instanceof Error ? err.message : String(err)) } catch { }
+        }
       }
-      
-      return { device: deviceInfo, logs: filteredLogs, logCount: filteredLogs.length }
+
+      const args = ['logcat', '-d', '-v', 'threadtime']
+      // Apply pid filter via --pid if available
+      if (pidArg) args.push(`--pid=${pidArg}`)
+      else if (pid) args.push(`--pid=${pid}`)
+
+      // Apply tag/level filter if provided
+      if (tag && level) {
+        // Map verbose/debug/info/warn/error to single-letter levels
+        const levelMap: Record<string, string> = { 'VERBOSE': 'V', 'DEBUG': 'D', 'INFO': 'I', 'WARN': 'W', 'ERROR': 'E' }
+        const L = (levelMap[(level || '').toUpperCase()] || 'V')
+        args.push(`${tag}:${L}`)
+      } else {
+        // Default: show all levels
+        args.push('*:V')
+      }
+
+      // Use -t to limit lines (apply early)
+      args.push('-t', effectiveLimit.toString())
+
+      const stdout = await execAdb(args, deviceId)
+      const allLines = stdout ? stdout.split(/\r?\n/).filter(Boolean) : []
+
+      // Parse lines into structured entries
+      const parsed = allLines.map(l => {
+        const entry = parseLogLine(l)
+        // normalize level
+        const levelChar = (entry.level || '').toUpperCase()
+        const levelMapChar: Record<string,string> = { 'V':'VERBOSE','D':'DEBUG','I':'INFO','W':'WARN','E':'ERROR' }
+        const normLevel = levelMapChar[levelChar] || (entry.level && String(entry.level).toUpperCase()) || 'INFO'
+        const iso = entry._iso || (() => {
+          const d = new Date(entry.timestamp || '')
+          if (!isNaN(d.getTime())) return d.toISOString()
+          return null
+        })()
+        let pidNum: number | null = null
+        if (entry.pid) pidNum = Number(entry.pid)
+        else if (pidArg) pidNum = Number(pidArg)
+        const pidVal = (pidNum !== null && !isNaN(pidNum)) ? pidNum : null
+        return { timestamp: iso, level: normLevel, tag: entry.tag || '', pid: pidVal, message: entry.message || '' }
+      })
+
+      // Apply client-side filters: contains, since_seconds
+      let filtered = parsed
+      if (contains) filtered = filtered.filter(e => e.message && e.message.includes(contains))
+
+      if (since_seconds) {
+        const sinceMs = Date.now() - (since_seconds * 1000)
+        filtered = filtered.filter(e => {
+          if (!e.timestamp) return false
+          const t = new Date(e.timestamp).getTime()
+          return t >= sinceMs
+        })
+      }
+
+      // If appId provided and no pidArg, try to filter by appId substring in message/tag
+      if (appId && !pidArg) {
+        const matched = filtered.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)))
+        if (matched.length > 0) filtered = matched
+      }
+
+      // Ensure ordering oldest -> newest (by timestamp when available)
+      filtered.sort((a,b) => {
+        const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0
+        const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0
+        return ta - tb
+      })
+
+      const limited = filtered.slice(-Math.max(0, effectiveLimit))
+
+      return { device: deviceInfo, logs: limited, logCount: limited.length }
     } catch (e) {
       console.error("Error fetching logs:", e)
       return { device: deviceInfo, logs: [], logCount: 0 }

package/src/observe/index.ts

@@ -38,18 +38,29 @@ export class ToolsObserve {
     return await (observe as AndroidObserve).getCurrentScreen(resolved.id)
   }
 
-  static async getLogsHandler({ platform, appId, deviceId, lines }: { platform?: 'android' | 'ios', appId?: string, deviceId?: string, lines?: number }) {
+  static async getLogsHandler({ platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines }: { platform?: 'android' | 'ios', appId?: string, deviceId?: string, pid?: number, tag?: string, level?: string, contains?: string, since_seconds?: number, limit?: number, lines?: number }) {
     const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId, appId)
+    const filters = { appId, deviceId: resolved.id, pid, tag, level, contains, since_seconds, limit: limit ?? lines }
+
+    // Validate filters
+    if (level && !['VERBOSE','DEBUG','INFO','WARN','ERROR'].includes(level.toString().toUpperCase())) {
+      return { device: resolved, logs: [], crashLines: [], logCount: 0, error: { code: 'INVALID_FILTER', message: `Unsupported level filter: ${level}` } } as any
+    }
+
     if (observe instanceof AndroidObserve) {
-      const response = await observe.getLogs(appId, lines ?? 200, resolved.id)
+      const response = await observe.getLogs(filters)
       const logs = Array.isArray(response.logs) ? response.logs : []
-      const crashLines = logs.filter(line => line.includes('FATAL EXCEPTION'))
-      return { device: response.device, logs, crashLines }
+      const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message))
+      const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds)
+      if (anyFilterApplied && logs.length === 0) return { device: response.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
+      return { device: response.device, logs, crashLines, logCount: response.logCount }
     } else {
-      const resp = await (observe as iOSObserve).getLogs(appId, resolved.id)
+      const resp = await (observe as iOSObserve).getLogs(filters)
       const logs = Array.isArray(resp.logs) ? resp.logs : []
-      const crashLines = logs.filter(l => l.includes('FATAL EXCEPTION'))
-      return { device: resp.device, logs, crashLines }
+      const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message))
+      const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds)
+      if (anyFilterApplied && logs.length === 0) return { device: resp.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
+      return { device: resp.device, logs, crashLines, logCount: resp.logCount }
     }
   }
 
@@ -96,7 +107,7 @@ export class ToolsObserve {
 
     // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
     const sid = sessionId || 'default'
-    const tasks = {
+    const tasks: Record<string, Promise<any>> = {
       screenshot: ToolsObserve.captureScreenshotHandler({ platform, deviceId }),
       currentScreen: (!platform || platform === 'android') ? ToolsObserve.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
       fingerprint: ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }),
@@ -145,10 +156,20 @@ export class ToolsObserve {
         let entries: any[] = Array.isArray(out._streamEntries) ? out._streamEntries : []
         if (!entries || entries.length === 0) {
           const gl = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines: logLines })
-          const raw: string[] = (gl && (gl as any).logs) ? (gl as any).logs : []
-          entries = raw.slice(-Math.max(0, logLines)).map(line => {
-            const level = /\b(FATAL EXCEPTION|ERROR| E )\b/i.test(line) ? 'ERROR' : /\b(WARN| W )\b/i.test(line) ? 'WARN' : 'INFO'
-            return { timestamp: null, level, message: line }
+          const raw: any[] = (gl && (gl as any).logs) ? (gl as any).logs : []
+          // raw may be structured entries or strings
+          entries = raw.slice(-Math.max(0, logLines)).map(item => {
+            if (!item) return { timestamp: null, level: 'INFO', message: '' }
+            if (typeof item === 'string') {
+              const level = /\b(FATAL EXCEPTION|ERROR| E )\b/i.test(item) ? 'ERROR' : /\b(WARN| W )\b/i.test(item) ? 'WARN' : 'INFO'
+              return { timestamp: null, level, message: item }
+            }
+            const msg = item.message || item.msg || JSON.stringify(item)
+            const levelRaw = item.level || item.levelName || item._level || ''
+            const level = (levelRaw && String(levelRaw)).toUpperCase() || (/\bERROR\b/i.test(msg) ? 'ERROR' : /\bWARN\b/i.test(msg) ? 'WARN' : 'INFO')
+            const ts = item.timestamp || item._iso || null
+            const tsNum = (ts && typeof ts === 'string') ? (isNaN(new Date(ts).getTime()) ? null : new Date(ts).getTime()) : (typeof ts === 'number' ? ts : null)
+            return { timestamp: tsNum, level, message: msg }
           })
         } else {
           entries = entries.map(ent => {

package/src/observe/ios.ts

@@ -121,20 +121,132 @@ export class iOSObserve {
     return getIOSDeviceMetadata(deviceId);
   }
 
-  async getLogs(appId?: string, deviceId: string = "booted"): Promise<GetLogsResponse> {
-    const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog', '--last', '1m']
+  async getLogs(filters: { appId?: string, deviceId?: string, pid?: number, tag?: string, level?: string, contains?: string, since_seconds?: number, limit?: number } = {}): Promise<GetLogsResponse> {
+    const { appId, deviceId = 'booted', pid, tag, level, contains, since_seconds, limit } = filters
+    const args: string[] = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog']
+
+    // Default to last N seconds if no since_seconds provided; limit lines handled after parsing
+    const effectiveLimit = typeof limit === 'number' && limit > 0 ? limit : 50
+
+    if (since_seconds) {
+      // log show accepts --last <time>
+      args.push('--last', `${since_seconds}s`)
+    } else {
+      // default to last 60s to keep quick
+      args.push('--last', '60s')
+    }
+
     if (appId) {
       validateBundleId(appId)
+      // constrain to subsystem or process matching appId
       args.push('--predicate', `subsystem contains "${appId}" or process == "${appId}"`)
+    } else if (tag) {
+      // predicate by subsystem/category
+      args.push('--predicate', `subsystem contains "${tag}"`)
     }
-    
-    const result = await execCommand(args, deviceId)
-    const device = await getIOSDeviceMetadata(deviceId)
-    const logs = result.output ? result.output.split('\n') : []
-    return {
-      device,
-      logs,
-      logCount: logs.length,
+
+    try {
+      const result = await execCommand(args, deviceId)
+      const device = await getIOSDeviceMetadata(deviceId)
+      const rawLines = result.output ? result.output.split(/\r?\n/).filter(Boolean) : []
+
+      // Parse lines into structured entries. iOS log format: timestamp [PID:tid] <level> subsystem:category: message
+      const parsed = rawLines.map(line => {
+        // Example: 2023-08-12 12:34:56.789012+0000  pid  <Debug>  MyApp[123:456]  <info>  MySubsystem: MyCategory: Message here
+        // Simpler approach: try to extract ISO timestamp at start
+        let ts: string | null = null
+        const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d+)?)/)
+        if (tsMatch) {
+          const d = new Date(tsMatch[1])
+          if (!isNaN(d.getTime())) ts = d.toISOString()
+        }
+
+        // level mapping
+        let lvl = 'INFO'
+        const lvlMatch = line.match(/\b(Debug|Info|Default|Error|Fault|Warning)\b/i)
+        if (lvlMatch) {
+          const map: Record<string, string> = { 'debug': 'DEBUG', 'info': 'INFO', 'default': 'DEBUG', 'error': 'ERROR', 'fault': 'ERROR', 'warning': 'WARN' }
+          lvl = map[(lvlMatch[1] || '').toLowerCase()] || 'INFO'
+        }
+
+        // subsystem/category -> tag
+        let tagVal = ''
+        const tagMatch = line.match(/\s([A-Za-z0-9_./-]+):\s/)
+        if (tagMatch) tagVal = tagMatch[1]
+
+        // pid extraction
+        let pidNum: number | null = null
+        const pidMatch = line.match(/\[(\d+):\d+\]/)
+        if (pidMatch) pidNum = Number(pidMatch[1])
+
+        // message: extract robustly after the subsystem/category token when available
+        let message = line
+        if (tagMatch) {
+          // tagMatch[0] includes the delimiter (e.g. " MySubsystem: ") — use it to find the message start
+          const marker = tagMatch[0]
+          const idx = line.indexOf(marker)
+          if (idx !== -1) {
+            message = line.slice(idx + marker.length).trim()
+          } else {
+            // fallback: try to trim off common prefixes (timestamp, pid, level) and keep the rest
+            const afterPidMatch = line.match(/\]\s+/)
+            if (afterPidMatch) {
+              const afterPidIdx = line.indexOf(afterPidMatch[0]) + afterPidMatch[0].length
+              message = line.slice(afterPidIdx).trim()
+            } else {
+              // remove leading level tokens like <Debug> and keep remainder
+              message = line.replace(/^.*?<.*?>\s*/,'').trim()
+            }
+          }
+        } else {
+          // No tag found — strip obvious prefixes and keep remainder (preserve colons in message)
+          message = line.replace(/^.*?<.*?>\s*/,'').trim()
+        }
+
+        return { timestamp: ts, level: lvl, tag: tagVal, pid: pidNum, message }
+      })
+
+      // Apply contains filter
+      let filtered = parsed
+      if (contains) filtered = filtered.filter(e => e.message && e.message.includes(contains))
+
+      // Apply since_seconds already applied by log show, but double-check timestamps
+      if (since_seconds) {
+        const sinceMs = Date.now() - (since_seconds * 1000)
+        filtered = filtered.filter(e => e.timestamp && (new Date(e.timestamp).getTime() >= sinceMs))
+      }
+
+      // level filter
+      if (level) {
+        const L = level.toUpperCase()
+        filtered = filtered.filter(e => e.level && e.level.toUpperCase() === L)
+      }
+
+      // tag filter
+      if (tag) filtered = filtered.filter(e => e.tag && e.tag.includes(tag))
+
+      // pid filter
+      if (pid) filtered = filtered.filter(e => e.pid === pid)
+
+      // If appId present but no predicate returned lines, try substring match
+      if (appId && filtered.length === 0) {
+        const matched = parsed.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)))
+        if (matched.length > 0) filtered = matched
+      }
+
+      // Order oldest -> newest
+      filtered.sort((a,b) => {
+        const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0
+        const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0
+        return ta - tb
+      })
+
+      const limited = filtered.slice(-Math.max(0, effectiveLimit))
+      return { device, logs: limited, logCount: limited.length }
+    } catch (err) {
+      console.error('iOS getLogs failed:', err)
+      const device = await getIOSDeviceMetadata(deviceId)
+      return { device, logs: [], logCount: 0 }
     }
   }
 

package/src/server.ts

@@ -171,7 +171,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 
     {
       name: "get_logs",
-      description: "Get recent logs from Android or iOS simulator. Returns device metadata and the log output.",
+      description: "Get recent logs from Android or iOS simulator. Returns device metadata and structured logs suitable for AI consumption.",
       inputSchema: {
         type: "object",
         properties: {
@@ -187,9 +187,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             type: "string",
             description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected."
           },
+          pid: { type: "number", description: "Filter by process id" },
+          tag: { type: "string", description: "Filter by tag (Android) or subsystem/category (iOS)" },
+          level: { type: "string", description: "Log level filter (VERBOSE, DEBUG, INFO, WARN, ERROR)" },
+          contains: { type: "string", description: "Substring to match in log message" },
+          since_seconds: { type: "number", description: "Only return logs from the last N seconds" },
+          limit: { type: "number", description: "Override default number of returned lines" },
           lines: {
             type: "number",
-            description: "Number of log lines (android only)"
+            description: "Legacy - number of log lines (android only)"
           }
         },
         required: ["platform"]
@@ -603,12 +609,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typ
 
 
     if (name === "get_logs") {
-      const { platform, appId, deviceId, lines } = args as any
-      const res = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines })
+      const { platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines } = args as any
+      const res = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines })
+      const filtered = !!(pid || tag || level || contains || since_seconds || appId)
       return {
         content: [
-          { type: 'text', text: JSON.stringify({ device: res.device, result: { lines: res.logs.length, crashLines: res.crashLines.length > 0 ? res.crashLines : undefined } }, null, 2) },
-          { type: 'text', text: (res.logs || []).join('\n') }
+          { type: 'text', text: JSON.stringify({ device: res.device, result: { count: res.logCount, filtered, crashLines: (res.crashLines || []) } }, null, 2) },
+          { type: 'text', text: JSON.stringify({ logs: res.logs }, null, 2) }
         ]
       }
     }

package/src/types.ts

@@ -36,9 +36,17 @@ export interface ResetAppDataResponse {
   diagnostics?: any;
 }
 
+export interface StructuredLogEntry {
+  timestamp: string | null; // ISO string
+  level: string; // VERBOSE, DEBUG, INFO, WARN, ERROR
+  tag: string;
+  pid: number | null;
+  message: string;
+}
+
 export interface GetLogsResponse {
   device: DeviceInfo;
-  logs: string[];
+  logs: StructuredLogEntry[];
   logCount: number;
 }
 

package/src/utils/cli/ios/run-ios-smoke.ts

@@ -17,7 +17,7 @@ async function main() {
     console.log('screenshot OK? size:', shot && shot.screenshot ? shot.screenshot.length : 0)
 
     console.log('[3] getLogs')
-    const logs = await obs.getLogs(appId, undefined);
+    const logs = await obs.getLogs({ appId, deviceId });
     console.log('logs count:', logs.logCount)
 
     console.log('[4] terminateApp')

package/test/helpers/run-get-logs.ts

@@ -0,0 +1,20 @@
+import { ToolsObserve } from '../../src/observe/index.js'
+import minimist from 'minimist'
+
+async function main() {
+  const args = minimist(process.argv.slice(2))
+  const platform = args.platform || args.p || 'android'
+  const id = args.id || args.device || args.deviceId || 'default'
+  const limit = typeof args.limit === 'number' ? args.limit : (typeof args.lines === 'number' ? args.lines : 50)
+
+  try {
+    const res = await ToolsObserve.getLogsHandler({ platform, id, limit })
+    console.log(JSON.stringify(res))
+    process.exit(0)
+  } catch (err: any) {
+    console.error(JSON.stringify({ error: { message: err.message || String(err) } }))
+    process.exit(2)
+  }
+}
+
+main()

package/test/observe/device/get_logs.android.smoke.ts

@@ -0,0 +1,35 @@
+import fs from 'fs'
+import { execSync } from 'child_process'
+
+function log(msg: string) { console.log(msg) }
+
+if (process.env.SKIP_DEVICE_TESTS === '1') {
+  log('SKIP_DEVICE_TESTS=1 detected - skipping android device smoke test')
+  process.exit(0)
+}
+
+// Ensure helper script exists
+const helperScript = 'test/helpers/run-get-logs.ts'
+if (!fs.existsSync(helperScript)) {
+  console.error(`Missing ${helperScript}. Run 'npm run build' first or ensure the helper exists.`)
+  process.exit(1)
+}
+
+try {
+  // Run the helper smoke script for android
+  const cmd = `tsx ${helperScript} --platform android --id default --limit 20`
+  const out = execSync(cmd, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024, timeout: 30000 })
+  const parsed = JSON.parse(out)
+
+  if (!parsed || !Array.isArray(parsed.logs)) throw new Error('Output missing logs array')
+  const count = parsed.count ?? parsed.logs.length
+  if (count !== parsed.logs.length) throw new Error('count mismatch')
+  if (parsed.logs.some((e: any) => !e.timestamp || !e.level || typeof e.message !== 'string')) throw new Error('log entry missing fields')
+
+  log('Android device smoke test: PASS')
+  process.exit(0)
+} catch (err: any) {
+  console.error('Android device smoke test: FAIL')
+  console.error(err && err.message ? err.message : err)
+  process.exit(2)
+}

package/test/observe/device/get_logs.ios.smoke.ts

@@ -0,0 +1,33 @@
+import fs from 'fs'
+import { execSync } from 'child_process'
+
+function log(msg: string) { console.log(msg) }
+
+if (process.env.SKIP_DEVICE_TESTS === '1') {
+  log('SKIP_DEVICE_TESTS=1 detected - skipping ios device smoke test')
+  process.exit(0)
+}
+
+const helperScript = 'test/helpers/run-get-logs.ts'
+if (!fs.existsSync(helperScript)) {
+  console.error(`Missing ${helperScript}. Run 'npm run build' first or ensure the helper exists.`)
+  process.exit(1)
+}
+
+try {
+  const cmd = `tsx ${helperScript} --platform ios --id booted --limit 20`
+  const out = execSync(cmd, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024, timeout: 30000 })
+  const parsed = JSON.parse(out)
+
+  if (!parsed || !Array.isArray(parsed.logs)) throw new Error('Output missing logs array')
+  const count = parsed.count ?? parsed.logs.length
+  if (count !== parsed.logs.length) throw new Error('count mismatch')
+  if (parsed.logs.some((e: any) => !e.timestamp || !e.level || typeof e.message !== 'string')) throw new Error('log entry missing fields')
+
+  log('iOS device smoke test: PASS')
+  process.exit(0)
+} catch (err: any) {
+  console.error('iOS device smoke test: FAIL')
+  console.error(err && err.message ? err.message : err)
+  process.exit(2)
+}

package/test/observe/unit/get_logs.test.ts

@@ -0,0 +1,58 @@
+import { StructuredLogEntry } from '../../../src/types.js'
+
+function assert(cond: boolean, msg?: string) { if (!cond) throw new Error(msg || 'Assertion failed') }
+
+function applyFilters(entries: StructuredLogEntry[], opts: { contains?: string, level?: string, tag?: string, pid?: number, since_seconds?: number, limit?: number }) {
+  let filtered = entries.slice()
+  if (opts.contains) filtered = filtered.filter(e => e.message && e.message.includes(opts.contains!))
+  if (opts.since_seconds) {
+    const sinceMs = Date.now() - (opts.since_seconds * 1000)
+    filtered = filtered.filter(e => e.timestamp && (new Date(e.timestamp).getTime() >= sinceMs))
+  }
+  if (opts.level) filtered = filtered.filter(e => e.level && e.level.toUpperCase() === opts.level!.toUpperCase())
+  if (opts.tag) filtered = filtered.filter(e => e.tag && e.tag.includes(opts.tag!))
+  if (typeof opts.pid === 'number') filtered = filtered.filter(e => e.pid === opts.pid)
+  // oldest -> newest
+  filtered.sort((a,b) => (a.timestamp? new Date(a.timestamp).getTime():0) - (b.timestamp? new Date(b.timestamp).getTime():0))
+  const lim = typeof opts.limit === 'number' && opts.limit > 0 ? opts.limit : 50
+  return filtered.slice(-Math.max(0, lim))
+}
+
+function run() {
+  const now = Date.now()
+  const entries: StructuredLogEntry[] = [
+    { timestamp: new Date(now - 60000).toISOString(), level: 'INFO', tag: 'A', pid: 123, message: 'startup complete' },
+    { timestamp: new Date(now - 45000).toISOString(), level: 'WARN', tag: 'B', pid: 124, message: 'slow response' },
+    { timestamp: new Date(now - 30000).toISOString(), level: 'ERROR', tag: 'A', pid: 123, message: 'Unhandled exception' },
+    { timestamp: new Date(now - 15000).toISOString(), level: 'DEBUG', tag: 'C', pid: 125, message: 'debug info' },
+    { timestamp: new Date(now - 5000).toISOString(), level: 'INFO', tag: 'A', pid: 123, message: 'user action happened' }
+  ]
+
+  // contains filter
+  const c1 = applyFilters(entries, { contains: 'user' })
+  assert(c1.length === 1 && c1[0].message.includes('user'), 'contains filter failed')
+
+  // level filter
+  const e1 = applyFilters(entries, { level: 'ERROR' })
+  assert(e1.length === 1 && e1[0].level === 'ERROR', 'level filter failed')
+
+  // tag filter
+  const t1 = applyFilters(entries, { tag: 'A' })
+  assert(t1.length === 3, 'tag filter failed')
+
+  // pid filter
+  const p1 = applyFilters(entries, { pid: 123 })
+  assert(p1.length === 3, 'pid filter failed')
+
+  // since_seconds filter (last 20s) should include last two entries
+  const s1 = applyFilters(entries, { since_seconds: 20 })
+  if (s1.length !== 2) throw new Error('since_seconds filter expected 2 entries, got ' + s1.length)
+
+  // limit
+  const l1 = applyFilters(entries, { limit: 2 })
+  assert(l1.length === 2 && l1[0].timestamp <= l1[1].timestamp, 'limit or ordering failed')
+
+  console.log('get_logs unit tests passed')
+}
+
+run()