mobile-debug-mcp 0.33.0 → 0.35.0

package/src/observe/evidence.ts

@@ -25,6 +25,7 @@ interface Acquisition {
   startSequence: number; endSequence: number; overlapping: boolean; reused: boolean
 }
 interface EvidenceContext {
+  systemTraceId?: string
   correlationId: string; action: ActionRecord | null; ref?: ActionRef
   device: EvidenceDevice | null; start: Stamp; end: Stamp | null; verification: Stamp | null
   observations: Acquisition[]; isAction: boolean; children: EvidenceContext[]
@@ -37,7 +38,13 @@ const orders = new Map<string, DeviceOrder>()
 const stamp = (): Stamp => ({ wall: Date.now(), mono: performance.now() })
 const deviceKey = (d: EvidenceDevice) => `${d.platform}:${d.id}`
 const sameDevice = (a: EvidenceDevice | null, b: EvidenceDevice | null) => !!a && !!b && deviceKey(a) === deviceKey(b)
-function validDevice(d: any): EvidenceDevice | null {
+interface EvidencePayload {
+  device?: unknown; error?: string; meta?: { error?: string }; success?: boolean; fingerprint?: string | null
+  captured_at_ms?: number; snapshot_session_id?: string; snapshot_revision?: number
+  logs?: Array<{ timestamp?: unknown; _iso?: unknown }>; entries?: Array<{ timestamp?: unknown; _iso?: unknown }>
+}
+function validDevice(value: unknown): EvidenceDevice | null {
+  const d = value as EvidenceDevice | null
   return d && ['android', 'ios'].includes(d.platform) && typeof d.id === 'string' && d.id && !['default', 'booted'].includes(d.id)
     ? { platform: d.platform, id: d.id } : null
 }
@@ -67,11 +74,17 @@ function prune() {
 export function validateActionRef(value: unknown): ActionRef | undefined {
   if (value === undefined) return undefined
   if (!value || typeof value !== 'object' || Array.isArray(value) ||
-      Object.keys(value).some(key => !['sessionId', 'actionId'].includes(key))) throw new Error('INVALID_ARGUMENT: invalid actionRef')
+    Object.keys(value).some(key => !['sessionId', 'actionId'].includes(key))) throw new Error('INVALID_ARGUMENT: invalid actionRef')
   const ref = value as ActionRef
   for (const v of [ref.sessionId, ref.actionId]) if (typeof v !== 'string' || v.length < 1 || v.length > 128) throw new Error('INVALID_ARGUMENT: invalid actionRef')
   return { sessionId: ref.sessionId, actionId: ref.actionId }
 }
+export function evidenceSessionId() { return sessionId }
+export function currentEvidenceCorrelationId() { return context.getStore()?.correlationId }
+export function bindSystemTrace(traceId: string) {
+  const current = context.getStore()
+  if (current) current.systemTraceId = traceId
+}
 export function currentEvidenceActionId() { return context.getStore()?.action?.id }
 export function bindEvidenceDevice(device: { platform: string; id: string }) {
   const current = context.getStore()
@@ -107,11 +120,13 @@ export function omitEvidence(kind: Kind) {
   const current = context.getStore()
   if (!current) return
   const start = stamp()
-  current.observations.push({ value: {
-    evidence_id: randomUUID(), kind, status: 'omitted', capture_started_at_ms: null,
-    capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
-    freshness: kind === 'logs' ? 'not_applicable' : 'unknown', freshness_reasons: [], device: current.device
-  }, start, end: null, order: null, startSequence: 0, endSequence: 0, overlapping: false, reused: false })
+  current.observations.push({
+    value: {
+      evidence_id: randomUUID(), kind, status: 'omitted', capture_started_at_ms: null,
+      capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
+      freshness: kind === 'logs' ? 'not_applicable' : 'unknown', freshness_reasons: [], device: current.device
+    }, start, end: null, order: null, startSequence: 0, endSequence: 0, overlapping: false, reused: false
+  })
 }
 export async function captureEvidence<T>(kind: Kind, device: EvidenceDevice | null, operation: () => Promise<T>): Promise<T> {
   const current = context.getStore()
@@ -120,42 +135,19 @@ export async function captureEvidence<T>(kind: Kind, device: EvidenceDevice | nu
   if (target) bindEvidenceDevice(target)
   const order = orderFor(target)
   const start = stamp()
-  const acquisition: Acquisition = { value: {
-    evidence_id: randomUUID(), kind, status: 'failed', capture_started_at_ms: start.wall,
-    capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
-    freshness: 'unknown', freshness_reasons: [], device: target
-  }, start, end: null, order, startSequence: order?.sequence ?? 0,
-  endSequence: 0, overlapping: !!order?.active, reused: false }
+  const acquisition: Acquisition = {
+    value: {
+      evidence_id: randomUUID(), kind, status: 'failed', capture_started_at_ms: start.wall,
+      capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
+      freshness: 'unknown', freshness_reasons: [], device: target
+    }, start, end: null, order, startSequence: order?.sequence ?? 0,
+    endSequence: 0, overlapping: !!order?.active, reused: false
+  }
   current.observations.push(acquisition)
   try {
-    const result = await operation() as any
-    const value = acquisition.value
-    const resolved = validDevice(result?.device) ?? target
-    value.device = resolved
-    if (resolved) bindEvidenceDevice(resolved)
-    const failure = result?.error ?? result?.meta?.error
-    value.status = failure || result?.success === false || (kind === 'fingerprint' && !result?.fingerprint) ? 'failed' : 'captured'
-    if (failure) value.error = failure
-    const source = result?.captured_at_ms
-    if (Number.isFinite(source) && source > 0) {
-      value.source_captured_at_ms = source
-      acquisition.reused = source < start.wall
-    }
-    if (kind === 'ui_tree') {
-      value.snapshot_session_id = result?.snapshot_session_id
-      value.snapshot_revision = result?.snapshot_revision
-    }
-    if (kind === 'logs') {
-      const entries = result?.logs ?? result?.entries ?? []
-      const times = entries.map((e: any) => {
-        const t = e?.timestamp ?? e?._iso
-        return typeof t === 'number' ? t : typeof t === 'string' ? Date.parse(t) : NaN
-      }).filter((t: number) => Number.isFinite(t)) as number[]
-      value.clock = 'device_or_unknown'; value.event_time_comparable = false
-      value.earliest_entry_at_ms = times.length ? times.reduce((a, b) => Math.min(a, b)) : null
-      value.latest_entry_at_ms = times.length ? times.reduce((a, b) => Math.max(a, b)) : null
-    }
-    return result
+    const original = await operation()
+    recordObservationResult(acquisition, original as EvidencePayload | null, kind, target, start)
+    return original
   } catch (error) {
     acquisition.value.error = error instanceof Error ? error.message : String(error)
     throw error
@@ -181,46 +173,28 @@ function assemble(current: EvidenceContext) {
   const link = association(current)
   const action = link.association === 'unavailable' ? null : current.action
   const clockChanged = end.wall < current.start.wall
-  const observations = current.observations.map(a => {
-    const v = { ...a.value, freshness_reasons: [] as string[] }
-    if (v.status === 'omitted') return v
-    const componentAction = sameDevice(v.device, action?.device ?? null) ? action : null
-    const sourceMono = a.end && v.source_captured_at_ms !== null ? a.end.mono + v.source_captured_at_ms - a.end.wall : a.end?.mono
-    const reason = (freshness: Freshness, code: string) => { v.freshness = freshness; v.freshness_reasons.push(code) }
-    if (v.kind === 'logs') reason('unknown', 'DEVICE_CLOCK_UNVERIFIED')
-    else if (clockChanged || (a.end && a.end.wall < a.start.wall)) reason('unknown', 'CLOCK_DISCONTINUITY')
-    else if (v.source_captured_at_ms !== null && a.end && v.source_captured_at_ms > a.end.wall) reason('unknown', 'CLOCK_DISCONTINUITY')
-    else if (!v.device || !a.order || orders.get(deviceKey(v.device)) !== a.order || v.status !== 'captured' || !a.end) reason('unknown', 'CAPTURE_TIME_UNKNOWN')
-    else if (componentAction?.dispatchStart && sourceMono !== undefined && sourceMono < componentAction.dispatchStart.mono) reason('stale', 'BEFORE_ACTION')
-    else if (a.order && (a.order.sequence > a.endSequence || (a.reused && sourceMono !== undefined && sourceMono < a.order.lastStarted))) reason('stale', 'SUPERSEDED_BY_ACTION')
-    else if (a.overlapping) reason('unknown', 'OVERLAPPING_ACTION')
-    else if (a.reused) reason('unknown', 'REUSED_OBSERVATION')
-    else { v.freshness = 'fresh' }
-    if (!clockChanged && a.end && a.end.wall >= a.start.wall && v.source_captured_at_ms !== null && v.source_captured_at_ms <= end.wall) {
-      v.age_ms = Math.max(0, end.mono - a.end.mono + a.end.wall - v.source_captured_at_ms)
-    }
-    return { ...v, session_id: sessionId, correlation_id: componentAction?.correlationId ?? current.correlationId,
-      action_id: componentAction?.id ?? null, association: componentAction ? 'internal' : link.association }
-  })
+  const observations = current.observations.map(a => assembleObservation(a, action, current, link, end, clockChanged))
   return {
     session_id: sessionId, correlation_id: action?.correlationId ?? current.correlationId,
     action_id: action?.id ?? null, device: current.device, ...link,
     ...(current.ref ? { requested_action_ref: current.ref } : {}),
     operation_started_at_ms: current.start.wall, operation_completed_at_ms: current.end?.wall ?? end.wall,
-    dispatch_started_at_ms: action?.dispatchStart?.wall ?? null,
-    dispatch_completed_at_ms: action?.dispatchEnd?.wall ?? null,
-    verification_completed_at_ms: current.verification?.wall ?? action?.verification?.wall ?? null,
-    observations, trace_context: { supported: false, trace_id: null, markers: [] }
+    ...actionTimes(action, current),
+    observations, trace_context: { supported: !!current.systemTraceId, trace_id: current.systemTraceId ?? null, markers: [] }
   }
 }
 export async function withEvidence<T>(options: { action?: boolean; journey?: boolean; ref?: ActionRef }, operation: () => Promise<T>): Promise<{ result: T; evidence: ReturnType<typeof assemble> }> {
   prune()
   const parent = context.getStore()
   const id = randomUUID()
-  const record: ActionRecord | null = options.action ? { id, correlationId: parent?.correlationId ?? id, device: null,
-    dispatchStart: null, dispatchEnd: null, verification: null, completed: null } : options.ref?.sessionId === sessionId ? active.get(options.ref.actionId) ?? history.get(options.ref.actionId) ?? null : null
-  const current: EvidenceContext = { correlationId: options.action ? record!.correlationId : options.journey ? id : randomUUID(),
-    action: record, ref: options.ref, device: null, start: stamp(), end: null, verification: null, observations: [], children: [], isAction: !!options.action }
+  const record: ActionRecord | null = options.action ? {
+    id, correlationId: parent?.correlationId ?? id, device: null,
+    dispatchStart: null, dispatchEnd: null, verification: null, completed: null
+  } : options.ref?.sessionId === sessionId ? active.get(options.ref.actionId) ?? history.get(options.ref.actionId) ?? null : null
+  const current: EvidenceContext = {
+    systemTraceId: parent?.systemTraceId, correlationId: options.action ? record!.correlationId : options.journey ? id : randomUUID(),
+    action: record, ref: options.ref, device: null, start: stamp(), end: null, verification: null, observations: [], children: [], isAction: !!options.action
+  }
   if (options.action && record) active.set(id, record)
   if (parent && options.action) parent.children.push(current)
   try {
@@ -236,7 +210,7 @@ export async function withEvidence<T>(options: { action?: boolean; journey?: boo
   }
 }
 
-export function refreshJourneyEvidence(steps: Array<{ result?: { evidence?: unknown } }>) {
+export function refreshJourneyEvidence(steps: Array<{ result?: { evidence?: unknown } | null }>) {
   const current = context.getStore()
   if (!current) return
   for (const step of steps) {
@@ -253,3 +227,88 @@ export function completeJourneyVerification(actionId: string) {
     child.action.verification = child.verification
   }
 }
+
+function recordObservationResult(acquisition: Acquisition, result: EvidencePayload | null, kind: Kind, target: EvidenceDevice | null, start: Stamp) {
+  const value = acquisition.value
+  const resolved = validDevice(result?.device) ?? target
+  value.device = resolved
+  if (resolved) bindEvidenceDevice(resolved)
+  const failure = result?.error ?? result?.meta?.error
+  value.status = failure || result?.success === false || (kind === 'fingerprint' && !result?.fingerprint) ? 'failed' : 'captured'
+  if (failure) value.error = failure
+  recordCaptureTime(acquisition, result, start)
+  if (kind === 'ui_tree') {
+    value.snapshot_session_id = result?.snapshot_session_id
+    value.snapshot_revision = result?.snapshot_revision
+  }
+  if (kind === 'logs') recordLogWindow(value, result)
+
+}
+
+function recordLogWindow(value: Component, result: EvidencePayload | null) {
+  const entries = result?.logs ?? result?.entries ?? []
+  const times = entries.map((e: { timestamp?: unknown; _iso?: unknown } | null) => {
+    const t = e?.timestamp ?? e?._iso
+    return typeof t === 'number' ? t : typeof t === 'string' ? Date.parse(t) : NaN
+  }).filter((t: number) => Number.isFinite(t)) as number[]
+  value.clock = 'device_or_unknown'; value.event_time_comparable = false
+  value.earliest_entry_at_ms = times.length ? times.reduce((a, b) => Math.min(a, b)) : null
+  value.latest_entry_at_ms = times.length ? times.reduce((a, b) => Math.max(a, b)) : null
+}
+
+function assembleObservation(a: Acquisition, action: ActionRecord | null, current: EvidenceContext, link: ReturnType<typeof association>, end: Stamp, clockChanged: boolean) {
+
+  const v = { ...a.value, freshness_reasons: [] as string[] }
+  if (v.status === 'omitted') return v
+  const componentAction = sameDevice(v.device, action?.device ?? null) ? action : null
+  const sourceMono = a.end && v.source_captured_at_ms !== null ? a.end.mono + v.source_captured_at_ms - a.end.wall : a.end?.mono
+  const freshness = observationFreshness(a, componentAction, sourceMono, clockChanged)
+  if (freshness) { v.freshness = freshness[0]; v.freshness_reasons.push(freshness[1]) }
+  else v.freshness = 'fresh'
+
+  if (!clockChanged && a.end && a.end.wall >= a.start.wall && v.source_captured_at_ms !== null && v.source_captured_at_ms <= end.wall) {
+    v.age_ms = Math.max(0, end.mono - a.end.mono + a.end.wall - v.source_captured_at_ms)
+  }
+  return {
+    ...v, session_id: sessionId, correlation_id: componentAction?.correlationId ?? current.correlationId,
+    action_id: componentAction?.id ?? null, association: componentAction ? 'internal' : link.association
+  }
+
+}
+
+function observationFreshness(a: Acquisition, action: ActionRecord | null, sourceMono: number | undefined, clockChanged: boolean): [Freshness, string] | null {
+  const v = a.value
+  if (v.kind === 'logs') return ['unknown', 'DEVICE_CLOCK_UNVERIFIED']
+  if (clockDiscontinuity(a, clockChanged)) return ['unknown', 'CLOCK_DISCONTINUITY']
+  if (!knownCapture(a)) return ['unknown', 'CAPTURE_TIME_UNKNOWN']
+  if (action?.dispatchStart && sourceMono !== undefined && sourceMono < action.dispatchStart.mono) return ['stale', 'BEFORE_ACTION']
+  if (superseded(a, sourceMono)) return ['stale', 'SUPERSEDED_BY_ACTION']
+  if (a.overlapping) return ['unknown', 'OVERLAPPING_ACTION']
+  if (a.reused) return ['unknown', 'REUSED_OBSERVATION']
+  return null
+}
+function clockDiscontinuity(a: Acquisition, changed: boolean) {
+  return changed || !!(a.end && a.end.wall < a.start.wall) || !!(a.value.source_captured_at_ms !== null && a.end && a.value.source_captured_at_ms > a.end.wall)
+}
+function knownCapture(a: Acquisition) {
+  return !!a.value.device && !!a.order && orders.get(deviceKey(a.value.device)) === a.order && a.value.status === 'captured' && !!a.end
+}
+function superseded(a: Acquisition, sourceMono: number | undefined) {
+  return !!a.order && (a.order.sequence > a.endSequence || (a.reused && sourceMono !== undefined && sourceMono < a.order.lastStarted))
+}
+
+function actionTimes(action: ActionRecord | null, current: EvidenceContext) {
+  return {
+    dispatch_started_at_ms: action?.dispatchStart?.wall ?? null,
+    dispatch_completed_at_ms: action?.dispatchEnd?.wall ?? null,
+    verification_completed_at_ms: current.verification?.wall ?? action?.verification?.wall ?? null,
+  }
+}
+
+function recordCaptureTime(acquisition: Acquisition, result: EvidencePayload | null, start: Stamp) {
+  const source = result?.captured_at_ms
+  if (typeof source === 'number' && Number.isFinite(source) && source > 0) {
+    acquisition.value.source_captured_at_ms = source
+    acquisition.reused = source < start.wall
+  }
+}

package/src/observe/index.ts

@@ -1,156 +1,18 @@
-import { omitEvidence } from './evidence.js'
+import type { GetUITreeResponse, StateDelta } from '../types.js'
 import { withResolvedDevice } from '../utils/resolve-device.js'
-import { measure } from '../utils/timing.js'
 import { ReadinessTracker } from './readiness.js'
 import { resolveTargetDevice } from '../utils/resolve-device.js'
 import { AndroidObserve } from './android.js'
 import { iOSObserve } from './ios.js'
-import type {
-  CaptureDebugSnapshotRawResponse,
-  SnapshotSemanticResponse
-} from '../types.js'
-import { deriveSnapshotMetadata, getLatestStateDelta, getStateDelta } from './snapshot-metadata.js'
+
+import { getLatestStateDelta, getStateDelta } from './snapshot-metadata.js'
 
 export { AndroidObserve } from './android.js'
 export { iOSObserve } from './ios.js'
 
-interface SnapshotTreeElementLike {
-  text?: string | null
-  contentDescription?: string | null
-  contentDesc?: string | null
-  accessibilityLabel?: string | null
-  resourceId?: string | null
-  id?: string | null
-  type?: string | null
-  class?: string | null
-  clickable?: boolean
-  enabled?: boolean
-  visible?: boolean
-  state?: unknown
-  stable_id?: string | null
-  role?: string | null
-  test_tag?: string | null
-  selector?: unknown
-  semantic?: unknown
-}
-
-interface SnapshotTreeLike {
-  screen?: string | null
-  elements?: SnapshotTreeElementLike[]
-}
-
-function normalizeHint(value: unknown): string {
-  if (value === null || value === undefined) return ''
-  return String(value).trim().replace(/\s+/g, ' ').toLowerCase()
-}
-
-function titleCase(value: string): string {
-  return value
-    .replace(/[_-]+/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-    .replace(/\b\w/g, (match) => match.toUpperCase())
-}
-
-function shortActivityName(activity: string | null | undefined): string | null {
-  if (!activity) return null
-  const trimmed = String(activity).trim()
-  if (!trimmed) return null
-  const lastSegment = trimmed.split('.').pop() || trimmed
-  const withoutSuffix = lastSegment.replace(/Activity$/, '')
-  return withoutSuffix ? titleCase(withoutSuffix) : titleCase(lastSegment)
-}
-
-function collectSnapshotTexts(tree: SnapshotTreeLike | null | undefined) {
-  const elements = Array.isArray(tree?.elements) ? tree!.elements! : []
-  const texts: string[] = []
-  const actionables: string[] = []
-
-  for (const element of elements) {
-    const rawText = element?.text ?? element?.contentDescription ?? element?.contentDesc ?? element?.accessibilityLabel ?? element?.resourceId ?? element?.id ?? ''
-    const text = normalizeHint(rawText)
-    if (text) texts.push(text)
-    if (element?.clickable && element?.enabled !== false && text) {
-      actionables.push(text)
-    }
-  }
-
-  return {
-    texts: Array.from(new Set(texts)),
-    actionables: Array.from(new Set(actionables))
-  }
-}
-
-function inferSnapshotScreen(raw: CaptureDebugSnapshotRawResponse): string | null {
-  const tree = raw.ui_tree as SnapshotTreeLike | null | undefined
-  const treeScreen = normalizeHint(tree?.screen)
-  if (treeScreen) return titleCase(treeScreen)
-
-  const activity = shortActivityName(raw.activity)
-  if (activity) return activity
-
-  const { texts } = collectSnapshotTexts(tree)
-  if (texts.length > 0) return titleCase(texts[0])
-
-  return null
-}
-
-function deriveSnapshotSemantic(raw: CaptureDebugSnapshotRawResponse): SnapshotSemanticResponse | null {
-  const tree = raw.ui_tree as SnapshotTreeLike | null | undefined
-  const { texts, actionables } = collectSnapshotTexts(tree)
-  const screenFromTree = normalizeHint(tree?.screen)
-  const activityHint = normalizeHint(raw.activity)
-  const screen = inferSnapshotScreen(raw)
-
-  if (!screen && !activityHint && texts.length === 0 && !raw.logs.length) return null
-
-  const hasErrorLogs = raw.logs.some((entry) => /error|fatal exception|exception|failed/i.test(entry.message))
-  const hasLoadingSignals = texts.some((text) => /loading|please wait|spinner|progress/i.test(text))
-  const hasPrimaryText = texts.some((text) => /sign in|log in|login|home|checkout|settings|menu|profile|search/i.test(text))
-  const hasScreenshot = typeof raw.screenshot === 'string' && raw.screenshot.length > 0
-  const hasUiTree = !!tree && Array.isArray(tree.elements)
-
-  const signals: Record<string, string | number | boolean> = {
-    has_activity: !!activityHint,
-    has_ui_tree: hasUiTree,
-    has_screenshot: hasScreenshot,
-    has_visible_text: texts.length > 0,
-    has_clickable_elements: actionables.length > 0,
-    has_error_logs: hasErrorLogs,
-    has_loading_signals: hasLoadingSignals,
-    has_primary_text: hasPrimaryText
-  }
-
-  const warnings: string[] = []
-  if (screenFromTree && activityHint && screenFromTree !== activityHint) {
-    warnings.push('ui_tree.screen and activity hints differ')
-  }
-  if (!hasUiTree) warnings.push('ui tree unavailable')
-  if (!activityHint) warnings.push('activity unavailable')
-  if (hasErrorLogs) warnings.push('error signals present in logs')
-
-  const evidenceScore =
-    (hasUiTree ? 0.35 : 0) +
-    (screen ? 0.2 : 0) +
-    (activityHint ? 0.15 : 0) +
-    (actionables.length > 0 ? 0.15 : 0) +
-    (texts.length > 0 ? 0.1 : 0) +
-    (hasScreenshot ? 0.05 : 0) +
-    (hasErrorLogs ? -0.15 : 0) +
-    (hasLoadingSignals ? -0.05 : 0)
-
-  const confidence = Math.max(0, Math.min(1, Number(evidenceScore.toFixed(2))))
-
-  if (!screen && confidence < 0.3) return null
-
-  return {
-    screen,
-    signals,
-    actions_available: actionables.length > 0 ? actionables.slice(0, 10) : null,
-    confidence,
-    warnings
-  }
-}
+import { collectDebugSnapshot } from './snapshot-collection.js'
+interface TreeInput { platform?: 'android' | 'ios'; deviceId?: string; responseMode?: 'compact' | 'debug'; sinceSnapshotRevision?: number }
+interface CompactTree extends Partial<GetUITreeResponse> { delta_available: boolean; state_delta?: StateDelta; reason?: string }
 
 export class ToolsObserve {
   static getLatestStateDelta(platform: 'android' | 'ios', deviceId: string) {
@@ -177,10 +39,12 @@ export class ToolsObserve {
     }
   }
 
+  static getUITreeHandler(input: TreeInput & { responseMode?: 'debug' }): Promise<GetUITreeResponse>
+  static getUITreeHandler(input: TreeInput): Promise<GetUITreeResponse | CompactTree>
   static async getUITreeHandler({ platform, deviceId, responseMode = 'debug', sinceSnapshotRevision }: { platform?: 'android' | 'ios', deviceId?: string, responseMode?: 'compact' | 'debug', sinceSnapshotRevision?: number }) {
     const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId)
     const acquisitionStarted = Date.now()
-    const tree = await observe.getUITree(resolved.id) as any
+    const tree = await observe.getUITree(resolved.id)
     tree.readiness = new ReadinessTracker(resolved.platform, resolved.id).observe(tree, acquisitionStarted)
     if (responseMode !== 'compact') return tree
     const revision = tree?.snapshot_revision ?? null
@@ -210,25 +74,16 @@ export class ToolsObserve {
     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 (level && !['VERBOSE', 'DEBUG', 'INFO', 'WARN', 'ERROR'].includes(level.toString().toUpperCase())) {
+      return { device: resolved, logs: [], crashLines: [], logCount: 0, error: { code: 'INVALID_FILTER', message: `Unsupported level filter: ${level}` } }
     }
 
-    if (observe instanceof AndroidObserve) {
-      const response = await observe.getLogs(filters)
-      const logs = Array.isArray(response.logs) ? response.logs : []
-      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(filters)
-      const logs = Array.isArray(resp.logs) ? resp.logs : []
-      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 }
-    }
+    const response = await observe.getLogs(filters)
+    const logs = Array.isArray(response.logs) ? response.logs : []
+    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' } }
+    return { device: response.device, logs, crashLines, logCount: response.logCount, source: response.source, meta: response.meta }
   }
 
   static async startLogStreamHandler({ platform, packageName, level, sessionId, deviceId }: { platform?: 'android' | 'ios', packageName: string, level?: 'error' | 'warn' | 'info' | 'debug', sessionId?: string, deviceId?: string }) {
@@ -273,135 +128,18 @@ export class ToolsObserve {
   static async getScreenFingerprintHandler({ platform, deviceId }: { platform?: 'android' | 'ios', deviceId?: string } = {}) {
     const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId)
     // Both observes implement getScreenFingerprint
-    return await (observe as any).getScreenFingerprint(resolved.id)
+    return await (observe).getScreenFingerprint(resolved.id)
   }
 
   static async captureDebugSnapshotHandler({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId }: { reason?: string; includeLogs?: boolean; includeScreenshot?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string } = {}) {
     const { resolved } = await ToolsObserve.resolveObserve(platform, deviceId, appId)
-    return withResolvedDevice(resolved, () => ToolsObserve.collectDebugSnapshot({ reason, includeLogs, includeScreenshot, logLines,
-      platform: resolved.platform as 'android' | 'ios', appId, deviceId: resolved.id, sessionId }))
+    return withResolvedDevice(resolved, () => ToolsObserve.collectDebugSnapshot({
+      reason, includeLogs, includeScreenshot, logLines,
+      platform: resolved.platform as 'android' | 'ios', appId, deviceId: resolved.id, sessionId
+    }))
   }
 
-  private static async collectDebugSnapshot({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId }: { reason?: string; includeLogs?: boolean; includeScreenshot?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string } = {}) {
-    if (!includeScreenshot) omitEvidence('screenshot')
-    if (!includeLogs) omitEvidence('logs')
-    const timestamp = Date.now()
-    const raw: CaptureDebugSnapshotRawResponse = {
-      timestamp,
-      snapshot_revision: 0,
-      captured_at_ms: timestamp,
-      reason: reason || '',
-      activity: null,
-      fingerprint: null,
-      screenshot: null,
-      ui_tree: null,
-      logs: []
-    }
-
-    // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
-    const sid = sessionId || 'default'
-    const tasks: Record<string, Promise<any>> = {
-      screenshot: includeScreenshot ? measure('screenshot_ms', () => ToolsObserve.captureScreenshotHandler({ platform, deviceId })) : Promise.resolve(null),
-      currentScreen: (!platform || platform === 'android') ? ToolsObserve.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
-      fingerprint: ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }),
-      uiTree: ToolsObserve.getUITreeHandler({ platform, deviceId }),
-      readLogStream: includeLogs ? ToolsObserve.readLogStreamHandler({ platform, deviceId, sessionId: sid, limit: logLines }) : Promise.resolve({ entries: [] }),
-    }
-
-    const results = await Promise.allSettled(Object.values(tasks))
-    const keys = Object.keys(tasks)
-
-    // Map results back to keys
-    for (let i = 0; i < results.length; i++) {
-      const key = keys[i]
-      const res = results[i] as PromiseSettledResult<any>
-      if (res.status === 'fulfilled') {
-        const val = res.value
-        if (key === 'screenshot') {
-          raw.screenshot = val && val.screenshot ? val.screenshot : null
-        } else if (key === 'currentScreen') {
-          raw.activity = val && ((val.activity || val.shortActivity)) ? (val.activity || val.shortActivity) : raw.activity || ''
-        } else if (key === 'fingerprint') {
-          if (val && val.fingerprint) raw.fingerprint = val.fingerprint
-          if (val && val.activity) raw.activity = raw.activity || val.activity
-          if (val && val.error) raw.fingerprint_error = val.error
-        } else if (key === 'uiTree') {
-          raw.ui_tree = val
-          if (val && val.error) raw.ui_tree_error = val.error
-        } else if (key === 'readLogStream') {
-          // handle below after evaluating fallback
-          // temporarily attach to out._streamEntries
-          raw.logs = Array.isArray(val?.entries) ? val.entries : []
-        }
-      } else {
-        const errMsg = res.reason instanceof Error ? res.reason.message : String(res.reason)
-        if (key === 'screenshot') raw.screenshot_error = errMsg
-        if (key === 'currentScreen') raw.activity_error = errMsg
-        if (key === 'fingerprint') { raw.fingerprint = null; raw.fingerprint_error = errMsg }
-        if (key === 'uiTree') { raw.ui_tree = null; raw.ui_tree_error = errMsg }
-        if (key === 'readLogStream') { raw.logs = []; raw.logs_error = errMsg }
-      }
-    }
-
-    // Logs: prefer stream entries, fallback to snapshot logs when empty
-    if (includeLogs) {
-      try {
-        let entries: any[] = Array.isArray(raw.logs) ? raw.logs : []
-        if (!entries || entries.length === 0) {
-          const gl = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines: logLines })
-          const snapshotLogs: any[] = (gl && (gl as any).logs) ? (gl as any).logs : []
-          // raw may be structured entries or strings
-          entries = snapshotLogs.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 => {
-            const msg = (ent && (ent.message || ent.msg)) ? (ent.message || ent.msg) : (typeof ent === 'string' ? ent : JSON.stringify(ent))
-            const levelRaw = (ent && (ent.level || ent.levelName || ent._level)) ? (ent.level || ent.levelName || ent._level) : ''
-            const level = (levelRaw && String(levelRaw)).toString().toUpperCase() || (/\bERROR\b/i.test(msg) ? 'ERROR' : /\bWARN\b/i.test(msg) ? 'WARN' : 'INFO')
-            let tsNum: number | null = null
-            const maybeIso = ent && ((ent._iso || ent.timestamp) as any)
-            if (maybeIso && typeof maybeIso === 'string') {
-              const d = new Date(maybeIso)
-              if (!isNaN(d.getTime())) tsNum = d.getTime()
-            }
-            return { timestamp: tsNum, level, message: msg }
-          })
-        }
-
-        raw.logs = entries
-      } catch (e) {
-        raw.logs = []
-        raw.logs_error = e instanceof Error ? e.message : String(e)
-      }
-    }
-
-    const snapshotDeviceKey = raw.ui_tree?.device
-      ? `${raw.ui_tree.device.platform}:${raw.ui_tree.device.id}`
-      : `${platform || 'unknown'}:${deviceId || 'default'}`
-    const snapshotMetadata = deriveSnapshotMetadata(
-      snapshotDeviceKey,
-      raw.ui_tree,
-      'snapshot',
-      raw.ui_tree?.snapshot_revision ? null : (raw.fingerprint || raw.activity || null)
-    )
-
-    raw.snapshot_revision = raw.ui_tree?.snapshot_revision ?? snapshotMetadata.snapshot_revision
-    raw.captured_at_ms = raw.ui_tree?.captured_at_ms ?? snapshotMetadata.captured_at_ms
-    raw.snapshot_delta = raw.ui_tree?.snapshot_delta ?? snapshotMetadata.snapshot_delta ?? null
-    raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state
-
-    const semantic = deriveSnapshotSemantic(raw)
-    return semantic ? { raw, semantic } : { raw }
+  private static collectDebugSnapshot(input: import('./snapshot-collection.js').SnapshotInput = {}) {
+    return collectDebugSnapshot(input, ToolsObserve)
   }
 }

package/src/observe/ios/context.ts

@@ -0,0 +1,22 @@
+import { execCommand } from "../../utils/ios/utils.js"
+export const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+export let iosExecCommand = execCommand
+
+export function _setIOSExecCommandForTests(fn: typeof execCommand) {
+  iosExecCommand = fn
+}
+
+export function _resetIOSExecCommandForTests() {
+  iosExecCommand = execCommand
+}
+
+export const iosActiveLogStreams: Map<string, { proc: Pick<import('node:child_process').ChildProcess, 'kill'>, file: string, device?: { platform: 'android' | 'ios'; id: string } }> = new Map()
+
+export function _setIOSActiveLogStream(sessionId: string, file: string, device?: { platform: 'android' | 'ios'; id: string }) {
+  iosActiveLogStreams.set(sessionId, { proc: { kill: () => false }, file, device })
+}
+
+export function _clearIOSActiveLogStream(sessionId: string) {
+  iosActiveLogStreams.delete(sessionId)
+}