mobile-debug-mcp 0.35.0 → 0.37.0

package/src/observe/readiness.ts

@@ -1,3 +1,5 @@
+import type { DeviceReadiness } from '../contracts/device-readiness.js'
+import { unknownDeviceReadiness, observeDeviceReadiness, finishDeviceReadiness } from './device-readiness.js'
 import type { GetUITreeResponse } from '../types.js'
 import { pausedReadiness } from '../debugger/guard.js'
 import { AsyncLocalStorage } from 'node:async_hooks'
@@ -12,7 +14,36 @@ export function isDeviceUnavailable(error: unknown) {
   return /device.*(?:not found|offline|disconnected)|no devices found|READINESS_DEVICE_UNAVAILABLE/i.test(String(error))
 }
 
+function retainBlockedEvidence(previous: DeviceReadiness, next: DeviceReadiness) {
+  const retained: string[] = []
+  if (['unknown', 'unsupported'].includes(next.wakefulness) && ['asleep', 'transitioning'].includes(previous.wakefulness)) {
+    next.wakefulness = previous.wakefulness
+    retained.push('DEVICE_ASLEEP', 'DEVICE_TRANSITIONING')
+  }
+  if (['unknown', 'unsupported'].includes(next.lock_state) && previous.lock_state === 'locked') {
+    next.lock_state = previous.lock_state
+    retained.push('DEVICE_LOCKED')
+  }
+  if (retained.length) {
+    next.evidence = [...previous.evidence.filter(item => retained.includes(item.code)), ...next.evidence].slice(-8)
+    next.limitations = [...new Set([...next.limitations, 'DEVICE_BLOCKER_EVIDENCE_RETAINED'])]
+  }
+  return finishDeviceReadiness(next)
+}
+
 export class ReadinessTracker {
+  deviceReadiness = unknownDeviceReadiness()
+  get ready() { return this.summary.state === 'settled' && this.deviceReadiness.input_ready !== false }
+  async observeDevice() {
+    const next = await observeDeviceReadiness({ platform: this.platform, id: this.deviceId })
+    this.deviceReadiness = retainBlockedEvidence(this.deviceReadiness, next)
+    if (this.deviceReadiness.input_ready === false) {
+      this.signature = null
+      this.stableSince = 0
+      this.summary = { ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
+        limitations: [...new Set([...this.summary.limitations, 'DEVICE_BLOCKED'])] }
+    }
+  }
   private signature: string | null = null
   private stableSince = 0
   summary: ReadinessSummary
@@ -21,7 +52,7 @@ export class ReadinessTracker {
     this.summary = {
       state: 'unknown', scope: 'device_ui', basis: 'insufficient', captured_at_ms: null,
       sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
-      evidence: [], limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
+      evidence: [], limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: ['android', 'ios'].includes(this.platform) }
     }
 
   }
@@ -30,7 +61,7 @@ export class ReadinessTracker {
     this.signature = null
     this.summary = {
       ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
-      sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
+      sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
       evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8)
     }
     return this.summary
@@ -42,7 +73,7 @@ export class ReadinessTracker {
   }
 
   observe(sample: unknown, acquisitionStartedAtMs: number, now = performance.now()): ReadinessSummary {
-    const paused = this.platform === 'android' ? pausedReadiness(this.deviceId) : null
+    const paused = pausedReadiness(this.deviceId, this.platform)
     if (paused) { this.summary = paused; return this.summary }
     const tree = sample as GetUITreeResponse | null | undefined
     if (tree?.error) return this.unavailable('OBSERVATION_FAILED')
@@ -64,7 +95,7 @@ export class ReadinessTracker {
       captured_at_ms: tree.captured_at_ms, snapshot_session_id: tree.snapshot_session_id, snapshot_revision: tree.snapshot_revision,
       sample_count: this.summary.sample_count + 1, stable_for_ms: stableFor,
       evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: tree.captured_at_ms, snapshot_revision: tree.snapshot_revision }].slice(-8),
-      limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
+      limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: ['android', 'ios'].includes(this.platform) }
     }
     return this.summary
   }
