mobile-debug-mcp 0.36.0 → 0.37.0

package/src/observe/device-readiness.ts

@@ -0,0 +1,96 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { DeviceReadiness } from '../contracts/device-readiness.js'
+import type { DeviceInfo } from '../types.js'
+import { pausedReadiness } from '../debugger/guard.js'
+import { execCmd } from '../utils/exec.js'
+import { getAdbCmd } from '../utils/android/commands.js'
+import { getXcrunCmd } from '../utils/ios/utils.js'
+import { remainingBudget } from '../utils/operation-budget.js'
+import { benchmarkStage } from '../utils/benchmark-metrics.js'
+
+export function unknownDeviceReadiness(code?: string): DeviceReadiness {
+  return { wakefulness: 'unknown', lock_state: 'unknown', input_ready: null, blockers: [], evidence: [], limitations: code ? [code] : [] }
+}
+function values(text: string, pattern: RegExp) { return [...text.matchAll(pattern)].map(match => match[1]) }
+function unique(items: string[]) { return items.length > 0 && new Set(items).size === 1 ? items[0] : null }
+export function parseAndroidPower(text: string): DeviceReadiness['wakefulness'] {
+  // Later vendor/debug sections can repeat mWakefulness as a numeric enum.
+  // Classify only the named current-state section when its boundary is present.
+  const main = text.split('Power Manager State:')[1]
+  if (main?.includes('Settings and Configuration:')) text = main.split('Settings and Configuration:')[0]
+  const wake = unique(values(text, /^\s*mWakefulness=(\w+)\s*$/gm))
+  const changing = unique(values(text, /^\s*mWakefulnessChanging=(true|false)\s*$/gm))
+  if (!wake || !changing) return 'unknown'
+  if (changing === 'true') return 'transitioning'
+  return wake === 'Awake' ? 'awake' : ['Asleep', 'Dozing'].includes(wake) ? 'asleep' : 'unknown'
+}
+export function parseAndroidLock(text: string): DeviceReadiness['lock_state'] {
+  const section = text.split(/\bKeyguardServiceDelegate\s*\n/)[1]
+  if (!section) return 'unknown'
+  const showing = unique(values(section, /^\s*(?:showing|mIsShowing)=(true|false)\s*$/gm))
+  return showing === 'true' ? 'locked' : showing === 'false' ? 'unlocked' : 'unknown'
+}
+export function finishDeviceReadiness(state: DeviceReadiness): DeviceReadiness {
+  if (state.wakefulness === 'asleep') state.blockers.push('DEVICE_ASLEEP')
+  if (state.wakefulness === 'transitioning') state.blockers.push('DEVICE_TRANSITIONING')
+  if (state.lock_state === 'locked') state.blockers.push('DEVICE_LOCKED')
+  state.blockers = [...new Set(state.blockers)]
+  state.input_ready = state.blockers.length ? false : null
+  return state
+}
+export function parseIosLock(text: string): DeviceReadiness['lock_state'] {
+  try {
+    const data = JSON.parse(text)
+    if (data.error?.domain === 'com.apple.dt.CoreDeviceError' && data.error.code === 1001 &&
+      data.error.userInfo?.CapabilityFeatureIdentifier?.string === 'com.apple.coredevice.feature.getlockstate') return 'unsupported'
+    // Successful response semantics require runtime validation before classification.
+  } catch { /* Non-JSON output supplies no state evidence. */ }
+  return 'unknown'
+}
+type Probe = (command: string, args: string[], timeout: number) => Promise<{ exitCode: number | null; stdout: string; stderr: string }>
+const probes = new AsyncLocalStorage<Probe>()
+export function withDeviceReadinessProbe<T>(probe: Probe, operation: () => Promise<T>) { return probes.run(probe, operation) }
+const nativeProbe: Probe = (command, args, timeout) => execCmd(command, args, { timeout })
+export async function observeDeviceReadiness(device?: Pick<DeviceInfo, 'platform' | 'id'> | null, probe: Probe = probes.getStore() ?? nativeProbe): Promise<DeviceReadiness> {
+  return benchmarkStage('device_readiness_ms', () => observe(device, probe))
+}
+async function observe(device: Pick<DeviceInfo, 'platform' | 'id'> | null | undefined, probe: Probe): Promise<DeviceReadiness> {
+  const state = unknownDeviceReadiness()
+  if (!device?.id || !['android', 'ios'].includes(device.platform) || ['booted', 'default'].includes(device.id)) return unknownDeviceReadiness('DEVICE_TARGET_UNAVAILABLE')
+  const paused = pausedReadiness(device.id, device.platform)
+  if (paused) {
+    state.blockers.push('DEBUGGER_PAUSED')
+    state.evidence.push({ code: 'DEBUGGER_PAUSED', source: 'debugger', captured_at_ms: paused.captured_at_ms })
+    return finishDeviceReadiness(state)
+  }
+  if (device.platform === 'android') {
+    await androidProbe(state, device.id, 'power', probe)
+    await androidProbe(state, device.id, 'window', probe)
+  } else {
+    state.limitations.push('DEVICE_WAKEFULNESS_UNVERIFIED')
+    try {
+      const timeout = remainingBudget(1000)
+      // CoreDevice requires a CLI timeout of at least five seconds; the parent
+      // subprocess deadline still caps this read at one second.
+      const result = await probe(getXcrunCmd(), ['devicectl', 'device', 'info', 'lockState', '--device', device.id, '--timeout', '5', '--json-output', '-'], timeout)
+      remainingBudget()
+      state.lock_state = parseIosLock(result.stdout)
+      if (state.lock_state === 'unsupported') state.evidence.push({ code: 'DEVICE_LOCK_SIGNAL_UNSUPPORTED', source: 'coredevice', captured_at_ms: Date.now() })
+      else state.limitations.push('DEVICE_LOCK_OBSERVATION_UNAVAILABLE')
+    } catch { state.limitations.push('DEVICE_LOCK_OBSERVATION_FAILED') }
+  }
+  return finishDeviceReadiness(state)
+}
+async function androidProbe(state: DeviceReadiness, id: string, kind: 'power' | 'window', probe: Probe) {
+  try {
+    const timeout = remainingBudget(1000)
+    const result = await probe(getAdbCmd(), ['-s', id, 'shell', 'dumpsys', kind, ...(kind === 'window' ? ['policy'] : [])], timeout)
+    remainingBudget()
+    if (result.exitCode !== 0) throw new Error('PROBE_FAILED')
+    const value = kind === 'power' ? parseAndroidPower(result.stdout) : parseAndroidLock(result.stdout)
+    if (kind === 'power') state.wakefulness = value as DeviceReadiness['wakefulness']
+    else state.lock_state = value as DeviceReadiness['lock_state']
+    if (value === 'unknown') state.limitations.push(kind === 'power' ? 'DEVICE_WAKEFULNESS_UNVERIFIED' : 'DEVICE_LOCK_STATE_UNVERIFIED')
+    else state.evidence.push({ code: `DEVICE_${value.toUpperCase()}`, source: `android_${kind}`, captured_at_ms: Date.now() })
+  } catch { state.limitations.push(kind === 'power' ? 'DEVICE_POWER_OBSERVATION_FAILED' : 'DEVICE_LOCK_OBSERVATION_FAILED') }
+}

