mobile-debug-mcp 0.32.4 → 0.33.0

package/src/interact/android.ts

@@ -1,3 +1,5 @@
+import { evidenceDispatch } from '../observe/evidence.js'
+import { beforeInputDispatch } from './conditional-action.js'
 import { markDispatchStarted } from '../utils/operation-budget.js'
 import { TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js"
@@ -13,8 +15,9 @@ export class AndroidInteract {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
     try {
+      await beforeInputDispatch('android', deviceInfo.id)
       markDispatchStarted()
-      await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId, { timeout: timeoutMs })
+      await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId, { timeout: timeoutMs }))
       return { device: deviceInfo, success: true, x, y }
     } catch (e) {
       return { device: deviceInfo, success: false, x, y, error: e instanceof Error ? e.message : String(e) }
@@ -26,8 +29,9 @@ export class AndroidInteract {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
     try {
+      await beforeInputDispatch('android', deviceInfo.id)
       markDispatchStarted()
-      await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId, { timeout: timeoutMs })
+      await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId, { timeout: timeoutMs }))
       return { device: deviceInfo, success: true, start: [x1, y1], end: [x2, y2], duration }
     } catch (e) {
       return { device: deviceInfo, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) }
@@ -42,8 +46,9 @@ export class AndroidInteract {
       // Encode spaces as %s to ensure proper input handling by adb shell input text
       const encodedText = text.replace(/\s/g, '%s')
       // Note: 'input text' might fail with some characters or if keyboard isn't ready, but it's the standard ADB way.
+      await beforeInputDispatch('android', deviceInfo.id)
       markDispatchStarted()
-      await execAdb(['shell', 'input', 'text', encodedText], deviceId, { timeout: timeoutMs })
+      await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'input', 'text', encodedText], deviceId, { timeout: timeoutMs }))
       return { device: deviceInfo, success: true, text }
     } catch (e) {
       return { device: deviceInfo, success: false, text, error: e instanceof Error ? e.message : String(e) }
@@ -55,8 +60,9 @@ export class AndroidInteract {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
     try {
+      await beforeInputDispatch('android', deviceInfo.id)
       markDispatchStarted()
-      await execAdb(['shell', 'input', 'keyevent', '4'], deviceId, { timeout: timeoutMs })
+      await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'input', 'keyevent', '4'], deviceId, { timeout: timeoutMs }))
       return { device: deviceInfo, success: true }
     } catch (e) {
       return { device: deviceInfo, success: false, error: e instanceof Error ? e.message : String(e) }

package/src/interact/conditional-action.ts

@@ -0,0 +1,75 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { ActionConditionResult } from '../types.js'
+import type { ExpectedState } from '../server/condition-schema.js'
+import { ToolsObserve } from '../observe/index.js'
+import { getSnapshotSessionId, hasSnapshotBaseline } from '../observe/snapshot-metadata.js'
+import { runWithSeparateBudget } from '../utils/operation-budget.js'
+import { ToolsNetwork } from '../network/index.js'
+
+export interface ConditionalAction {
+  platform: 'android' | 'ios'
+  deviceId: string
+  expected: ExpectedState
+  result: ActionConditionResult
+}
+
+const context = new AsyncLocalStorage<ConditionalAction>()
+
+export function createConditionalAction(platform: 'android' | 'ios', deviceId: string, expected: ExpectedState): ConditionalAction {
+  return { platform, deviceId, expected, result: {
+    status: 'not_checked',
+    expected: { snapshot_session_id: expected.snapshotSessionId, snapshot_revision: expected.snapshotRevision },
+    observed: null, elapsed_ms: 0, reason: 'ACTION_NOT_REACHED'
+  } }
+}
+
+export function withConditionalAction<T>(condition: ConditionalAction, operation: () => Promise<T>) {
+  return context.run(condition, operation)
+}
+
+export function isConditionBlocked() {
+  const status = context.getStore()?.result.status
+  return status === 'mismatch' || status === 'unavailable'
+}
+
+// Guarded calls reset the observation window only when input is about to spawn.
+export function notifyActionStart() {
+  if (!context.getStore()) ToolsNetwork.notifyActionStart()
+}
+
+export function conditionFailureCode(condition: ConditionalAction) {
+  return condition.result.status === 'mismatch' ? 'PRECONDITION_FAILED' as const : 'PRECONDITION_UNAVAILABLE' as const
+}
+
+export async function beforeInputDispatch(platform: 'android' | 'ios', deviceId: string) {
+  const condition = context.getStore()
+  if (!condition) return
+  const started = performance.now()
+  const result = condition.result
+  result.status = 'unavailable'
+  delete result.reason
+  try {
+    if (platform !== condition.platform || deviceId !== condition.deviceId) result.reason = 'DEVICE_MISMATCH'
+    else if (condition.expected.snapshotSessionId !== getSnapshotSessionId()) result.reason = 'SESSION_MISMATCH'
+    else if (!hasSnapshotBaseline(`${platform}:${deviceId}`, condition.expected.snapshotRevision)) result.reason = 'BASELINE_UNAVAILABLE'
+    else {
+      const tree = await runWithSeparateBudget(condition.expected.timeoutMs ?? 15000, () =>
+        ToolsObserve.getUITreeHandler({ platform, deviceId })) as any
+      if (tree?.error) result.reason = 'OBSERVATION_FAILED'
+      else if (!tree || !Array.isArray(tree.elements) || !Number.isSafeInteger(tree.snapshot_revision) || tree.snapshot_revision < 1 ||
+          tree.snapshot_session_id !== getSnapshotSessionId() || !Number.isFinite(tree.captured_at_ms) || tree.captured_at_ms <= 0 ||
+          !tree.resolution || !Number.isFinite(tree.resolution.width) || !Number.isFinite(tree.resolution.height) ||
+          !(tree.resolution.width > 0) || !(tree.resolution.height > 0)) result.reason = 'OBSERVATION_INVALID'
+      else if (tree.device?.platform !== platform || tree.device?.id !== deviceId) result.reason = 'DEVICE_MISMATCH'
+      else {
+        result.observed = tree
+        result.status = tree.snapshot_revision === condition.expected.snapshotRevision ? 'matched' : 'mismatch'
+      }
+    }
+  } catch (error) {
+    result.reason = /TIMEOUT|timed out/i.test(String(error)) ? 'CONDITION_TIMEOUT' : 'OBSERVATION_FAILED'
+  }
+  result.elapsed_ms = performance.now() - started
+  if (result.status !== 'matched') throw new Error(conditionFailureCode(condition))
+  ToolsNetwork.notifyActionStart()
+}

package/src/interact/index.ts

@@ -1,3 +1,6 @@
+import { currentReadinessWait, observeReadinessWait, isDeviceUnavailable } from '../observe/readiness.js'
+import { readinessDelay } from '../observe/readiness-service.js'
+import { isConditionBlocked } from './conditional-action.js'
 import { remainingBudget } from '../utils/operation-budget.js'
 import { createHash } from 'crypto'
 import { AndroidInteract } from './android.js';
@@ -605,6 +608,7 @@ export class ToolsInteract {
   }
 
   private static async _captureFingerprint(platform: 'android' | 'ios', deviceId?: string): Promise<string | null> {
+    if (isConditionBlocked()) return null
     try {
       const fingerprint = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
       return fingerprint?.fingerprint ?? null
@@ -2491,7 +2495,8 @@ export class ToolsInteract {
     return { found: true, element: outEl, score: scoreVal, confidence: scoreVal, resolution }
   }
 
-  static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false }: { 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, singleObservation?: boolean, singleAttempt?: boolean, rejectAmbiguous?: boolean }) {
+  static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false, resolveTapTarget = false }: { 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, singleObservation?: boolean, singleAttempt?: boolean, rejectAmbiguous?: boolean, resolveTapTarget?: boolean }) {
+    const readinessTracker = currentReadinessWait()
     const overallStart = Date.now()
     const requestedIndex = typeof match?.index === 'number' ? match.index : null
     const requested = {
@@ -2559,7 +2564,11 @@ export class ToolsInteract {
           remainingBudget()
           totalPollCount++
           try {
+            const acquisitionStarted = Date.now()
             const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+            observeReadinessWait(tree, acquisitionStarted)
+            // A failed acquisition cannot establish that the requested tap target is absent.
+            if (resolveTapTarget && tree?.error && /ACTION_TIMEOUT|timed out/i.test(String(tree.error))) throw new Error('ACTION_TIMEOUT')
             const elements = (tree && Array.isArray(tree.elements)) ? tree.elements as any[] : []
 
             const matches: { el: any, idx: number }[] = []
@@ -2633,7 +2642,8 @@ export class ToolsInteract {
                 conditionMet = visibleFlag
               } else conditionMet = false
             } else if (condition === 'clickable') {
-              matchedElement = chosen ? (ToolsInteract._resolveActionableAncestor(elements, chosen as { el: UiElement, idx: number }) || chosen) : null
+              matchedElement = chosen ? (resolveTapTarget && (!ToolsInteract._isVisibleElement(chosen.el) || chosen.el.enabled === false)
+                ? chosen : ToolsInteract._resolveActionableAncestor(elements, chosen as { el: UiElement, idx: number }) || chosen) : null
               if (matchedElement) {
                 const b = matchedElement.el.bounds
                 const visibleFlag = !!matchedElement.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1])
@@ -2643,6 +2653,13 @@ export class ToolsInteract {
               } else conditionMet = false
             }
 
+            // Waiting for a label to exist/be visible is distinct from resolving its
+            // executable control. Reuse the clickable-wait ancestor policy without
+            // promoting hidden or disabled labels into an unrelated enabled target.
+            if (resolveTapTarget && conditionMet && matchedElement &&
+                ToolsInteract._isVisibleElement(matchedElement.el) && matchedElement.el.enabled !== false) {
+              matchedElement = ToolsInteract._resolveActionableAncestor(elements, matchedElement) ?? matchedElement
+            }
             const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android')
             const resolvedDeviceId = tree?.device?.id || deviceId
             lastMatchedCount = matchedCount
@@ -2656,7 +2673,7 @@ export class ToolsInteract {
             if (conditionMet && snapshotFresh) {
               if (matchedAt === null) matchedAt = now
               stableMatchCount++
-              if (stableMatchCount >= stableObservationCount) {
+              if (stableMatchCount >= stableObservationCount && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
                 const latency_ms = now - overallStart
                 const outEl = lastMatchedElement
 
@@ -2681,19 +2698,22 @@ export class ToolsInteract {
             }
 
           } catch (e) {
+            // Deadline expiry does not invalidate the last successfully observed state.
             if (e instanceof Error && e.message === 'ACTION_TIMEOUT') throw e
+            if (readinessTracker && !String(e).includes('READINESS_')) readinessTracker.unavailable()
+            if (readinessTracker && isDeviceUnavailable(e)) throw e
             // Non-fatal per-poll error; record and continue
-            console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e))
+            if (!readinessTracker) console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e))
           }
 
           if (singleAttempt) break
           // Sleep until next poll
-          await new Promise(r => setTimeout(r, effectivePoll || 50))
+          await (readinessTracker ? readinessDelay(effectivePoll || 50) : 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))
+          if (backoff > 0) await (readinessTracker ? readinessDelay(backoff) : new Promise(r => setTimeout(r, backoff)))
           continue
         }
 