@@ -103,3 +134,5 @@ function readinessState(loading: boolean, previous: string | null, unchanged: bo
 function readinessCode(nativeLoading: boolean, textLoading: boolean, state: ReadinessSummary['state']) {
   return nativeLoading ? 'NATIVE_LOADING_INDICATOR' : textLoading ? 'LOADING_LABEL' : state === 'transitioning' ? 'SNAPSHOT_CHANGED' : state === 'settled' ? 'SNAPSHOT_STABLE' : 'INSUFFICIENT_SAMPLES'
 }
+
+export async function observeReadinessDeviceWait() { await waits.getStore()?.observeDevice() }

package/src/observe/screenshot-encoding.ts

@@ -1,4 +1,5 @@
 import type { Metadata } from 'sharp'
+import { benchmarkStage } from '../utils/benchmark-metrics.js'
 interface EncodedScreenshot { screenshot: string; screenshot_mime: string; screenshot_fallback?: string | null; screenshot_fallback_mime?: string }
 async function convert(buffer: Buffer, platform: 'android' | 'ios') {
   const { default: sharp } = await import('sharp')
@@ -16,6 +17,9 @@ async function convert(buffer: Buffer, platform: 'android' | 'ios') {
   return { hasAlpha, webp, jpeg }
 }
 export async function encodeScreenshot(buffer: Buffer, platform: 'android' | 'ios'): Promise<EncodedScreenshot> {
+  return benchmarkStage('screenshot_encoding_ms', () => encode(buffer, platform))
+}
+async function encode(buffer: Buffer, platform: 'android' | 'ios'): Promise<EncodedScreenshot> {
   const png = buffer.toString('base64')
   try {
     const { hasAlpha, webp, jpeg } = await convert(buffer, platform)

package/src/observe/snapshot-collection.ts

@@ -5,6 +5,7 @@ import { measure } from '../utils/timing.js'
 import { deriveSnapshotMetadata } from './snapshot-metadata.js'
 import { deriveSnapshotSemantic } from './snapshot-semantic.js'
 import { snapshotLog, streamLog, type SnapshotLogEntry } from './snapshot-logs.js'
+import { collectGetScreenFingerprint } from './android/fingerprint.js'
 export interface SnapshotInput { reason?: string; includeLogs?: boolean; includeScreenshot?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string }
 type Dependencies = Pick<typeof ToolsObserve, 'captureScreenshotHandler' | 'getCurrentScreenHandler' | 'getScreenFingerprintHandler' | 'getUITreeHandler' | 'readLogStreamHandler' | 'getLogsHandler'>
 async function settle<T extends Record<string, Promise<unknown>>>(tasks: T) {
@@ -17,11 +18,15 @@ function apply<T>(result: PromiseSettledResult<T>, success: (value: T) => void,
 }
 async function collect(raw: CaptureDebugSnapshotRawResponse, input: SnapshotInput, deps: Dependencies) {
   const { platform, deviceId, includeScreenshot = true, includeLogs = true, sessionId, logLines = 200 } = input
+  const androidTree = platform === 'android' ? deps.getUITreeHandler({ platform, deviceId }) : undefined
   const results = await settle({
     screenshot: includeScreenshot ? measure('screenshot_ms', () => deps.captureScreenshotHandler({ platform, deviceId })) : Promise.resolve(null),
     currentScreen: !platform || platform === 'android' ? deps.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
-    fingerprint: deps.getScreenFingerprintHandler({ platform, deviceId }),
-    uiTree: deps.getUITreeHandler({ platform, deviceId }),
+    fingerprint: androidTree ? collectGetScreenFingerprint({
+      getUITree: () => androidTree,
+      getCurrentScreen: id => deps.getCurrentScreenHandler({ deviceId: id })
+    }, deviceId) : deps.getScreenFingerprintHandler({ platform, deviceId }),
+    uiTree: androidTree ?? deps.getUITreeHandler({ platform, deviceId }),
     readLogStream: includeLogs ? deps.readLogStreamHandler({ platform, deviceId, sessionId: sessionId || 'default', limit: logLines }) : Promise.resolve({ entries: [] })
   })
   let entries: unknown[] = []

package/src/observe/system-trace-error.ts

@@ -0,0 +1,3 @@
+export class TraceError extends Error {
+  constructor(public code: string) { super(code) }
+}

package/src/observe/system-trace-router.ts

@@ -0,0 +1,61 @@
+import { TraceError } from './system-trace-error.js'
+import type { SystemTraceSessions, TraceResult } from './system-trace.js'
+import { IosTraceSessions, type IosTraceResult } from './ios-trace/sessions.js'
+import { IosTraceNative } from './ios-trace/native.js'
+import type { IosTemplate } from './ios-trace/capabilities.js'
+
+interface Route { platform: 'android' | 'ios'; device: string; active: boolean; touched: number }
+export class SystemTraceRouter {
+  private routes = new Map<string, Route>()
+  private pending = new Set<string>()
+  private closing = false
+  constructor(private android: SystemTraceSessions, private ios = new IosTraceSessions(), private native = new IosTraceNative()) {}
+  capabilities(device: string) { return this.android.capabilities(device) }
+  iosCapabilities(device: string, appId?: string, template?: IosTemplate) { return this.native.capabilities(device, appId, template) }
+  private backend(platform: string) { return platform === 'ios' ? this.ios : this.android }
+  private track(result: TraceResult | IosTraceResult) {
+    this.routes.set(result.trace_id, { platform: result.device.platform, device: result.device.id,
+      active: result.cleanup.status !== 'complete', touched: performance.now() })
+    const terminal = [...this.routes.entries()].filter(([, r]) => !r.active)
+    for (const [index, [id, r]] of terminal.entries()) if (performance.now() - r.touched > 600000 || index < terminal.length - 100) this.routes.delete(id)
+    return result
+  }
+  async start(device: string, duration?: number, ios?: { appId: string; template?: IosTemplate }) {
+    if (this.closing) throw new TraceError('TRACE_BUSY')
+    // Refresh automatically finalised reservations without trusting cached state.
+    await Promise.all([...this.routes.entries()].filter(([, r]) => r.active).map(async ([id, r]) => {
+      try { this.track(await this.backend(r.platform).control(id, 'status')) }
+      catch { /* uncertain cleanup continues to reserve capacity */ }
+    }))
+    const key = (ios ? 'ios:' : 'android:') + device
+    const active = [...this.routes.values()].filter(r => r.active)
+    if (this.closing || this.pending.has(key) || active.some(r => r.platform + ':' + r.device === key) || active.length + this.pending.size >= 4) throw new TraceError('TRACE_BUSY')
+    this.pending.add(key)
+    try {
+      if (!ios) return this.track(await this.android.start(device, duration))
+      const cap = await this.native.capabilities(device, ios.appId, ios.template)
+      if (!cap.supported || !cap.device) throw new TraceError('TRACE_UNSUPPORTED')
+      if (this.closing) throw new TraceError('TRACE_BUSY')
+      return this.track(await this.ios.start(cap.device, ios.appId, duration))
+    } finally { this.pending.delete(key) }
+  }
+  async control(id: string, operation: 'status' | 'stop' | 'cancel' | 'duration') {
+    const route = this.routes.get(id)
+    if (!route) throw new TraceError('TRACE_NOT_FOUND')
+    return this.track(await this.backend(route.platform).control(id, operation))
+  }
+  async link(id: string, device: { platform: string; id: string }, correlation: string) {
+    const route = this.routes.get(id)
+    if (!route || route.platform !== device.platform || route.device !== device.id) throw new TraceError('TRACE_NOT_FOUND')
+    return this.backend(route.platform).link(id, device, correlation)
+  }
+  async shutdown() {
+    this.closing = true
+    this.native.shutdown()
+    const results = await Promise.allSettled([this.android.shutdown(), this.ios.shutdown()])
+    if (results.some(result => result.status === 'rejected')) throw new TraceError('TRACE_STOP_FAILED')
+    const remaining: (TraceResult | IosTraceResult)[] = []
+    for (const result of results) if (result.status === 'fulfilled') remaining.push(...result.value)
+    return remaining
+  }
+}

package/src/observe/system-trace.ts

@@ -1,3 +1,4 @@
+import { SystemTraceRouter } from './system-trace-router.js'
 import { randomUUID } from 'node:crypto'
 import { promises as fs } from 'node:fs'
 import os from 'node:os'
@@ -6,9 +7,8 @@ import { AndroidTraceNative, TRACE_MAX_BYTES, type TraceCapabilities, type Trace
 import { evidenceSessionId } from './evidence.js'
 import { runWithBudget, remainingBudget } from '../utils/operation-budget.js'
 
-export class TraceError extends Error {
-  constructor(public code: string) { super(code) }
-}
+export { TraceError } from './system-trace-error.js'
+import { TraceError } from './system-trace-error.js'
 type State = 'starting' | 'recording' | 'stopping' | 'completed' | 'cancelled' | 'failed'
 type Completion = 'requested' | 'duration_limit' | 'cancelled' | 'error'
 export interface TraceResult {
@@ -224,4 +224,4 @@ export class SystemTraceSessions {
     })
   }
 }
-export const systemTraces = new SystemTraceSessions()
+export const systemTraces = new SystemTraceRouter(new SystemTraceSessions())

package/src/server/common.ts

@@ -13,9 +13,9 @@ export function wrapResponse<T>(data: T, includeSerializationTiming = true) {
 }
 
 export type ToolCallArgs = Record<string, unknown>
-export type ToolCallResult = Awaited<ReturnType<typeof wrapResponse>> | {
+export type ToolCallResult = (Awaited<ReturnType<typeof wrapResponse>> | {
   content: Array<{ type: 'text' | 'image'; text?: string; data?: string; mimeType?: string }>
-}
+}) & { isError?: boolean }
 export type ToolHandler = (args: ToolCallArgs) => Promise<ToolCallResult>
 
 export function getStringArg(args: ToolCallArgs, key: string): string | undefined {

package/src/server/definitions/manage.ts

@@ -185,11 +185,12 @@ Failure Handling:
   },
 {
     name: 'list_devices',
-    description: 'List connected devices and their metadata (android + ios).',
+    description: 'List Android devices and iOS simulators. Supply appId for device-specific installation status; unknown checks do not imply absence.',
     inputSchema: {
       type: 'object',
       properties: {
-        platform: { type: 'string', enum: ['android', 'ios'] }
+        platform: { type: 'string', enum: ['android', 'ios'] },
+        appId: { type: 'string', pattern: '^[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*$', description: 'Optional package or bundle identifier to check on each device.' }
       }
     }
   }

package/src/server/handlers/action-execution.ts

@@ -1,3 +1,4 @@
+import { observeDeviceReadiness, unknownDeviceReadiness } from '../../observe/device-readiness.js'
 import type { ToolPayload } from './payload.js'
 import { payloadOf } from './payload.js'
 import { correlatedHandler } from './correlation.js'
@@ -8,7 +9,7 @@ import { randomUUID } from 'node:crypto'
 import { runWithBudget } from '../../utils/operation-budget.js'
 import { validateExpectedState } from '../schemas/condition-schema.js'
 import { conditionFailureCode, createConditionalAction, withConditionalAction } from '../../interact/conditional-action.js'
-import { resolveTargetDevice, withResolvedDevice } from '../../utils/resolve-device.js'
+import { resolveTargetDevice, withResolvedDevice, currentResolvedDevice } from '../../utils/resolve-device.js'
 
 import { ToolsObserve } from '../../observe/index.js'
 import { recordObservationEvent, withObservationContext } from '../../observe/performance-metrics.js'
@@ -24,6 +25,7 @@ import type { PlatformArg, VerificationMode } from './handler-types.js'
 export function compactAction(result: ToolPayload, verificationMode: VerificationMode, started = true, stateDelta?: unknown, totalMs = 0) {
   return {
     action_id: result.action_id,
+    ...(result.device_readiness ? { device_readiness: result.device_readiness } : {}),
     action_type: result.action_type,
     success: !!result.success,
     lifecycle_state: result.success ? (verificationMode === 'full' ? result.lifecycle_state : 'pending_verification') : 'failed',
@@ -51,14 +53,25 @@ function createAction(type: string, args: ToolCallArgs, timing: Record<string, n
   }
 }
 type Action = ReturnType<typeof createAction>
+async function executeWithDeviceState(args: ToolCallArgs, execute: ToolHandler) {
+  const result = payloadOf(await execute(args))
+  result.device_readiness = await observeDeviceReadiness(result.device ?? currentResolvedDevice())
+  return result
+}
+function actionError(type: string, error: unknown) {
+  const response = wrapToolError(type, error)
+  const item = response.content.find(item => item.type === 'text')
+  if (item?.text) item.text = JSON.stringify({ ...JSON.parse(item.text), device_readiness: unknownDeviceReadiness('DEVICE_TARGET_UNAVAILABLE') })
+  return response
+}
 async function dispatchAction(s: Action, execute: ToolHandler) {
   const { type, args, controls, condition, budgetMs } = s
   const dispatchWithBudget = (timeoutMs: number) => runWithBudget(timeoutMs, async (budget) => {
     try {
-      if (!condition) return payloadOf(await execute(args))
+      if (!condition) return await executeWithDeviceState(args, execute)
       return await withConditionalAction(condition, async () => {
         const device = await resolveTargetDevice({ platform: condition.platform, deviceId: condition.deviceId })
-        return withResolvedDevice(device, async () => payloadOf(await execute(args)))
+        return withResolvedDevice(device, async () => executeWithDeviceState(args, execute))
       })
     }
     finally { s.dispatchStarted = budget.dispatchStarted }
@@ -69,8 +82,8 @@ async function dispatchAction(s: Action, execute: ToolHandler) {
       ? await dispatchWithBudget(Infinity) : await dispatchWithBudget(budgetMs)
     if (s.result.success) s.dispatchStarted = true
   } catch (error) {
-    if (!condition && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error))) return wrapToolError(type, error)
-    s.result = { success: false, failure_code: /TIMEOUT|timed out/i.test(String(error)) ? 'ACTION_TIMEOUT' : 'UNKNOWN', error: String(error) }
+    if (!condition && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error))) return actionError(type, error)
+    s.result = { device_readiness: unknownDeviceReadiness('DEVICE_OBSERVATION_UNAVAILABLE'), success: false, failure_code: /TIMEOUT|timed out/i.test(String(error)) ? 'ACTION_TIMEOUT' : 'UNKNOWN', error: String(error) }
   }
 }
 function rejectCondition(s: Action) {
@@ -78,6 +91,7 @@ function rejectCondition(s: Action) {
   s.blocked = !!condition && ['mismatch', 'unavailable'].includes(condition.result.status)
   if (s.blocked && condition) {
     s.dispatchStarted = false
+    const deviceReadiness = s.result.device_readiness
     s.result = buildActionExecutionResult({
       actionType: type, sourceModule: 'server', device: condition.result.observed?.device,
       selector: s.result?.target?.selector ?? null, resolved: s.result?.target?.resolved,
@@ -85,6 +99,7 @@ function rejectCondition(s: Action) {
       failure: { failureCode: conditionFailureCode(condition), retryable: false },
       traceSteps: [{ stage: 'verify', timestamp: Date.now(), result: 'failure', attempt_index: 0, metadata: { phase: 'precondition', dispatch_started: false } }]
     })
+    s.result.device_readiness = deviceReadiness
   }
 }
 function normalizeAction(s: Action) {
@@ -130,19 +145,12 @@ function actionResponse(s: Action) {
   const evidence = {
     ...compact,
     ...(condition ? {
-      condition: controls.responseMode === 'compact' && condition.result.status === 'matched'
-        ? {
-          ...condition.result, observed: condition.result.observed ? {
-            snapshot_session_id: condition.result.observed.snapshot_session_id,
-            snapshot_revision: condition.result.observed.snapshot_revision,
-            captured_at_ms: condition.result.observed.captured_at_ms
-          } : null
-        } : condition.result
+      condition: condition.result
     } : {}),
     ...(controls.verificationMode === 'light' ? { state_delta_available: !!s.delta } : {}),
     ...(s.result.success && controls.verificationMode === 'light' && !s.observationAvailable ? { verification_diagnostic: { code: 'VERIFICATION_UNAVAILABLE', retryable: true } } : {})
   }
-  return wrapResponse(controls.responseMode === 'compact' ? evidence : {
+  return wrapResponse({
     ...s.result, ...evidence, timing: { ...timing, total_ms: performance.now() - started },
     effective_controls: { ...controls, actionTimeoutMs: s.unbounded ? null : budgetMs, timeout_bound: !(s.unbounded) }
   }, controls.responseMode === 'debug')

package/src/server/handlers/compact-interaction.ts

@@ -0,0 +1,91 @@
+import { evidenceSessionId } from '../../observe/evidence.js'
+import { interactionDiagnostics } from './interaction-diagnostics.js'
+import { object, pick, boundedValue, boundedState, observedState, deltaSummary, type Payload } from './compact-state.js'
+import type { ToolCallArgs, ToolCallResult } from '../common.js'
+
+export const compactInteractionTools = new Set(['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'run_journey'])
+const bytes = (value: unknown) => Buffer.byteLength(JSON.stringify(value))
+// IDs are preserved verbatim; their allowance counts the UTF-8 wire encoding.
+const idBytes = (value: unknown) => bytes(String(value ?? '')) - 2
+const deviceBytes = (evidence: unknown) => idBytes(object(object(evidence).device).id)
+function compactEvidence(value: unknown) {
+  const e = object(value)
+  return { ...pick(e, ['session_id', 'correlation_id', 'action_id', 'device']),
+    ...(e.association_reason ? pick(e, ['association', 'association_reason']) : {}),
+    ...(object(e.trace_context).trace_id ? { trace_id: object(e.trace_context).trace_id } : {}) }
+}
+function conditionSummary(value: unknown) {
+  const c = object(value)
+  return { ...pick(c, ['status', 'reason']), observed: c.observed == null ? null : pick(c.observed, ['snapshot_session_id', 'snapshot_revision', 'captured_at_ms']) }
+}
+function addCompactError(result: Payload, error: unknown, name: string) {
+  const message = typeof error === 'string' ? error : object(error).message
+  result.error = { ...pick(error, ['code']), message: boundedValue(message) }
+  result.action_type ??= name
+  result.verification ??= { status: 'unavailable' }
+  if (object(result.error).message !== message) result.truncated = true
+}
+function compactResult(source: Payload, name: string, limit = 1280): Payload {
+  const evidence = object(source.evidence)
+  const result: Payload = {
+    ...pick(source, ['action_id', 'action_type', 'success', 'lifecycle_state', 'failure_code', 'retryable', 'delivery_status', 'dispatch_started', 'verification', 'verification_diagnostic', 'state_delta_available']),
+    observed_state: !['wait', 'assert'].includes(name) && source.dispatch_started !== true
+      ? { status: 'unknown', reason: 'NO_POST_ACTION_OBSERVATION' } : observedState(evidence, source.dispatch_started === true),
+    evidence: compactEvidence(evidence), diagnostics: interactionDiagnostics.retain(source)
+  }
+  result.success ??= false
+  result.verification ??= { status: source.dispatch_started === false ? 'not_requested' : 'unavailable' }
+  if (source.error) addCompactError(result, source.error, name)
+  if (source.device_readiness) result.device_readiness = pick(source.device_readiness, ['wakefulness', 'lock_state', 'input_ready', 'blockers', 'limitations'])
+  if (source.condition) result.condition = conditionSummary(source.condition)
+  if (source.state_delta) result.state_delta = deltaSummary(source.state_delta)
+  if (source.timing) result.timing = pick(source.timing, ['total_ms'])
+  if (object(source.observed).matched_count !== undefined) result.matched_count = object(source.observed).matched_count
+  if (source.observed_fingerprint !== undefined) result.matched = !!source.success
+  const state = source.actual_state !== undefined ? source.actual_state : source.observed_state
+  if (state !== undefined) {
+    result.observed = boundedState(state)
+    if (JSON.stringify(result.observed) !== JSON.stringify(state)) result.truncated = true
+  }
+  result.evidence = { session_id: evidenceSessionId(), ...object(result.evidence) }
+  enforceBudget(result, limit + deviceBytes(evidence))
+  return result
+}
+function enforceBudget(result: Payload, limit: number) {
+  if (bytes(result) <= limit) return
+  result.truncated = true
+  for (const key of ['state_delta', 'observed', 'matched_count', 'matched', 'state_delta_available', 'timing']) {
+    delete result[key]
+    if (bytes(result) <= limit) return
+  }
+  if (result.condition) result.condition = pick(result.condition, ['status', 'reason'])
+  result.observed_state = { status: 'unknown', reason: 'OMITTED' }
+  if (result.failure_code) delete result.error
+  else if (result.error) result.error = pick(result.error, ['code'])
+}
+function compactJourney(source: Payload): Payload {
+  const steps = Array.isArray(source.steps) ? source.steps.map(object) : []
+  const result: Payload = { ...pick(source, ['stopped_at_step_id']), success: source.success === true,
+    evidence: compactEvidence(source.evidence), diagnostics: interactionDiagnostics.retain(source),
+    observed_state: observedState(source.evidence), timing: pick(source.timing, ['total_ms']),
+    steps: steps.map(step => ({ ...pick(step, ['id', 'type', 'status', 'success', 'reason']),
+      result: step.result ? compactResult(object(step.result), String(step.type), 1080) : null })) }
+  if (source.error) {
+    const message = object(source.error).message
+    const bounded = boundedValue(message)
+    result.error = { ...pick(source.error, ['code']), message: bounded }
+    if (bounded !== message) result.truncated = true
+  }
+  if (source.system_trace) result.system_trace = pick(source.system_trace, ['trace_id', 'state', 'coverage', 'clock_alignment'])
+  enforceBudget(result, 1280 + 1280 * steps.length + steps.reduce((sum, s) => sum + idBytes(s.id) + deviceBytes(object(s.result).evidence), 0) + idBytes(source.stopped_at_step_id) + deviceBytes(source.evidence))
+  return result
+}
+export function finalizeCompactInteraction(name: string, args: ToolCallArgs, response: ToolCallResult) {
+  if (!compactInteractionTools.has(name) || (args.responseMode ?? (name === 'run_journey' ? 'compact' : 'debug')) !== 'compact') return response
+  const item = response.content.find(item => item.type === 'text')
+  if (item?.text) {
+    const source = object(JSON.parse(item.text))
+    item.text = JSON.stringify(name === 'run_journey' ? compactJourney(source) : compactResult(source, name))
+  }
+  return response
+}

package/src/server/handlers/compact-state.ts

@@ -0,0 +1,43 @@
+export type Payload = Record<string, unknown>
+export function object(value: unknown): Payload {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Payload : {}
+}
+export function pick(value: unknown, keys: string[]): Payload {
+  const source = object(value)
+  return Object.fromEntries(keys.filter(key => source[key] !== undefined).map(key => [key, source[key]]))
+}
+export function boundedValue(value: unknown): unknown {
+  if (typeof value !== 'string') return ['number', 'boolean'].includes(typeof value) || value === null ? value : undefined
+  let text = ''
+  for (const char of value) {
+    if (Buffer.byteLength(text + char) > 128) break
+    text += char
+  }
+  return text
+}
+export function observedState(evidence: unknown, dispatchStarted = false): Payload {
+  const e = object(evidence), device = object(e.device)
+  const observations = Array.isArray(e.observations) ? e.observations.map(object) : []
+  const candidates = observations.filter(o => ['ui_tree', 'fingerprint', 'screenshot'].includes(String(o.kind)))
+  const last = candidates.at(-1)
+  if (!last) return { status: 'unknown', reason: 'NO_POST_ACTION_OBSERVATION' }
+  const summary = pick(last, ['kind', 'source_captured_at_ms', 'freshness', 'snapshot_session_id', 'snapshot_revision'])
+  summary.captured_at_ms = summary.source_captured_at_ms ?? null
+  delete summary.source_captured_at_ms
+  const same = object(last.device).id === device.id && object(last.device).platform === device.platform && !!device.id
+  const post = typeof e.dispatch_completed_at_ms === 'number' && typeof last.capture_started_at_ms === 'number' && last.capture_started_at_ms >= e.dispatch_completed_at_ms
+  if (typeof last.source_captured_at_ms !== 'number' || last.source_captured_at_ms <= 0) return { status: 'unknown', reason: 'CAPTURE_TIME_UNKNOWN', ...summary }
+  if (last.status === 'captured' && last.freshness === 'fresh' && same && (!dispatchStarted || post)) return { status: 'observed', ...summary }
+  return { status: 'unknown', reason: !same ? 'DEVICE_MISMATCH' : !post && dispatchStarted ? 'NO_POST_ACTION_OBSERVATION' : 'OBSERVATION_UNAVAILABLE', ...summary }
+}
+export function deltaSummary(value: unknown) {
+  const delta = object(value)
+  return { ...pick(delta, ['base_snapshot_revision', 'snapshot_revision', 'truncated', 'omitted_changes']),
+    ...Object.fromEntries(['added', 'removed', 'changed'].map(key => [key, Array.isArray(delta[key]) ? delta[key].length : 0])) }
+}
+
+export function boundedState(value: unknown): unknown {
+  if (!value || typeof value !== 'object') return boundedValue(value)
+  const fields = pick(value, ['property', 'value', 'raw_value', 'checked', 'selected', 'expanded', 'enabled', 'text_value'])
+  return Object.fromEntries(Object.entries(fields).map(([key, item]) => [key, boundedValue(item)]).filter(([, item]) => item !== undefined))
+}

package/src/server/handlers/debugger-handlers.ts

@@ -1,7 +1,8 @@
+import { iosCapabilities } from '../../debugger/ios-worker.js'
 import { debuggerResponse } from './debugger-response.js'
 import { classify, type DebuggerDiagnostic } from '../../debugger/diagnostics.js'
 import { debuggerContracts } from '../schemas/debugger-schema.js'
-import { debuggerSessions, debuggerCapabilities } from '../../debugger/sessions.js'
+import { debuggerSessions, iosDebuggerSessions, debuggerCapabilities } from '../../debugger/sessions.js'
 import { DebuggerError, withDebuggerBudget } from '../../debugger/worker.js'
 import { wrapResponse, type ToolCallArgs } from '../common.js'
 function failure(code: string, summary: Record<string, unknown> = {}, diagnostic?: DebuggerDiagnostic, command = '', mode: 'compact' | 'debug' = 'debug') {
@@ -17,23 +18,41 @@ export async function handleDebugger(name: string, args: ToolCallArgs, signal?:
   const parsed = debuggerContracts[name].schema.safeParse(args)
   if (!parsed.success) return failure('INVALID_ARGUMENT')
   const { responseMode, ...input } = parsed.data
-  const a = input as { timeoutMs: number; deviceId?: string; appId?: string; processId?: number; debugSessionId?: string }
+  const a = input as { platform?: 'android' | 'ios'; timeoutMs: number; deviceId?: string; appId?: string; processId?: number; debugSessionId?: string }
   const command = debuggerContracts[name].command
+  const sessions = selectSessions(a)
   try {
     if (signal?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
-    const result = await withDebuggerBudget(a.timeoutMs, signal, async () => command === 'capabilities' ? await debuggerSessions.capabilities(a.deviceId!, a.appId!, a.processId) :
-      command === 'attach' ? await debuggerSessions.attach(a.deviceId!, a.appId!, a.processId, a.timeoutMs) :
-        await debuggerSessions.command(a.debugSessionId!, command, { ...a, signal: command === 'events' ? signal : undefined }, a.timeoutMs))
+    const result = await withDebuggerBudget(a.timeoutMs, signal, async () => command === 'capabilities' ? await sessions.capabilities(a.deviceId!, a.appId!, a.processId) :
+      command === 'attach' ? await sessions.attach(a.deviceId!, a.appId!, a.processId, a.timeoutMs) :
+        await sessions.command(a.debugSessionId!, command, { ...a, signal: command === 'events' ? signal : undefined }, a.timeoutMs))
     if (signal?.aborted && command === 'capabilities') throw new DebuggerError('DEBUGGER_CANCELLED')
-    return { ...wrapResponse(debuggerResponse(command, responseMode, result)), ...(!result.success ? { isError: true } : {}) }
+    const payload = sessions === iosDebuggerSessions ? iosDiagnostics(result) : result
+    return { ...wrapResponse(debuggerResponse(command, responseMode, payload)), ...(!result.success ? { isError: true } : {}) }
   } catch (e) {
     const error = classify(e, 'unknown', 'DEBUGGER_WORKER_FAILED')
     const code = error.code
     let summary: Partial<ReturnType<typeof debuggerSessions.summary>> = {}
-    if (a.debugSessionId) { try { summary = debuggerSessions.summary(a.debugSessionId) } catch { /* Unknown session */ } }
-    return failure(code, {
+    if (a.debugSessionId) { try { summary = sessions.summary(a.debugSessionId) } catch { /* Unknown session */ } }
+    const response = failure(code, {
+      ...(sessions === iosDebuggerSessions ? { capabilities: iosCapabilities } : {}),
       debug_session_id: a.debugSessionId ?? null,
-      device: a.deviceId ? { platform: 'android', id: a.deviceId } : null, ...summary
+      device: a.deviceId ? { platform: a.platform ?? 'android', id: a.deviceId } : null, ...summary
     }, code === 'DEBUGGER_CLEANUP_FAILED' ? summary.error?.diagnostic : error.diagnostic, command, responseMode)
+    if (sessions === iosDebuggerSessions) response.content[0].text = JSON.stringify(iosDiagnostics(JSON.parse(response.content[0].text)))
+    return response
   }
 }
+
+function selectSessions(a: { platform?: string; debugSessionId?: string }) {
+  return a.platform === 'ios' || (a.debugSessionId && iosDebuggerSessions.owns(a.debugSessionId)) ? iosDebuggerSessions : debuggerSessions
+}
+function iosRecovery(d: DebuggerDiagnostic) {
+  return { ...d, recovery: d.recovery.replace('JDK 17+ availability, including java, javac and jdk.jdi.', 'Xcode and its Swift-enabled LLDB/Python availability.').replace('JDK compiler and worker source/cache', 'LLDB worker source').replace('Java worker', 'LLDB worker').replace('ADB server', 'simulator') }
+}
+function iosDiagnostics<T extends Record<string, unknown>>(value: T) {
+  const result = { ...value }
+  const error = value.error as { diagnostic?: DebuggerDiagnostic } | undefined
+  return { ...result, ...(error?.diagnostic ? { error: { ...error, diagnostic: iosRecovery(error.diagnostic) } } : {}),
+    ...(Array.isArray(value.diagnostics) ? { diagnostics: (value.diagnostics as DebuggerDiagnostic[]).map(iosRecovery) } : {}) }
+}

package/src/server/handlers/diagnostic.ts

@@ -1,3 +1,4 @@
+import type { IosTemplate } from '../../observe/ios-trace/capabilities.js'
 import { systemTraces, TraceError } from '../../observe/system-trace.js'
 import { traceTargetSchema, traceStartSchema, traceControlSchema } from '../schemas/system-trace-schema.js'
 import { resolveTargetDevice } from '../../utils/resolve-device.js'
@@ -57,10 +58,10 @@ export async function handleSystemTrace(name: string, args: ToolCallArgs) {
   const parsed = schema.safeParse(args)
   if (!parsed.success) throw new TraceError('INVALID_ARGUMENT')
   if (name === 'get_system_trace_capabilities' || name === 'start_system_trace') {
-    const target = parsed.data as { platform: PlatformArg; deviceId?: string; durationMs?: number }
-    if (target.platform !== 'android') {
-      if (name === 'start_system_trace') throw new TraceError('UNSUPPORTED_PLATFORM')
-      return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: {}, reasons: ['UNSUPPORTED_PLATFORM'], enabled_sources: [], unavailable_categories: [], limitations: ['Android only'] })
+    const target = parsed.data as { platform: PlatformArg; deviceId?: string; durationMs?: number; appId?: string; template?: IosTemplate }
+    if (target.platform === 'android' && (target.appId !== undefined || target.template !== undefined)) throw new TraceError('INVALID_ARGUMENT')
+    if (target.platform === 'ios') {
+      return handleIosTrace(name, target)
     }
     let device
     try { device = await resolveTargetDevice(target) }
@@ -77,3 +78,9 @@ export async function handleSystemTrace(name: string, args: ToolCallArgs) {
   return { ...wrapResponse(result), ...(['failed', 'cancelled'].includes(result.state) ? { isError: true } : {}) }
 }
 
+async function handleIosTrace(name: string, target: { deviceId?: string; appId?: string; durationMs?: number; template?: IosTemplate }) {
+  if (!target.deviceId || (name === 'start_system_trace' && !target.appId)) throw new TraceError('INVALID_ARGUMENT')
+  if (name === 'get_system_trace_capabilities') return wrapResponse(await systemTraces.iosCapabilities(target.deviceId, target.appId, target.template))
+  const result = await systemTraces.start(target.deviceId, target.durationMs, { appId: target.appId!, template: target.template })
+  return { ...wrapResponse(result), ...(result.state === 'failed' ? { isError: true } : {}) }
+}

package/src/server/handlers/input.ts

@@ -34,6 +34,7 @@ export async function executeTap(args: ToolCallArgs) {
   const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
   const result = buildActionExecutionResult({
     actionType: 'tap',
+    device: res.device,
     sourceModule: 'server',
     selector: { x, y },
     success: !!res.success,
@@ -84,6 +85,7 @@ export async function executeSwipe(args: ToolCallArgs) {
   const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
   const result = buildActionExecutionResult({
     actionType: 'swipe',
+    device: res.device,
     sourceModule: 'server',
     selector: { x1, y1, x2, y2, duration },
     success: !!res.success,

package/src/server/handlers/interact.ts

@@ -1,3 +1,4 @@
+import { observeDeviceReadiness } from '../../observe/device-readiness.js'
 import type { UiSelector as ExpectElementSelectorArg } from '../../contracts/selector.js'
 import { markEvidenceVerification } from '../../observe/evidence.js'
 import { withReadyWait } from '../../observe/readiness-service.js'
@@ -86,6 +87,7 @@ export async function handleAdjustControl(args: ToolCallArgs) {
     platform,
     deviceId
   })
+  res.device_readiness = await observeDeviceReadiness(res.device)
   markEvidenceVerification()
   return wrapResponse(res)
 }