mobile-debug-mcp 0.21.2 → 0.21.4

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"]
@@ -316,17 +322,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "wait_for_ui",
-            description: "Wait for a UI/log/screen/idle condition with a stability window before returning success.",
+            description: "Deterministic UI wait primitive. Waits for selector condition with retries and backoff.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    type: { type: "string", enum: ["ui", "log", "screen", "idle"], description: "Condition type to observe", default: "ui" },
-                    query: { type: "string", description: "Optional query string for ui/log/screen types" },
-                    timeoutMs: { type: "number", description: "Timeout in ms to wait for condition (default 30000)", default: 30000 },
-                    pollIntervalMs: { type: "number", description: "Polling interval in ms (default 300, clamped to 250-500)", default: 300 },
-                    match: { type: "string", enum: ["present", "absent"], description: "Match mode for UI checks: 'present' or 'absent' (default 'present')", default: "present" },
-                    stability_ms: { type: "number", description: "Stability window in ms that the condition must hold before returning success (default 700)", default: 700 },
-                    includeSnapshotOnFailure: { type: "boolean", description: "Whether to include a debug snapshot on timeout (default true)", default: true },
+                    selector: {
+                        type: "object",
+                        properties: {
+                            text: { type: "string" },
+                            resource_id: { type: "string" },
+                            accessibility_id: { type: "string" },
+                            contains: { type: "boolean", description: "When true, perform substring matching", default: false }
+                        }
+                    },
+                    condition: { type: "string", enum: ["exists", "not_exists", "visible", "clickable"], default: "exists" },
+                    timeout_ms: { type: "number", default: 60000 },
+                    poll_interval_ms: { type: "number", default: 300 },
+                    match: { type: "object", properties: { index: { type: "number" } } },
+                    retry: { type: "object", properties: { max_attempts: { type: "number", default: 1 }, backoff_ms: { type: "number", default: 0 } } },
                     platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override" },
                     deviceId: { type: "string", description: "Optional device serial/udid" }
                 }
@@ -563,12 +576,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 || []), source: res.source, meta: res.meta || {} } }, null, 2) },
+                    { type: 'text', text: JSON.stringify({ logs: res.logs }, null, 2) }
                 ]
             };
         }
@@ -622,8 +636,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return wrapResponse(res);
         }
         if (name === "wait_for_ui") {
-            const { type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId } = (args || {});
-            const res = await ToolsInteract.waitForUIHandler({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId });
+            const { selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry, platform, deviceId } = (args || {});
+            const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId });
             return wrapResponse(res);
         }
         if (name === "find_element") {

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,13 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.21.4]
+- updated `wait_for_ui` with better contract and observability
+- update `get_logs` to get better output
+
+## [0.21.3]
+- Added structured logs
+
 ## [0.21.2]
 - Fixed screenshots not working, imnproved tool
 

package/docs/tools/observe.md

@@ -3,27 +3,42 @@
 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. Use logs as a debugging aid only — prefer UI validation (wait_for_ui) first.