@@ -2710,7 +2730,7 @@ export class ToolsInteract {
           : ` observed ${lastMatchedCount} match(es)`
         return {
           status: 'timeout',
-          error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
+          error: { code: readinessTracker ? 'TIMEOUT' : 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
           metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
           requested,
           observed
@@ -2718,16 +2738,17 @@ export class ToolsInteract {
       }
 
     } catch (err) {
-      if (err instanceof Error && err.message === 'ACTION_TIMEOUT') throw err
+      if (!readinessTracker && err instanceof Error && err.message === 'ACTION_TIMEOUT') throw err
+      if (readinessTracker && isDeviceUnavailable(err)) throw err
       const elapsed = Date.now() - overallStart
       return {
         status: 'timeout',
-        error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) },
+        error: { code: readinessTracker && String(err).includes('ACTION_TIMEOUT') ? 'TIMEOUT' : 'INTERNAL_ERROR', message: readinessTracker ? 'Readiness predicate wait did not complete' : err instanceof Error ? err.message : String(err) },
         metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
         requested,
         observed: {
           matched_count: lastMatchedCount,
-          condition_satisfied: false,
+          condition_satisfied: readinessTracker ? lastConditionSatisfied : false,
           selected_index: lastMatchedElement?.index ?? null,
           last_matched_element: lastMatchedElement
         }
@@ -2821,6 +2842,7 @@ export class ToolsInteract {
     scope?: 'screen' | 'subtree',
     target?: string | null
   }): Promise<WaitForUIChangeResponse> {
+    const readinessTracker = currentReadinessWait()
     const start = Date.now()
     const pollIntervalMs = 300
     const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300)
@@ -2844,7 +2866,10 @@ export class ToolsInteract {
 
     while (Date.now() - start < timeout_ms) {
       try {
+        if (readinessTracker) remainingBudget()
+        const acquisitionStarted = Date.now()
         const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+        observeReadinessWait(tree, acquisitionStarted)
         const scopedTree = ToolsInteract._resolveUiChangeScope(tree, scope, target)
         if (scopedTree.error) {
           lastScopeResolution = scopedTree.resolution
@@ -2892,7 +2917,7 @@ export class ToolsInteract {
             }
 
             const stableForMs = candidateSinceMs === null ? 0 : Date.now() - candidateSinceMs
-            if (stabilityWindow === 0 || stableForMs >= stabilityWindow) {
+            if ((stabilityWindow === 0 || stableForMs >= stabilityWindow) && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
                 return {
                   success: true,
                   observed_change: candidateObservedChange ?? observedChange,
@@ -2915,11 +2940,14 @@ export class ToolsInteract {
             candidateSinceMs = null
           }
         }
-      } catch {
-        // Keep polling until timeout; the observable surface should be best-effort.
+      } catch (error) {
+        if (readinessTracker && !String(error).includes('READINESS_')) readinessTracker.unavailable()
+        if (readinessTracker && isDeviceUnavailable(error)) throw error
+        if (readinessTracker && String(error).includes('ACTION_TIMEOUT')) { readinessTracker.deadline(); break }
+        // Default waits retain best-effort polling.
       }
 
-      await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+      await (readinessTracker ? readinessDelay(pollIntervalMs) : new Promise(resolve => setTimeout(resolve, pollIntervalMs)))
     }
 
     return {

package/src/interact/ios.ts

@@ -1,3 +1,5 @@
+import { evidenceDispatch } from '../observe/evidence.js'
+import { beforeInputDispatch } from './conditional-action.js'
 import { remainingBudget, markDispatchStarted } from '../utils/operation-budget.js'
 import { spawn } from "child_process"
 import { TapResponse, SwipeResponse } from "../types.js"
@@ -31,9 +33,11 @@ export class iOSInteract {
         args.push('--udid', targetUdid);
       }
 
-      await new Promise<void>((resolve, reject) => {
-        markDispatchStarted()
-        const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
+      await beforeInputDispatch('ios', device.id)
+      const timeout = remainingBudget() || undefined
+      markDispatchStarted()
+      await evidenceDispatch({ platform: 'ios', id: device.id }, () => new Promise<void>((resolve, reject) => {
+        const proc = spawn(getIdbCmd(), args, { timeout });
         let stderr = '';
         proc.stderr.on('data', d => stderr += d.toString());
         proc.on('close', code => {
@@ -41,7 +45,7 @@ export class iOSInteract {
             else reject(new Error(`idb ui tap failed: ${stderr}`));
         });
         proc.on('error', err => reject(err));
-      });
+      }));
 
       return { device, success: true, x, y };
     } catch (e) {
@@ -73,9 +77,11 @@ export class iOSInteract {
         args.push('--udid', targetUdid);
       }
 
-      await new Promise<void>((resolve, reject) => {
-        markDispatchStarted()
-        const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
+      await beforeInputDispatch('ios', device.id)
+      const timeout = remainingBudget() || undefined
+      markDispatchStarted()
+      await evidenceDispatch({ platform: 'ios', id: device.id }, () => new Promise<void>((resolve, reject) => {
+        const proc = spawn(getIdbCmd(), args, { timeout });
         let stderr = '';
         proc.stderr.on('data', d => stderr += d.toString());
         proc.on('close', code => {
@@ -83,7 +89,7 @@ export class iOSInteract {
           else reject(new Error(`idb ui swipe failed: ${stderr}`));
         });
         proc.on('error', err => reject(err));
-      });
+      }));
 
       return { device, success: true, start: [x1, y1], end: [x2, y2], duration };
     } catch (e) {

package/src/manage/android.ts

@@ -1,3 +1,4 @@
+import { evidenceDispatch } from '../observe/evidence.js'
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js'
 import { promises as fs } from 'fs'
 import { spawn } from 'child_process'
@@ -156,7 +157,7 @@ export class AndroidManage {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
     try {
       markDispatchStarted()
-      const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs })
+      const output = await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs }))
       const current = await new AndroidObserve().getCurrentScreen(deviceId).catch(() => null)
       return {
         device: deviceInfo,
@@ -182,7 +183,7 @@ export class AndroidManage {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
     try {
       markDispatchStarted()
-      await execAdb(['shell', 'am', 'force-stop', appId], deviceId)
+      await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'am', 'force-stop', appId], deviceId))
       return { device: deviceInfo, appTerminated: true }
     } catch (e: unknown) {
       const diagnostics = hasFiniteBudget() ? undefined : execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId)
@@ -215,7 +216,7 @@ export class AndroidManage {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
     try {
       markDispatchStarted()
-      const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId)
+      const output = await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'pm', 'clear', appId], deviceId))
       return { device: deviceInfo, dataCleared: output === 'Success' }
     } catch (e: unknown) {
       const diag = execAdbWithDiagnostics(['shell', 'pm', 'clear', appId], deviceId)

package/src/manage/ios.ts

@@ -1,3 +1,4 @@
+import { evidenceDispatch } from '../observe/evidence.js'
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js'
 import { promises as fs } from "fs"
 import { spawn, spawnSync } from "child_process"
@@ -316,7 +317,7 @@ export class iOSManage {
     validateBundleId(bundleId)
     try {
       markDispatchStarted()
-      const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)
+      const result = await evidenceDispatch({ platform: 'ios', id: deviceId }, () => execCommand(['simctl', 'launch', deviceId, bundleId], deviceId))
       const device = await getIOSDeviceMetadata(deviceId)
       const fingerprint = observe ? await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null) : null
       const pidMatch = result.output.match(/:\s*(\d+)\s*$/)
@@ -343,7 +344,7 @@ export class iOSManage {
     validateBundleId(bundleId)
     try {
       markDispatchStarted()
-      await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId)
+      await evidenceDispatch({ platform: 'ios', id: deviceId }, () => execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId))
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appTerminated: true }
     } catch (e: unknown) {

package/src/observe/android.ts

@@ -1,3 +1,4 @@
+import { captureEvidence } from './evidence.js'
 import { spawn } from "child_process"
 import { XMLParser } from "fast-xml-parser"
 import { GetLogsResponse, CaptureAndroidScreenResponse, GetUITreeResponse, GetCurrentScreenResponse, UIElement, DeviceInfo } from "../types.js"
@@ -11,14 +12,20 @@ import { deriveSnapshotMetadata } from "./snapshot-metadata.js"
 import { remainingBudget } from '../utils/operation-budget.js'
 import { createObservationMeasurement } from './performance-metrics.js'
 
-const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
+const activeLogStreams: Map<string, { proc: any, file: string, device?: { platform: 'android' | 'ios'; id: string } }> = new Map()
 
 export class AndroidObserve {
+  getLogStreamDevice(sessionId: string = 'default') { return activeLogStreams.get(sessionId)?.device ?? null }
+
   async getDeviceMetadata(appId: string, deviceId?: string): Promise<DeviceInfo> {
     return getAndroidDeviceMetadata(appId, deviceId);
   }
 
   async getUITree(deviceId?: string): Promise<GetUITreeResponse> {
+    return captureEvidence('ui_tree', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetUITree(deviceId))
+  }
+
+  private async collectGetUITree(deviceId?: string): Promise<GetUITreeResponse> {
     const measurement = createObservationMeasurement('android')
     let metadata
     try {
@@ -122,6 +129,10 @@ export class AndroidObserve {
   }
 
   async getLogs(filters: { appId?: string, deviceId?: string, pid?: number, tag?: string, level?: string, contains?: string, since_seconds?: number, limit?: number } = {}): Promise<GetLogsResponse> {
+    return captureEvidence('logs', { platform: 'android', id: filters.deviceId ?? '' }, () => this.collectGetLogs(filters))
+  }
+
+  private async collectGetLogs(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)
@@ -221,6 +232,10 @@ export class AndroidObserve {
   }
 
   async captureScreen(deviceId?: string): Promise<CaptureAndroidScreenResponse> {
+    return captureEvidence('screenshot', { platform: 'android', id: deviceId ?? '' }, () => this.collectCaptureScreen(deviceId))
+  }
+
+  private async collectCaptureScreen(deviceId?: string): Promise<CaptureAndroidScreenResponse> {
     const metadata = await getAndroidDeviceMetadata("", deviceId)
     const deviceInfo: DeviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
@@ -349,6 +364,10 @@ export class AndroidObserve {
   }
 
   async getCurrentScreen(deviceId?: string): Promise<GetCurrentScreenResponse> {
+    return captureEvidence('activity', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetCurrentScreen(deviceId))
+  }
+
+  private async collectGetCurrentScreen(deviceId?: string): Promise<GetCurrentScreenResponse> {
     const metadata = await getAndroidDeviceMetadata("", deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
@@ -410,13 +429,17 @@ export class AndroidObserve {
     }
   }
 
-  async getScreenFingerprint(deviceId?: string): Promise<{ fingerprint: string | null; activity?: string; error?: string }> {
+  async getScreenFingerprint(deviceId?: string): Promise<{ fingerprint: string | null; activity?: string; error?: string; captured_at_ms?: number }> {
+    return captureEvidence('fingerprint', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetScreenFingerprint(deviceId))
+  }
+
+  private async collectGetScreenFingerprint(deviceId?: string): Promise<{ fingerprint: string | null; activity?: string; error?: string; captured_at_ms?: number }> {
     try {
       const tree = await this.getUITree(deviceId)
       if (!tree || (tree as any).error) return { fingerprint: null, error: (tree as any).error }
 
       const current = await this.getCurrentScreen(deviceId).catch(() => null)
-      return computeScreenFingerprint(tree, current, 'android', 50)
+      return { ...computeScreenFingerprint(tree, current, 'android', 50), captured_at_ms: tree.captured_at_ms }
     } catch (e) {
       return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
     }
@@ -436,7 +459,7 @@ export class AndroidObserve {
         activeLogStreams.delete(sessionId)
       }
 
-      const args = ['logcat', `--pid=${pid}`, filter]
+      const args = [...(deviceId ? ['-s', deviceId] : []), 'logcat', `--pid=${pid}`, filter]
       const proc = spawn(getAdbCmd(), args)
 
       const tmpDir = process.env.TMPDIR || '/tmp'
@@ -463,10 +486,10 @@ export class AndroidObserve {
 
       proc.on('close', () => {
         stream.end()
-        activeLogStreams.delete(sessionId)
+        if (activeLogStreams.get(sessionId)?.proc === proc) activeLogStreams.delete(sessionId)
       })
 
-      activeLogStreams.set(sessionId, { proc, file })
+      activeLogStreams.set(sessionId, { proc, file, device: { platform: 'android', id: deviceId ?? '' } })
       return { success: true, stream_started: true }
     } catch (e) {
       return { success: false, error: e instanceof Error ? e.message : String(e) }
@@ -482,6 +505,10 @@ export class AndroidObserve {
   }
 
   async readLogStream(sessionId: string = 'default', limit: number = 100, since?: string) {
+    return captureEvidence('logs', this.getLogStreamDevice(sessionId), () => this.collectReadLogStream(sessionId, limit, since))
+  }
+
+  private async collectReadLogStream(sessionId: string = 'default', limit: number = 100, since?: string) {
     const entry = activeLogStreams.get(sessionId)
     let file: string | undefined
     if (entry && entry.file) file = entry.file