mobile-debug-mcp 0.34.0 → 0.36.0

package/src/system/ios-status.ts

@@ -0,0 +1,147 @@
+import { checkIOS } from './ios.js'
+import { getIdbCmd, getXcrunCmd } from '../utils/ios/utils.js'
+import { probeIdb } from '../utils/cli/idb/idb-helper.js'
+import type { HostOs, PlatformStatus, DiagnosticFailure, PlatformEntry } from './model.js'
+import { probeCommand, makeFailure, makeToolEntry, describeXcrunDiscovery, describeIdbDiscovery } from './probes.js'
+
+export function buildIOSPlatform(ios: Awaited<ReturnType<typeof checkIOS>>, hostSupported: boolean, hostOs: HostOs): PlatformEntry {
+  const platformUnsupported = !hostSupported || hostOs === 'linux' || hostOs === 'windows'
+  if (platformUnsupported) {
+    return {
+      status: 'unsupported',
+      tools: {},
+      providers: {},
+      capabilities: {},
+      devices: [],
+      failures: [
+        makeFailure('PLATFORM_UNAVAILABLE', 'ios', 'iOS tooling is only supported on macOS.', {
+          tool: null,
+          searchedLocations: [],
+          selectedProvider: null,
+          rawVersion: null,
+          remediation: ['Run Mobile Debug MCP on macOS for iOS toolchain discovery.']
+        })
+      ]
+    }
+  }
+
+  const { xcrunCmd, xcrunProbe, idbProbe, xcrunTool, idbTool, idbCompanionTool, lldbTool } = iosTools(ios, hostSupported, hostOs)
+  const simctlAvailable = !!ios.iosAvailable
+  const idbAvailable = !!idbProbe.ok
+  const bootedDevices = ios.iosDevices > 0
+    ? Array.from({ length: ios.iosDevices }, (_, index) => ({
+      id: `ios-simulator-${index + 1}`,
+      state: 'booted'
+    }))
+    : []
+
+  const { platformUnavailableFailure, deviceFailure } = iosFailures(platformUnsupported, simctlAvailable, bootedDevices.length, xcrunCmd, xcrunProbe.raw)
+  const selectedInstallProvider = idbAvailable ? 'idb' : simctlAvailable ? 'simctl' : null
+  const selectedDebugProvider = simctlAvailable ? 'LLDB' : null
+  const selectedDiscoveryProvider = idbAvailable ? 'idb' : simctlAvailable ? 'simctl' : null
+
+  const status: PlatformStatus = platformUnsupported
+    ? 'unsupported'
+    : !simctlAvailable
+      ? 'unavailable'
+      : !bootedDevices.length
+        ? 'partially_ready'
+        : 'ready'
+
+  const iosFailure = platformUnsupported
+    ? makeFailure('PLATFORM_UNAVAILABLE', 'ios', 'iOS tooling is only supported on macOS.', {
+      tool: null,
+      searchedLocations: [],
+      selectedProvider: null,
+      rawVersion: null,
+      remediation: ['Run Mobile Debug MCP on macOS for iOS toolchain discovery.']
+    })
+    : platformUnavailableFailure ?? deviceFailure ?? null
+
+  const failureList = [iosFailure].filter((value): value is DiagnosticFailure => value !== null)
+
+  return {
+    status,
+    tools: {
+      xcrun: xcrunTool,
+      idb: idbTool,
+      idb_companion: idbCompanionTool,
+      lldb: lldbTool
+    },
+    providers: {
+      idb: { available: idbAvailable, selected: selectedInstallProvider === 'idb', tool: 'idb' },
+      simctl: { available: simctlAvailable, selected: selectedInstallProvider === 'simctl', tool: 'xcrun' },
+      lldb: { available: simctlAvailable, selected: selectedDebugProvider === 'LLDB', tool: 'xcrun' }
+    },
+    capabilities: iosCapabilities(selectedDiscoveryProvider, selectedInstallProvider, selectedDebugProvider, simctlAvailable, bootedDevices.length, deviceFailure, iosFailure),
+    devices: bootedDevices,
+    failures: failureList
+  }
+}
+
+function iosTools(ios: Awaited<ReturnType<typeof checkIOS>>, hostSupported: boolean, hostOs: HostOs) {
+  const xcrunCmd = getXcrunCmd()
+  const xcrunProbe = ios.iosAvailable ? probeCommand(xcrunCmd, ['--version']) : { ok: false, raw: null, parsedVersion: null }
+  const idbCmd = getIdbCmd()
+  const idbProbe = hostSupported && hostOs === 'macos' ? probeIdb(idbCmd) : { ok: false, raw: null, parsedVersion: null }
+  const idbCompanionProbe = hostSupported && hostOs === 'macos' ? probeCommand('idb_companion', ['--version']) : { ok: false, raw: null, parsedVersion: null }
+  const xcrunTool = makeToolEntry(xcrunCmd, describeXcrunDiscovery(xcrunCmd).discoverySource, xcrunProbe.raw, xcrunProbe.ok ? 'valid' : 'invalid')
+  const idbTool = makeToolEntry(idbCmd, describeIdbDiscovery(idbCmd).discoverySource, idbProbe.raw, idbProbe.ok ? 'valid' : 'invalid')
+  const idbCompanionTool = makeToolEntry('idb_companion', 'PATH', idbCompanionProbe.raw, idbCompanionProbe.ok ? 'valid' : 'invalid')
+  const lldbTool = makeToolEntry('xcrun lldb', 'xcrun', xcrunProbe.raw, xcrunProbe.ok ? 'valid' : 'invalid')
+
+  return { xcrunCmd, xcrunProbe, idbProbe, xcrunTool, idbTool, idbCompanionTool, lldbTool }
+}
+
+function iosFailures(platformUnsupported: boolean, simctlAvailable: boolean, deviceCount: number, xcrunCmd: string, rawVersion: string | null) {
+  const platformUnavailableFailure = !platformUnsupported && !simctlAvailable
+    ? makeFailure('PLATFORM_UNAVAILABLE', 'ios', 'iOS tooling is unavailable on this host.', {
+      tool: 'xcrun',
+      searchedLocations: describeXcrunDiscovery(xcrunCmd).searchedLocations,
+      selectedProvider: null,
+      rawVersion: rawVersion,
+      remediation: ['Install Xcode Command Line Tools and ensure xcrun is on PATH.']
+    })
+    : null
+
+  const deviceFailure = simctlAvailable && !deviceCount
+    ? makeFailure('DEVICE_NOT_FOUND', 'ios', 'No iOS simulators are booted.', {
+      tool: 'simctl',
+      searchedLocations: ['xcrun simctl list devices booted --json'],
+      selectedProvider: 'simctl',
+      rawVersion: rawVersion,
+      remediation: ['Boot a simulator in Xcode or via xcrun simctl boot.']
+    })
+    : null
+
+  return { platformUnavailableFailure, deviceFailure }
+}
+
+function iosCapabilities(selectedDiscoveryProvider: string | null, selectedInstallProvider: string | null, selectedDebugProvider: string | null, simctlAvailable: boolean, deviceCount: number, deviceFailure: DiagnosticFailure | null, iosFailure: DiagnosticFailure | null): PlatformEntry['capabilities'] {
+  const applicationCapability = {
+    availability: !!selectedInstallProvider && deviceCount > 0,
+    selectedProvider: selectedInstallProvider,
+    blockingFailure: selectedInstallProvider && deviceCount > 0 ? null : deviceFailure ?? iosFailure
+  }
+  return {
+    device_discovery: {
+      availability: !!selectedDiscoveryProvider,
+      selectedProvider: selectedDiscoveryProvider,
+      blockingFailure: selectedDiscoveryProvider ? null : iosFailure
+    },
+    install_app: { ...applicationCapability },
+    launch_app: { ...applicationCapability },
+    ui_interaction: { ...applicationCapability },
+    screenshot: { ...applicationCapability },
+    log_capture: {
+      availability: simctlAvailable && deviceCount > 0,
+      selectedProvider: simctlAvailable ? 'simctl' : null,
+      blockingFailure: simctlAvailable && deviceCount > 0 ? null : deviceFailure ?? iosFailure
+    },
+    debug: {
+      availability: !!selectedDebugProvider,
+      selectedProvider: selectedDebugProvider,
+      blockingFailure: selectedDebugProvider ? null : iosFailure
+    }
+  }
+}