+
+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.
+
+When to use get_logs:
+
+- After a UI validation (wait_for_ui) fails to confirm the expected outcome.
+- When you suspect a crash, error, or silent failure that the UI doesn't expose.
+- To provide additional debugging context correlated with an action.
+
+Do NOT use get_logs as the primary signal for success/failure, or call it repeatedly without new actions.
+
+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" } ], "logCount": 1, "source": "pid|package|process|broad", "meta": { "filters": { "tag": "MyTag", "level": "ERROR" }, "pidArg": 1234 } }
 ```
 
-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. logCount equals number of entries returned.
+- `source`: indicates how logs were filtered at collection time. Values: `pid` (filtered by process id), `package` / `process` (filtered by app/package/bundle), or `broad` (unfiltered system logs).
+- `meta`: debugging information about filters and collection method (e.g., pid detection, effective limit).
+- 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.4",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/interact/index.ts

@@ -218,9 +218,193 @@ export class ToolsInteract {
     return { found: true, element: outEl, score: scoreVal, confidence: scoreVal }
   }
 
-  static async waitForUIHandler({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }: { type?: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, includeSnapshotOnFailure?: boolean, match?: 'present'|'absent', stability_ms?: number, observationDelayMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
-    // 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 })
+  static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId }: { selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }, condition?: 'exists'|'not_exists'|'visible'|'clickable', timeout_ms?: number, poll_interval_ms?: number, match?: { index?: number }, retry?: { max_attempts?: number, backoff_ms?: number }, platform?: 'android'|'ios', deviceId?: string }) {
+    const overallStart = Date.now()
+
+    // Validate selector: require at least one of text, resource_id, or accessibility_id
+    if (!selector || (typeof selector === 'object' && Object.keys(selector).length === 0)) {
+      return { status: 'timeout', error: { code: 'INVALID_SELECTOR', message: 'At least one selector field must be provided (text, resource_id, or accessibility_id)' }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } }
+    }
+
+    const hasText = selector && typeof (selector as any).text === 'string' && (selector as any).text.trim().length > 0
+    const hasResId = selector && typeof (selector as any).resource_id === 'string' && (selector as any).resource_id.trim().length > 0
+    const hasAccId = selector && typeof (selector as any).accessibility_id === 'string' && (selector as any).accessibility_id.trim().length > 0
+    if (!hasText && !hasResId && !hasAccId) {
+      return { status: 'timeout', error: { code: 'INVALID_SELECTOR', message: 'Selector must include at least one of: text, resource_id, accessibility_id' }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } }
+    }
+
+    // Validate condition
+    if (!['exists','not_exists','visible','clickable'].includes(condition)) {
+      return { status: 'timeout', error: { code: 'INVALID_CONDITION', message: `Unsupported condition: ${condition}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } }
+    }
+
+    // Platform check
+    if (platform && !['android','ios'].includes(platform)) {
+      return { status: 'timeout', error: { code: 'PLATFORM_NOT_SUPPORTED', message: `Unsupported platform: ${platform}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } }
+    }
+
+    const effectivePoll = Math.max(50, Math.min(poll_interval_ms || 300, 2000))
+    const maxAttempts = (retry && retry.max_attempts) ? Math.max(1, retry.max_attempts) : 1
+    const backoff = (retry && retry.backoff_ms) ? Math.max(0, retry.backoff_ms) : 0
+
+    let attempts = 0
+    let totalPollCount = 0
+
+    // Precompute normalized selector values and helpers (constant across polls)
+    const normalize = (s: any) => (s === null || s === undefined) ? '' : String(s).toLowerCase().trim()
+    const containsFlag = !!selector.contains
+    const selText = normalize((selector as any).text)
+    const selRid = normalize((selector as any).resource_id)
+    const selAid = normalize((selector as any).accessibility_id)
+
+    try {
+      while (attempts < maxAttempts) {
+        attempts++
+        const attemptStart = Date.now()
+        const deadline = attemptStart + (timeout_ms || 0)
+
+        while (Date.now() <= deadline) {
+          totalPollCount++
+          try {
+            const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+            const elements = (tree && Array.isArray(tree.elements)) ? tree.elements as any[] : []
+
+            const matches: { el: any, idx: number }[] = []
+
+            for (let i = 0; i < elements.length; i++) {
+              const el = elements[i]
+              let ok = true
+
+              // text
+              if (selector.text !== undefined && selector.text !== null) {
+                const val = normalize(el.text || el.label || el.value || '')
+                if (containsFlag) {
+                  if (!val.includes(selText)) ok = false
+                } else {
+                  if (val !== selText) ok = false
+                }
+              }
+
+              // resource_id
+              if (ok && selector.resource_id !== undefined && selector.resource_id !== null) {
+                const rid = normalize(el.resourceId || el.resourceID || el.id || '')
+                if (containsFlag) {
+                  if (!rid.includes(selRid)) ok = false
+                } else {
+                  if (rid !== selRid) ok = false
+                }
+              }
+
+              // accessibility_id
+              if (ok && selector.accessibility_id !== undefined && selector.accessibility_id !== null) {
+                const aid = normalize(el.contentDescription || el.contentDesc || el.accessibilityLabel || el.label || '')
+                if (containsFlag) {
+                  if (!aid.includes(selAid)) ok = false
+                } else {
+                  if (aid !== selAid) ok = false
+                }
+              }
+
+              if (ok) matches.push({ el, idx: i })
+            }
+
+            // Evaluate condition
+            const matchedCount = matches.length
+            const pickIndexProvided = (match && typeof (match as any).index === 'number')
+            const pickIndex: number = pickIndexProvided ? Number((match as any).index) : 0
+            let chosen: { el: any, idx: number } | null = null
+            if (matches.length === 0) {
+              chosen = null
+            } else if (pickIndexProvided) {
+              // If a specific index is requested but out of bounds, treat as not matched for this poll (deterministic)
+              if (pickIndex >= 0 && pickIndex < matches.length) chosen = matches[pickIndex]
+              else chosen = null
+            } else {
+              chosen = matches[0]
+            }
+
+            let conditionMet = false
+            if (condition === 'exists') {
+              // when an index is specified, existence requires that specific index be present
+              conditionMet = pickIndexProvided ? (chosen !== null) : (matchedCount >= 1)
+            } else if (condition === 'not_exists') {
+              // when an index is specified, not_exists is true if that index is absent
+              conditionMet = pickIndexProvided ? (chosen === null) : (matchedCount === 0)
+            } else if (condition === 'visible') {
+              if (chosen) {
+                const b = chosen.el.bounds
+                const visibleFlag = !!chosen.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1])
+                conditionMet = visibleFlag
+              } else conditionMet = false
+            } else if (condition === 'clickable') {
+              if (chosen) {
+                const b = chosen.el.bounds
+                const visibleFlag = !!chosen.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1])
+                const enabled = !!chosen.el.enabled
+                const clickable = !!chosen.el.clickable || !!chosen.el._interactable
+                conditionMet = visibleFlag && enabled && clickable
+              } else conditionMet = false
+            }
+
+            if (conditionMet) {
+              const now = Date.now()
+              const latency_ms = now - overallStart
+              // Build element output per spec
+              const outEl = chosen ? {
+                text: chosen.el.text ?? null,
+                resource_id: chosen.el.resourceId ?? chosen.el.resourceID ?? chosen.el.id ?? null,
+                accessibility_id: chosen.el.contentDescription ?? chosen.el.contentDesc ?? chosen.el.accessibilityLabel ?? chosen.el.label ?? null,
+                class: chosen.el.type ?? chosen.el.class ?? null,
+                bounds: Array.isArray(chosen.el.bounds) && chosen.el.bounds.length >= 4 ? chosen.el.bounds : null,
+                index: chosen.idx
+              } : null
+
+              return {
+                status: 'success',
+                matched: matchedCount,
+                element: outEl,
+                metrics: { latency_ms, poll_count: totalPollCount, attempts }
+              }
+            }
+
+          } catch (e) {
+            // Non-fatal per-poll error; record and continue
+            console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e))
+          }
+
+          // Sleep until next poll
+          await new Promise(r => setTimeout(r, effectivePoll || 50))
+        }
+
+        // Attempt timed out; if more attempts allowed, backoff then retry
+        if (attempts < maxAttempts) {
+          if (backoff > 0) await new Promise(r => setTimeout(r, backoff))
+          continue
+        }
+
+        // Final failure for this call
+        const elapsed = Date.now() - overallStart
+        return {
+          status: 'timeout',
+          error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout` },
+          metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts }
+        }
+      }
+
+    } catch (err) {
+      const elapsed = Date.now() - overallStart
+      return { status: 'timeout', error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) }, metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts } }
+    }
+  }
+
+  // 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 }) {
@@ -279,7 +463,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 +534,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,29 +93,102 @@ 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))
+
+      const source = pidArg ? 'pid' : (appId ? 'package' : 'broad')
+      const meta = { pidArg, appIdProvided: !!appId, filters: { tag, level, contains, since_seconds, limit: effectiveLimit }, pidExplicit: !!pid }
+      return { device: deviceInfo, logs: limited, logCount: limited.length, source, meta }
     } catch (e) {
       console.error("Error fetching logs:", e)
-      return { device: deviceInfo, logs: [], logCount: 0 }
+      return { device: deviceInfo, logs: [], logCount: 0, source: 'broad', meta: { error: e instanceof Error ? e.message : String(e) } }
     }
   }
 

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, source: response.source, meta: response.meta, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
+      return { device: response.device, logs, crashLines, logCount: response.logCount, source: response.source, meta: response.meta }
     } 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, source: resp.source, meta: resp.meta, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
+      return { device: resp.device, logs, crashLines, logCount: resp.logCount, source: resp.source, meta: resp.meta }
     }
   }
 
@@ -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 => {