mobile-debug-mcp 0.21.2 → 0.21.4

package/src/observe/ios.ts

@@ -121,20 +121,158 @@ 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')
+    }
+
+    let processNameUsed: string | undefined = undefined
     if (appId) {
       validateBundleId(appId)
-      args.push('--predicate', `subsystem contains "${appId}" or process == "${appId}"`)
+      // prefer matching the simple process name (last segment of bundle id), but also match full bundle id in subsystem
+      const parts = appId.split('.')
+      const simpleName = parts[parts.length - 1]
+      processNameUsed = simpleName
+      // predicate: match process by simple name or full bundle id, or subsystem contains bundle id
+      args.push('--predicate', `process == "${simpleName}" or process == "${appId}" or subsystem contains "${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 {
+      // Attempt pid detection if appId provided and no explicit pid supplied — prefer process name derived from bundle id
+      let detectedPid: number | null = null
+      if (appId && !pid) {
+        const parts = appId.split('.')
+        const simpleName = parts[parts.length - 1]
+        try {
+          const pgrepRes = await execCommand(['simctl','spawn', deviceId, 'pgrep', '-f', simpleName], deviceId)
+          const out = pgrepRes && pgrepRes.output ? pgrepRes.output.trim() : ''
+          const firstLine = out.split(/\r?\n/).find(Boolean)
+          if (firstLine) {
+            const n = Number(firstLine.trim())
+            if (!isNaN(n) && n > 0) detectedPid = n
+          }
+        } catch {
+          // ignore pgrep failures — we'll fall back to process/bundle matching
+        }
+      }
+      const effectivePid = pid || detectedPid || null
+      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 (use detected/effective pid if available)
+      const pidToFilter = effectivePid
+      if (pidToFilter) filtered = filtered.filter(e => e.pid === pidToFilter)
+
+      // 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)) || (e.message && processNameUsed && e.message.includes(processNameUsed)))
+        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 source = pidToFilter ? 'pid' : (appId ? 'process' : 'broad')
+      const meta = { appIdProvided: !!appId, processNameUsed: processNameUsed || null, detectedPid: detectedPid || null, filters: { tag, level, contains, since_seconds, limit: effectiveLimit }, pidExplicit: !!pid }
+      const limited = filtered.slice(-Math.max(0, effectiveLimit))
+      return { device, logs: limited, logCount: limited.length, source, meta }
+    } catch (err) {
+      console.error('iOS getLogs failed:', err)
+      const device = await getIOSDeviceMetadata(deviceId)
+      return { device, logs: [], logCount: 0, source: 'broad', meta: { error: err instanceof Error ? err.message : String(err) } }
     }
   }
 
@@ -327,7 +465,8 @@ export class iOSObserve {
 
   async startLogStream(bundleId: string, deviceId: string = 'booted', sessionId: string = 'default') : Promise<{ success: boolean; stream_started?: boolean; error?: string }> {
     try {
-      const predicate = `process == "${bundleId}" or subsystem contains "${bundleId}"`
+      const simple = bundleId.split('.').pop() || bundleId
+      const predicate = `process == "${simple}" or process == "${bundleId}" or subsystem contains "${bundleId}"`
 
       if (iosActiveLogStreams.has(sessionId)) {
         try { iosActiveLogStreams.get(sessionId)!.proc.kill() } catch {}

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"]
@@ -341,17 +347,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" }
         }
@@ -359,6 +372,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
 
 
+
     {
       name: "find_element",
       description: "Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.",
@@ -603,12 +617,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 || []), source: res.source, meta: res.meta || {} } }, null, 2) },
+          { type: 'text', text: JSON.stringify({ logs: res.logs }, null, 2) }
         ]
       }
     }
@@ -673,8 +688,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typ
 
 
     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 || {}) as any
-      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 || {}) as any
+      const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId })
       return wrapResponse(res)
     }
 

package/src/types.ts

@@ -36,10 +36,22 @@ 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;
+  // Source indicates the filtering method used: 'pid', 'package'/'process', or 'broad'
+  source?: string;
+  // Meta contains debugging information about how logs were collected and filters applied
+  meta?: Record<string, any>;
 }
 
 export interface GetCrashResponse {

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/interact/unit/wait_for_ui_contract.test.ts

@@ -0,0 +1,33 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+import assert from 'assert'
+
+async function run() {
+  console.log('Starting wait_for_ui contract tests...')
+  const orig = (Observe as any).ToolsObserve.getUITreeHandler
+
+  try {
+    // success shape
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'OK', resourceId: 'rid', contentDescription: 'acc', type: 'TextView', bounds: [0,0,10,10], visible: true, clickable: false, enabled: true } ] })
+    const s = await ToolsInteract.waitForUIHandler({ selector: { text: 'OK' }, condition: 'exists', timeout_ms: 500, poll_interval_ms: 50, platform: 'android' })
+    // Assert contract fields for success
+    assert.strictEqual(s.status, 'success', 'status must be success')
+    assert.strictEqual(typeof s.matched, 'number', 'matched must be number')
+    assert.ok(s.element, 'element must be present')
+    assert.ok(s.metrics && typeof s.metrics.latency_ms === 'number' && typeof s.metrics.poll_count === 'number' && typeof s.metrics.attempts === 'number', 'metrics must include latency_ms, poll_count, attempts')
+    assert.ok(['string','object'].includes(typeof s.element.bounds) || Array.isArray(s.element.bounds), 'element.bounds must be present')
+
+    // timeout shape
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [] })
+    const t = await ToolsInteract.waitForUIHandler({ selector: { text: 'Nope' }, condition: 'exists', timeout_ms: 200, poll_interval_ms: 50, platform: 'android' })
+    assert.strictEqual(t.status, 'timeout', 'status must be timeout on no match')
+    assert.ok(t.error && t.error.code && t.error.message, 'timeout must include error with code and message')
+    assert.ok(t.metrics && typeof t.metrics.latency_ms === 'number', 'timeout metrics must include latency_ms')
+
+    console.log('wait_for_ui contract tests: PASS')
+  } finally {
+    ;(Observe as any).ToolsObserve.getUITreeHandler = orig
+  }
+}
+
+run().catch(err => { console.error('wait_for_ui_contract tests failed:', err); process.exit(1) })

package/test/interact/unit/wait_for_ui_new.test.ts

@@ -0,0 +1,57 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+
+async function run() {
+  console.log('Starting new wait_for_ui unit tests...')
+  const origGetUITree = (Observe as any).ToolsObserve.getUITreeHandler
+
+  try {
+    // Test 1: exact text match -> exists
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'Hello', resourceId: 'rid1', contentDescription: 'acc1', type: 'Button', bounds: [0,0,10,10], visible: true, clickable: false, enabled: true } ] })
+    const r1 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Hello' }, condition: 'exists', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
+    const ok1 = r1 && r1.status === 'success' && r1.matched === 1 && r1.element && r1.element.text === 'Hello'
+    console.log('Exact match exists:', ok1 ? 'PASS' : 'FAIL', JSON.stringify(r1, null, 2))
+
+    // Test 2: contains matching
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'Welcome User', resourceId: 'rid2', contentDescription: 'acc2', type: 'TextView', bounds: [0,0,50,10], visible: true } ] })
+    const r2 = await ToolsInteract.waitForUIHandler({ selector: { text: 'User', contains: true }, condition: 'exists', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
+    const ok2 = r2 && r2.status === 'success' && r2.matched === 1 && r2.element && r2.element.text && r2.element.text.includes('Welcome')
+    console.log('Contains match:', ok2 ? 'PASS' : 'FAIL', JSON.stringify(r2, null, 2))
+
+    // Test 3: visible condition
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'Hidden', resourceId: 'rid3', bounds: [0,0,0,0], visible: false } ] })
+    const r3 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Hidden' }, condition: 'visible', timeout_ms: 300, poll_interval_ms: 50, platform: 'android' })
+    const ok3 = r3 && r3.status === 'timeout' && r3.error && r3.error.code === 'ELEMENT_NOT_FOUND'
+    console.log('Visible negative (hidden element):', ok3 ? 'PASS' : 'FAIL', JSON.stringify(r3, null, 2))
+
+    // Test 4: clickable condition
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'TapMe', resourceId: 'rid4', bounds: [0,0,20,20], visible: true, clickable: true, enabled: true } ] })
+    const r4 = await ToolsInteract.waitForUIHandler({ selector: { text: 'TapMe' }, condition: 'clickable', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
+    const ok4 = r4 && r4.status === 'success' && r4.matched === 1 && r4.element && r4.element.index === 0
+    console.log('Clickable match:', ok4 ? 'PASS' : 'FAIL', JSON.stringify(r4, null, 2))
+
+    // Test 5: retry behavior - first attempt times out, second attempt succeeds
+    const start = Date.now()
+    let seqTree = async () => {
+      const now = Date.now()
+      // for first ~400ms return no elements, afterwards return match
+      if (now - start < 400) return { elements: [] }
+      return { elements: [ { text: 'Retried', resourceId: 'rid5', bounds: [0,0,10,10], visible: true } ] }
+    }
+    ;(Observe as any).ToolsObserve.getUITreeHandler = seqTree
+    const r5 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Retried' }, condition: 'exists', timeout_ms: 200, poll_interval_ms: 50, match: undefined, retry: { max_attempts: 3, backoff_ms: 150 }, platform: 'android' })
+    const ok5 = r5 && r5.status === 'success' && r5.metrics && r5.metrics.attempts >= 2
+    console.log('Retry behavior:', ok5 ? 'PASS' : 'FAIL', JSON.stringify(r5, null, 2))
+
+    // Test 6: timeout with no selector match -> correct error code
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [] })
+    const r6 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Nope' }, condition: 'exists', timeout_ms: 300, poll_interval_ms: 50, retry: { max_attempts: 1 }, platform: 'android' })
+    const ok6 = r6 && r6.status === 'timeout' && r6.error && r6.error.code === 'ELEMENT_NOT_FOUND'
+    console.log('Timeout no match:', ok6 ? 'PASS' : 'FAIL', JSON.stringify(r6, null, 2))
+
+  } finally {
+    (Observe as any).ToolsObserve.getUITreeHandler = origGetUITree
+  }
+}
+
+run().catch(err => { console.error('wait_for_ui_new tests failed:', err); process.exit(1) })

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()

package/test/observe/unit/ios-getlogs.test.ts

@@ -0,0 +1,67 @@
+import { iOSObserve } from '../../../src/observe/ios'
+import assert from 'assert'
+
+// Lightweight unit tests: verify predicate construction and meta extraction logic using internal functions
+// Since getLogs executes xcrun, run tests in SKIP_DEVICE_TESTS=1 environment by stubbing execCommand where possible.
+
+import * as iosUtils from '../../../src/utils/ios/utils'
+
+function stubExecCommand(original: any, expectedArgsChecker: (args: string[]) => boolean, output: string) {
+  return async function (args: string[], deviceId?: string) {
+    if (!expectedArgsChecker(args)) throw new Error('Unexpected args: ' + JSON.stringify(args))
+    return { output, device: { platform: 'ios', id: deviceId || 'booted' } }
+  }
+}
+
+describe('iOS getLogs predicate and meta', () => {
+  let obs: iOSObserve
+  beforeEach(() => {
+    obs = new iOSObserve()
+  })
+
+  it('uses simple process name predicate when appId provided', async () => {
+    const bundle = 'com.ideamechanics.modul8'
+    // stub execCommand twice: first for pgrep, second for log show
+    const pgrepOutput = '12345\n'
+    const logOutput = '2026-03-31 09:21:20.085 Module[12345:678] <Info> Modul8: Test message'
+
+    const orig = (iosUtils as any).execCommand
+    try {
+      (iosUtils as any).execCommand = stubExecCommand(orig, (args) => args.includes('pgrep'), pgrepOutput)
+      // second replacement for the log show call
+      let called = false
+      (iosUtils as any).execCommand = async function (args: string[]) {
+        if (args.includes('pgrep')) return { output: pgrepOutput, device: { platform: 'ios', id: 'booted' } }
+        if (args.includes('log') && args.includes('show')) { called = true; return { output: logOutput, device: { platform: 'ios', id: 'booted' } } }
+        throw new Error('Unexpected args: ' + JSON.stringify(args))
+      }
+
+      const res = await obs.getLogs({ appId: bundle, deviceId: 'booted' })
+      assert(res.meta.processNameUsed === 'modul8' || res.meta.processNameUsed === 'Modul8' || !!res.meta.processNameUsed)
+      assert(res.meta.detectedPid === 12345)
+      assert(res.source === 'pid')
+      assert(res.logCount === 1)
+      assert(res.logs[0].message.includes('Test message'))
+      assert(called, 'log show must have been called')
+    } finally {
+      (iosUtils as any).execCommand = orig
+    }
+  })
+
+  it('falls back to broad when no appId', async () => {
+    const logOutput = '2026-03-31 09:21:20.085 SomeOther[222:333] <Info> Other: Hello'
+    const orig = (iosUtils as any).execCommand
+    try {
+      (iosUtils as any).execCommand = async function (args: string[]) {
+        if (args.includes('log') && args.includes('show')) return { output: logOutput, device: { platform: 'ios', id: 'booted' } }
+        throw new Error('Unexpected args: ' + JSON.stringify(args))
+      }
+      const obs = new iOSObserve()
+      const res = await obs.getLogs({ deviceId: 'booted' })
+      assert(res.source === 'broad')
+      assert(res.logCount === 1)
+    } finally {
+      (iosUtils as any).execCommand = orig
+    }
+  })
+})

package/test/manage/device/run-install-kmp.ts

@@ -1,18 +0,0 @@
-#!/usr/bin/env node
-import { ToolsManage } from '../../../dist/manage/index.js'
-import path from 'path'
-
-async function main() {
-  // Prefer a repo-local sample modul8 project if present, otherwise allow overriding via KMP_PROJECT env var
-  const defaultRelative = path.join(process.cwd(), '..', '..', '..', '..', 'test-fixtures', 'modul8')
-  const project = process.env.KMP_PROJECT || defaultRelative
-  console.log('Running KMP build+install for project', project)
-  // Use projectType=kmp and let handler pick android by default for KMP
-  // Request iOS explicitly for this run to test iOS build path
-  const res = await ToolsManage.buildAndInstallHandler({ platform: 'ios', projectPath: project, projectType: 'kmp', timeout: 600000, deviceId: undefined })
-  console.log(JSON.stringify(res, null, 2))
-  if (res.result && res.result.success) process.exit(0)
-  process.exit(1)
-}
-
-main().catch(e => { console.error(e); process.exit(2) })