package/src/observe/evidence.ts

@@ -214,15 +214,25 @@ export function refreshJourneyEvidence(steps: Array<{ result?: { evidence?: unkn
   const current = context.getStore()
   if (!current) return
   for (const step of steps) {
-    const previous = step.result?.evidence as { action_id?: string } | undefined
+    const previous = step.result?.evidence as { action_id?: string; observations?: Array<{ evidence_id: string }> } | undefined
     const child = current.children.find(c => c.action?.id === previous?.action_id)
     if (child && step.result) step.result.evidence = assemble(child)
+    else if (previous?.observations && step.result) {
+      const ids = new Set(previous.observations.map(o => o.evidence_id))
+      step.result.evidence = assemble({ ...current, observations: current.observations.filter(o => ids.has(o.value.evidence_id)) })
+    }
   }
 }
 
 export function completeJourneyVerification(actionId: string) {
   const child = context.getStore()?.children.find(c => c.action?.id === actionId)
   if (child?.action) {
+    const parent = context.getStore()!
+    const completed = child.action.dispatchEnd?.mono
+    if (completed !== undefined) {
+      const after = parent.observations.filter(o => o.start.mono >= completed && sameDevice(o.value.device, child.action!.device))
+      child.observations.push(...after)
+    }
     child.verification = stamp()
     child.action.verification = child.verification
   }
@@ -312,3 +322,22 @@ function recordCaptureTime(acquisition: Acquisition, result: EvidencePayload | n
     acquisition.reused = source < start.wall
   }
 }
+
+export class JourneyStepError extends Error {
+  constructor(readonly evidence: ReturnType<typeof assemble>, cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause })
+  }
+}
+
+/** Retain per-step evidence without changing the parent journey's acquisition flow. */
+export async function withJourneyStepEvidence<T>(operation: () => Promise<T>) {
+  const current = context.getStore()
+  const start = current?.observations.length ?? 0
+  try {
+    const result = await operation()
+    return { ...result, ...(current ? { evidence: assemble({ ...current, observations: current.observations.slice(start) }) } : {}) }
+  } catch (error) {
+    if (current) throw new JourneyStepError(assemble({ ...current, observations: current.observations.slice(start) }), error)
+    throw error
+  }
+}