package/src/system/ios.ts

@@ -8,19 +8,12 @@ export async function checkIOS() {
   try {
     const xcrun = getXcrunCmd()
     try {
-      execSync(`${xcrun} --version`, { stdio: ['ignore','pipe','ignore'], timeout: 1500 })
+      execSync(`${xcrun} --version`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500 })
       iosAvailable = true
       try {
-        const simOut = execSync(`${xcrun} simctl list devices booted --json`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore','pipe','ignore'] })
+        const simOut = execSync(`${xcrun} simctl list devices booted --json`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] })
         try {
-          const data = JSON.parse(simOut)
-          type SimDevice = { state?: string }
-          let count = 0
-          for (const k in data.devices) {
-            const arr = data.devices[k]
-            if (Array.isArray(arr)) count += arr.filter((d: SimDevice) => (d.state || '').toLowerCase() === 'booted').length
-          }
-          iosDevices = count
+          iosDevices = countBooted(simOut)
         } catch {
           // Some xcrun builds include extra text around the JSON response.
           // Fall back to counting explicit booted state markers so readiness remains deterministic.
@@ -33,3 +26,14 @@ export async function checkIOS() {
   } catch (e: unknown) { console.debug('[get_system_status] xcrun check failed: ' + String(e)) }
   return { iosAvailable, iosDevices, issues }
 }
+
+function countBooted(simOut: string) {
+  const data = JSON.parse(simOut)
+  type SimDevice = { state?: string }
+  let count = 0
+  for (const k in data.devices) {
+    const arr = data.devices[k]
+    if (Array.isArray(arr)) count += arr.filter((d: SimDevice) => (d.state || '').toLowerCase() === 'booted').length
+  }
+  return count
+}

package/src/system/model.ts

@@ -0,0 +1,41 @@
+
+export type HostOs = 'macos' | 'linux' | 'windows' | 'freebsd' | 'openbsd' | 'netbsd' | 'sunos' | 'unknown'
+
+export type PlatformStatus = 'ready' | 'partially_ready' | 'unavailable' | 'unsupported'
+
+export type ValidationStatus = 'valid' | 'invalid' | 'missing' | 'unsupported' | 'unknown'
+
+export interface DiagnosticFailure {
+  code: string
+  platform: 'android' | 'ios'
+  tool: string | null
+  message: string
+  searchedLocations: string[]
+  selectedProvider: string | null
+  rawVersion: string | null
+  remediation: string[]
+}
+
+export interface ToolEntry {
+  resolvedPath: string | null
+  discoverySource: string | null
+  parsedVersion: string | null
+  rawVersionOutput: string | null
+  validationStatus: ValidationStatus
+}
+
+export interface CapabilityEntry {
+  probeRequired?: string
+  availability: boolean
+  selectedProvider: string | null
+  blockingFailure: DiagnosticFailure | null
+}
+
+export interface PlatformEntry {
+  status: PlatformStatus
+  tools: Record<string, ToolEntry>
+  providers: Record<string, { available: boolean; selected: boolean; tool: string | null; probeRequired?: string }>
+  capabilities: Record<string, CapabilityEntry>
+  devices: Array<Record<string, unknown>>
+  failures: DiagnosticFailure[]
+}

package/src/system/probes.ts

@@ -0,0 +1,114 @@
+import { spawnSync } from 'child_process'
+import path from 'path'
+import type { HostOs, ValidationStatus, DiagnosticFailure, ToolEntry } from './model.js'
+
+export function normalizeHostOs(platform: NodeJS.Platform): HostOs {
+  switch (platform) {
+    case 'darwin':
+      return 'macos'
+    case 'linux':
+      return 'linux'
+    case 'win32':
+      return 'windows'
+    case 'freebsd':
+    case 'openbsd':
+    case 'netbsd':
+    case 'sunos':
+      return platform
+    default:
+      return 'unknown'
+  }
+}
+
+export function isSupportedHost(hostOs: HostOs): boolean {
+  return hostOs === 'macos' || hostOs === 'linux' || hostOs === 'windows'
+}
+
+export function firstVersionToken(raw: string | null | undefined): string | null {
+  if (!raw) return null
+  const match = String(raw).match(/(\d+(?:\.\d+)+|\d+)/)
+  return match?.[1] ?? null
+}
+
+export function probeCommand(command: string, args: string[], timeoutMs = 2000): { ok: boolean, raw: string | null, parsedVersion: string | null } {
+  try {
+    const result = spawnSync(command, args, { encoding: 'utf8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'pipe'] })
+    const raw = `${result.stdout || ''}${result.stderr || ''}`.trim() || null
+    return {
+      ok: result.status === 0,
+      raw,
+      parsedVersion: firstVersionToken(raw)
+    }
+  } catch {
+    return { ok: false, raw: null, parsedVersion: null }
+  }
+}
+
+export function makeFailure(
+  code: string,
+  platform: 'android' | 'ios',
+  message: string,
+  opts: Partial<DiagnosticFailure> = {}
+): DiagnosticFailure {
+  return {
+    code,
+    platform,
+    tool: opts.tool ?? null,
+    message,
+    searchedLocations: opts.searchedLocations ?? [],
+    selectedProvider: opts.selectedProvider ?? null,
+    rawVersion: opts.rawVersion ?? null,
+    remediation: opts.remediation ?? []
+  }
+}
+
+export function makeToolEntry(
+  resolvedPath: string | null,
+  discoverySource: string | null,
+  rawVersionOutput: string | null,
+  validationStatus: ValidationStatus
+): ToolEntry {
+  return {
+    resolvedPath,
+    discoverySource,
+    parsedVersion: firstVersionToken(rawVersionOutput),
+    rawVersionOutput,
+    validationStatus
+  }
+}
+
+export function describeAdbDiscovery(adbCmd: string): { discoverySource: string | null, searchedLocations: string[] } {
+  const searchedLocations: string[] = ['ADB_PATH', 'ANDROID_SDK_ROOT/platform-tools/adb', 'ANDROID_HOME/platform-tools/adb', '~/Library/Android/sdk/platform-tools/adb', 'PATH']
+  if (process.env.ADB_PATH && process.env.ADB_PATH.trim()) return { discoverySource: 'ADB_PATH', searchedLocations }
+  if (process.env.ANDROID_SDK_ROOT) return { discoverySource: 'ANDROID_SDK_ROOT', searchedLocations }
+  if (process.env.ANDROID_HOME) return { discoverySource: 'ANDROID_HOME', searchedLocations }
+  if (adbCmd.includes('Library/Android/sdk')) return { discoverySource: 'HOME_SDK', searchedLocations }
+  if (adbCmd === 'adb') return { discoverySource: 'PATH_OR_FALLBACK', searchedLocations }
+  return { discoverySource: 'PATH', searchedLocations }
+}
+
+export function describeXcrunDiscovery(xcrunCmd: string): { discoverySource: string | null, searchedLocations: string[] } {
+  const searchedLocations: string[] = ['XCRUN_PATH', 'PATH']
+  if (process.env.XCRUN_PATH && process.env.XCRUN_PATH.trim()) return { discoverySource: 'XCRUN_PATH', searchedLocations }
+  return { discoverySource: xcrunCmd === 'xcrun' ? 'PATH' : 'PATH', searchedLocations }
+}
+
+export function describeIdbDiscovery(idbCmd: string): { discoverySource: string | null, searchedLocations: string[] } {
+  const searchedLocations: string[] = ['MCP_IDB_PATH', 'IDB_PATH', 'mcp.config.json', '~/.mcp/config.json', 'PATH', '/opt/homebrew/bin/idb', '/usr/local/bin/idb']
+  if (process.env.MCP_IDB_PATH && process.env.MCP_IDB_PATH.trim()) return { discoverySource: 'MCP_IDB_PATH', searchedLocations }
+  if (process.env.IDB_PATH && process.env.IDB_PATH.trim()) return { discoverySource: 'IDB_PATH', searchedLocations }
+  return { discoverySource: idbCmd === 'idb' ? 'PATH_OR_FALLBACK' : 'PATH', searchedLocations }
+}
+
+export function describeJavaDiscovery(javaHome: string | null): { discoverySource: string | null, searchedLocations: string[] } {
+  const searchedLocations: string[] = ['GRADLE_JAVA_HOME', 'JAVA_HOME', 'GRADLE_HOME', 'detectJavaHome']
+  if (process.env.GRADLE_JAVA_HOME && process.env.GRADLE_JAVA_HOME.trim()) return { discoverySource: 'GRADLE_JAVA_HOME', searchedLocations }
+  if (process.env.JAVA_HOME && process.env.JAVA_HOME.trim()) return { discoverySource: 'JAVA_HOME', searchedLocations }
+  if (process.env.GRADLE_HOME && process.env.GRADLE_HOME.trim()) return { discoverySource: 'GRADLE_HOME', searchedLocations }
+  return { discoverySource: javaHome ? 'detected' : null, searchedLocations }
+}
+
+export function resolveJavaBinaryPath(javaHome: string, hostOs: HostOs): string {
+  const javaBinary = hostOs === 'windows' ? 'java.exe' : 'java'
+  return path.join(javaHome, 'bin', javaBinary)
+}

package/src/system/status-summary.ts

@@ -0,0 +1,47 @@
+import { checkGradle } from './gradle.js'
+import type { PlatformEntry } from './model.js'
+
+export function buildLegacySummary(androidStatus: PlatformEntry, iosStatus: PlatformEntry, gradle: Awaited<ReturnType<typeof checkGradle>>) {
+  const androidReady = androidStatus.status === 'ready'
+  const iosReady = iosStatus.status === 'ready'
+  const gradleReady = (gradle.issues || []).length === 0
+  const overallStatus = (androidReady || iosReady || gradleReady)
+    ? ((androidReady && iosReady && gradleReady) ? 'ready' : 'degraded')
+    : 'blocked'
+
+  return {
+    overall: overallStatus,
+    android: {
+      ready: androidReady,
+      summary: androidStatus.status === 'ready'
+        ? `${androidStatus.devices.length} Android device(s) connected; log access available`
+        : androidStatus.status === 'partially_ready'
+          ? 'Android toolchain available but device-dependent capabilities are limited'
+          : androidStatus.status === 'unsupported'
+            ? 'Android unsupported on this host'
+            : 'ADB unavailable',
+      blockers: androidStatus.failures.map((failure) => failure.message)
+    },
+    ios: {
+      ready: iosReady,
+      summary: iosStatus.status === 'ready'
+        ? `${iosStatus.devices.length} iOS simulator(s) booted`
+        : iosStatus.status === 'partially_ready'
+          ? 'iOS toolchain available but device-dependent capabilities are limited'
+          : iosStatus.status === 'unsupported'
+            ? 'iOS unsupported on this host'
+            : 'xcrun unavailable',
+      blockers: iosStatus.failures.map((failure) => failure.message)
+    },
+    gradle: {
+      ready: gradleReady,
+      summary: !gradle.gradleJavaHome
+        ? 'No explicit Gradle JDK override detected'
+        : gradleReady
+          ? `Gradle JDK configured at ${gradle.gradleJavaHome}`
+          : `Gradle JDK override invalid: ${gradle.gradleJavaHome}`,
+      blockers: gradle.issues || [],
+      suggestedFixes: gradle.suggestedFixes || []
+    }
+  }
+}

package/src/system/unsupported-status.ts

@@ -0,0 +1,55 @@
+import type { HostOs } from './model.js'
+import { makeFailure } from './probes.js'
+
+export function buildUnsupportedHostStatus(hostOs: HostOs) {
+  const failureMessage = `Host operating system '${hostOs}' is not supported.`
+  const remediation = ['Run Mobile Debug MCP on macOS, Linux, or Windows.']
+  const failureAndroid = makeFailure('HOST_OS_UNSUPPORTED', 'android', failureMessage, {
+    remediation
+  })
+  const failureIos = makeFailure('HOST_OS_UNSUPPORTED', 'ios', failureMessage, {
+    remediation
+  })
+
+  return {
+    success: false,
+    status: 'blocked',
+    adbAvailable: false,
+    adbVersion: '',
+    devices: 0,
+    deviceStates: '',
+    logsAvailable: false,
+    envValid: false,
+    issues: [failureMessage],
+    appInstalled: undefined,
+    iosAvailable: false,
+    iosDevices: 0,
+    gradleJavaHome: undefined,
+    gradleValid: false,
+    gradleFilesChecked: [],
+    gradleSuggestedFixes: [],
+    host: { os: hostOs, supported: false },
+    android: {
+      status: 'unsupported',
+      tools: {},
+      providers: {},
+      capabilities: {},
+      devices: [],
+      failures: [failureAndroid]
+    },
+    ios: {
+      status: 'unsupported',
+      tools: {},
+      providers: {},
+      capabilities: {},
+      devices: [],
+      failures: [failureIos]
+    },
+    summary: {
+      overall: 'blocked',
+      android: { ready: false, summary: `Host operating system '${hostOs}' is not supported.`, blockers: [failureMessage] },
+      ios: { ready: false, summary: `Host operating system '${hostOs}' is not supported.`, blockers: [failureMessage] },
+      gradle: { ready: false, summary: 'Gradle status unavailable on unsupported host', blockers: [], suggestedFixes: [] }
+    }
+  }
+}

package/src/types.ts

@@ -1,9 +1,13 @@
+export type { UIElementState, SelectorConfidence, UIResolutionSelector, UIElementSemanticMetadata, LoadingState, SnapshotDelta, StateDelta, UIElement, ReadinessSummary } from './contracts/ui.js'
+import type { UIElementState, UIResolutionSelector, UIElementSemanticMetadata, LoadingState, SnapshotDelta, StateDelta, UIElement, ReadinessSummary } from './contracts/ui.js'
 export interface DeviceInfo {
   platform: string;
   id: string;
   osVersion: string;
   model: string;
   simulator: boolean;
+  appInstalled?: boolean;
+  booted?: boolean;
 }
 
 export interface StartAppResponse {
@@ -20,14 +24,14 @@ export interface StartAppResponse {
     matchedTarget?: boolean | null;
   };
   error?: string;
-  diagnostics?: any;
+  diagnostics?: unknown;
 }
 
 export interface TerminateAppResponse {
   device: DeviceInfo;
   appTerminated: boolean;
   error?: string;
-  diagnostics?: any;
+  diagnostics?: unknown;
 }
 
 export interface RestartAppResponse {
@@ -46,14 +50,14 @@ export interface RestartAppResponse {
   terminatedBeforeRestart?: boolean;
   terminateError?: string;
   error?: string;
-  diagnostics?: any;
+  diagnostics?: unknown;
 }
 
 export interface ResetAppDataResponse {
   device: DeviceInfo;
   dataCleared: boolean;
   error?: string;
-  diagnostics?: any;
+  diagnostics?: unknown;
 }
 
 export interface StructuredLogEntry {
@@ -71,7 +75,7 @@ export interface GetLogsResponse {
   // 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>;
+  meta?: Record<string, unknown>;
 }
 
 export interface GetCrashResponse {
@@ -79,43 +83,8 @@ export interface GetCrashResponse {
   crashes: string[];
 }
 
-export interface UIElementState {
-  checked?: boolean | null;
-  selected?: boolean | string | { id: string; label?: string } | null;
-  focused?: boolean | null;
-  expanded?: boolean | null;
-  enabled?: boolean | null;
-  text_value?: string | null;
-  value?: number | string | null;
-  raw_value?: number | string | null;
-  value_range?: {
-    min: number;
-    max: number;
-    step?: number | null;
-  } | null;
-  step?: number | null;
-}
-
-export interface SelectorConfidence {
-  score: number;
-  reason: string;
-}
-
-export interface UIResolutionSelector {
-  value: string | null;
-  confidence: SelectorConfidence | null;
-}
-
-export interface UIElementSemanticMetadata {
-  is_clickable: boolean;
-  is_container: boolean;
-  semantic_role?: 'slider' | 'stepper' | 'dropdown' | 'segmented_control' | 'custom_adjustable' | 'composite_control' | null;
-  supported_actions?: string[] | null;
-  adjustable?: boolean | null;
-  state_shape?: 'continuous' | 'discrete' | 'semantic' | null;
-}
-
 export type TraceStage = 'resolve' | 'execute' | 'verify' | 'stabilize' | 'recover';
+
 export type TraceResult = 'success' | 'failure' | 'retry';
 
 export interface TraceStep {
@@ -148,35 +117,11 @@ export type RecoveryStrategy =
   | 'retry_adjustment'
   | 'step_back';
 
-export interface LoadingState {
-  active: boolean;
-  signal: string;
-  source: string;
-}
-
-export interface SnapshotDelta {
-  previous_snapshot_revision: number | null;
-  added_elements: number;
-  removed_elements: number;
-  mutated_elements: number;
-  total_elements: number;
-}
-
-export interface StateDelta {
-  base_snapshot_revision: number | null;
-  snapshot_revision: number;
-  added: UIElement[];
-  removed: Array<{ stable_id?: string; resourceId?: string; contentDescription?: string; text?: string; index: number }>;
-  changed: UIElement[];
-  truncated: boolean;
-  omitted_changes?: number;
-}
-
 export interface CaptureAndroidScreenResponse {
   device: DeviceInfo;
   screenshot: string; // base64 encoded string
   screenshot_mime?: string; // e.g. image/webp, image/jpeg, image/png
-  screenshot_fallback?: string; // optional fallback base64 (e.g., jpeg)
+  screenshot_fallback?: string | null; // optional fallback base64 (e.g., jpeg)
   screenshot_fallback_mime?: string;
   resolution: {
     width: number;
@@ -188,7 +133,7 @@ export interface CaptureIOSScreenshotResponse {
   device: DeviceInfo;
   screenshot: string; // base64 encoded string
   screenshot_mime?: string; // e.g. image/webp, image/jpeg, image/png
-  screenshot_fallback?: string; // optional fallback base64 (e.g., jpeg)
+  screenshot_fallback?: string | null; // optional fallback base64 (e.g., jpeg)
   screenshot_fallback_mime?: string;
   resolution: {
     width: number;
@@ -196,27 +141,6 @@ export interface CaptureIOSScreenshotResponse {
   };
 }
 
-export interface UIElement {
-  text: string | null;
-  contentDescription: string | null;
-  type: string;
-  clickable: boolean;
-  enabled: boolean;
-  visible: boolean;
-  bounds: [number, number, number, number];
-  resourceId: string | null;
-  parentId?: number;
-  children?: number[];
-  center?: [number, number];
-  depth?: number;
-  state?: UIElementState | null;
-  stable_id?: string | null;
-  role?: string | null;
-  test_tag?: string | null;
-  selector?: UIResolutionSelector | null;
-  semantic?: UIElementSemanticMetadata | null;
-}
-
 export interface GetUITreeResponse {
   readiness?: ReadinessSummary;
   device: DeviceInfo;
@@ -234,20 +158,6 @@ export interface GetUITreeResponse {
   error?: string;
 }
 
-export interface ReadinessSummary {
-  state: 'loading' | 'transitioning' | 'settled' | 'unknown' | 'unresponsive' | 'debugger_paused';
-  scope: 'device_ui';
-  basis: 'observed' | 'heuristic' | 'insufficient';
-  captured_at_ms: number | null;
-  sample_count: number;
-  stable_for_ms: number;
-  snapshot_session_id: string | null;
-  snapshot_revision: number | null;
-  evidence: Array<{ code: string; source: string; captured_at_ms: number | null; snapshot_revision: number | null }>;
-  limitations: string[];
-  capabilities: { loading: boolean; transitioning: boolean; settled: boolean; unresponsive: boolean; debugger_paused: boolean };
-}
-
 export interface GetCurrentScreenResponse {
   device: DeviceInfo;
   package: string;
@@ -274,7 +184,7 @@ export interface CaptureDebugSnapshotRawResponse {
   fingerprint: string | null;
   screenshot: string | null;
   ui_tree: GetUITreeResponse | null;
-  logs: StructuredLogEntry[];
+  logs: import('./observe/snapshot-logs.js').SnapshotLogEntry[];
   loading_state?: LoadingState | null;
   device?: DeviceInfo;
   screenshot_error?: string;
@@ -441,7 +351,7 @@ export interface ActionConditionResult {
   observed: GetUITreeResponse | null;
   elapsed_ms: number;
   reason?: 'BASELINE_UNAVAILABLE' | 'SESSION_MISMATCH' | 'DEVICE_MISMATCH' |
-    'OBSERVATION_FAILED' | 'OBSERVATION_INVALID' | 'CONDITION_TIMEOUT' | 'ACTION_NOT_REACHED';
+  'OBSERVATION_FAILED' | 'OBSERVATION_INVALID' | 'CONDITION_TIMEOUT' | 'ACTION_NOT_REACHED';
 }
 
 export interface ActionExecutionResult {
@@ -505,7 +415,7 @@ export interface ExpectElementVisibleResponse {
   element?: ActionTargetResolved | null;
   observed?: {
     status?: string;
-    matched_count?: number;
+    matched_count?: number | null;
     condition_satisfied?: boolean;
     selected_index?: number | null;
     last_matched_element?: ActionTargetResolved | null;
@@ -615,5 +525,5 @@ export interface InstallAppResponse {
   installed: boolean;
   output?: string;
   error?: string;
-  diagnostics?: any;
+  diagnostics?: unknown;
 }