package/src/observe/ios-trace/sessions.ts

@@ -143,10 +143,12 @@ export class IosTraceSessions {
     } catch (error) {
       this.fail(s, reasonFor(error, s.recording?.recorder.alive() ? 'TRACE_STOP_FAILED' : 'TRACE_ARTIFACT_FAILED'))
       s.result.cleanup.status = 'failed'
-      if (s.result.reason === 'STORAGE_LIMIT' && !s.recording?.recorder.alive()) await this.discardOversized(s)
+      // Stop timeouts can throw after SIGKILL has already closed the recorder.
+      // Discarding is safe only after exit; keep the failure but release owned files.
+      if ((s.discard || s.result.reason === 'STORAGE_LIMIT') && !s.recording?.recorder.alive()) await this.discardStoppedFiles(s)
     }
   }
-  private async discardOversized(s: Session) {
+  private async discardStoppedFiles(s: Session) {
     try {
       if (s.directory) await fs.rm(s.directory, { recursive: true, force: true })
       s.result.cleanup = { status: 'complete', remaining_resources: [] }; s.terminal = this.time.mono()

package/src/observe/readiness-service.ts

@@ -1,3 +1,4 @@
+import { unknownDeviceReadiness, observeDeviceReadiness } from './device-readiness.js'
 import { pausedReadiness } from '../debugger/guard.js'
 import type { DeviceInfo } from '../types.js'
 import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js'
@@ -20,10 +21,15 @@ export async function readinessDelay(ms: number) {
   remainingBudget()
 }
 
+function observationComplete(tracker: ReadinessTracker, wait: boolean, count: number) {
+  return tracker.ready || (!wait && (tracker.summary.state === 'loading' || count === 2))
+}
+
 export async function getAppReadiness(args: Target & { timeoutMs?: number; stabilityMs?: number; pollIntervalMs?: number }, wait = false) {
   const started = performance.now()
   let device: DeviceInfo | null = null
   let tracker = new ReadinessTracker(args.platform ?? 'android', args.deviceId ?? '')
+  tracker.deviceReadiness = unknownDeviceReadiness('DEVICE_TARGET_UNAVAILABLE')
   let failureCode: string | undefined
   let debugPause: ReturnType<typeof pausedReadiness> = null
   await runWithBudget(args.timeoutMs ?? (wait ? 30000 : 15000), async () => {
@@ -36,7 +42,13 @@ export async function getAppReadiness(args: Target & { timeoutMs?: number; stabi
         while (wait || count < 2) {
           remainingBudget()
           debugPause = pausedReadiness(device!.id, device!.platform)
-          if (debugPause) { failureCode = wait ? 'DEBUGGER_PAUSED' : undefined; return }
+          if (debugPause) { tracker.deviceReadiness = await observeDeviceReadiness(device); failureCode = wait ? 'DEBUGGER_PAUSED' : undefined; return }
+          await tracker.observeDevice()
+          if (tracker.deviceReadiness.input_ready === false) {
+            if (!wait) return
+            await readinessDelay(args.pollIntervalMs ?? 500)
+            continue
+          }
           const captureStarted = Date.now()
           try {
             const tree = await ToolsObserve.getUITreeHandler({ platform: device!.platform as 'android' | 'ios', deviceId: device!.id })
@@ -49,8 +61,7 @@ export async function getAppReadiness(args: Target & { timeoutMs?: number; stabi
             if (isDeviceUnavailable(error)) { failureCode = 'DEVICE_UNAVAILABLE'; return }
           }
           count++
-          if (tracker.summary.state === 'settled' || (!wait && tracker.summary.state === 'loading')) return
-          if (!wait && count === 2) return
+          if (observationComplete(tracker, wait, count)) return
           await readinessDelay(wait ? args.pollIntervalMs ?? 500 : args.stabilityMs ?? 500)
         }
       })
@@ -61,11 +72,11 @@ export async function getAppReadiness(args: Target & { timeoutMs?: number; stabi
       failureCode = !expired && (!device || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE'
     }
   })
-  if (debugPause) return { success: !wait, device, readiness: debugPause, elapsed_ms: performance.now() - started, ...(wait ? { failure_code: 'DEBUGGER_PAUSED' } : {}) }
+  if (debugPause) return { success: !wait, device, readiness: debugPause, device_readiness: tracker.deviceReadiness, elapsed_ms: performance.now() - started, ...(wait ? { failure_code: 'DEBUGGER_PAUSED' } : {}) }
   const state = tracker.summary.state
-  const success = !failureCode && (wait ? state === 'settled' : state !== 'unknown')
+  const success = !failureCode && (wait ? tracker.ready : state !== 'unknown' || tracker.deviceReadiness.input_ready === false)
   return {
-    success, device, readiness: tracker.summary, elapsed_ms: performance.now() - started,
+    success, device, readiness: tracker.summary, device_readiness: tracker.deviceReadiness, elapsed_ms: performance.now() - started,
     ...(!success ? { failure_code: failureCode ?? (wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE') } : {})
   }
 }
@@ -73,6 +84,7 @@ export async function getAppReadiness(args: Target & { timeoutMs?: number; stabi
 export async function withReadyWait<T extends object | undefined, F extends object>(target: Target, timeoutMs: number, operation: (device: DeviceInfo) => Promise<T>, failure: (code: string, elapsedMs: number, samples: number) => F) {
   const started = performance.now()
   let tracker = new ReadinessTracker(target.platform ?? 'android', target.deviceId ?? '')
+  tracker.deviceReadiness = unknownDeviceReadiness('DEVICE_TARGET_UNAVAILABLE')
   let resolved = false
   return runWithBudget(timeoutMs, async () => {
     try {
@@ -83,14 +95,14 @@ export async function withReadyWait<T extends object | undefined, F extends obje
       const result = await withResolvedDevice(device, () => withReadinessTracker(tracker, () => operation(device)))
       try { remainingBudget() } catch {
         const alreadyFailed = result && (('status' in result && result.status !== 'success') || ('success' in result && result.success === false))
-        return { ...(alreadyFailed ? result : failure('TIMEOUT', performance.now() - started, tracker.summary.sample_count)), readiness: tracker.deadline() }
+        return { ...(alreadyFailed ? result : failure('TIMEOUT', performance.now() - started, tracker.summary.sample_count)), readiness: tracker.deadline(), device_readiness: tracker.deviceReadiness }
       }
-      return { ...result, readiness: tracker.summary }
+      return { ...result, readiness: tracker.summary, device_readiness: tracker.deviceReadiness }
     } catch (error) {
       const expired = budgetExpired(error)
       if (expired) tracker.deadline()
       else tracker.unavailable()
-      return { ...failure(!expired && (!resolved || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : 'TIMEOUT', performance.now() - started, tracker.summary.sample_count), readiness: tracker.summary }
+      return { ...failure(!expired && (!resolved || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : 'TIMEOUT', performance.now() - started, tracker.summary.sample_count), readiness: tracker.summary, device_readiness: tracker.deviceReadiness }
     }
   })
 }

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
@@ -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/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/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)
 }