mobile-debug-mcp 0.32.2 → 0.33.0

package/dist/observe/readiness-service.js

@@ -0,0 +1,115 @@
+import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js';
+import { remainingBudget, runWithBudget } from '../utils/operation-budget.js';
+import { ToolsObserve } from './index.js';
+import { isDeviceUnavailable, ReadinessTracker, withReadinessTracker } from './readiness.js';
+function budgetExpired(error) {
+    if (/ACTION_TIMEOUT/.test(String(error)))
+        return true;
+    try {
+        remainingBudget();
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+async function resolve(target) {
+    if (target.platform)
+        return resolveTargetDevice({ ...target, platform: target.platform });
+    try {
+        return await resolveTargetDevice({ ...target, platform: 'android' });
+    }
+    catch {
+        return resolveTargetDevice({ ...target, platform: 'ios' });
+    }
+}
+export async function readinessDelay(ms) {
+    await new Promise(resolve => setTimeout(resolve, Math.min(ms, remainingBudget(ms))));
+    remainingBudget();
+}
+export async function getAppReadiness(args, wait = false) {
+    const started = performance.now();
+    let device = null;
+    let tracker = new ReadinessTracker(args.platform ?? 'android', args.deviceId ?? '');
+    let failureCode;
+    await runWithBudget(args.timeoutMs ?? (wait ? 30000 : 15000), async () => {
+        try {
+            device = await resolve(args);
+            remainingBudget();
+            tracker = new ReadinessTracker(device.platform, device.id, args.stabilityMs ?? 500);
+            await withResolvedDevice(device, async () => {
+                let count = 0;
+                while (wait || count < 2) {
+                    remainingBudget();
+                    const captureStarted = Date.now();
+                    try {
+                        const tree = await ToolsObserve.getUITreeHandler({ platform: device.platform, deviceId: device.id });
+                        remainingBudget();
+                        tracker.observe(tree, captureStarted);
+                        if (isDeviceUnavailable(tree?.error)) {
+                            failureCode = 'DEVICE_UNAVAILABLE';
+                            return;
+                        }
+                    }
+                    catch (error) {
+                        if (/ACTION_TIMEOUT/.test(String(error)))
+                            throw error;
+                        tracker.unavailable();
+                        if (isDeviceUnavailable(error)) {
+                            failureCode = 'DEVICE_UNAVAILABLE';
+                            return;
+                        }
+                    }
+                    count++;
+                    if (tracker.summary.state === 'settled' || (!wait && tracker.summary.state === 'loading'))
+                        return;
+                    if (!wait && count === 2)
+                        return;
+                    await readinessDelay(wait ? args.pollIntervalMs ?? 500 : args.stabilityMs ?? 500);
+                }
+            });
+        }
+        catch (error) {
+            const expired = budgetExpired(error);
+            if (expired)
+                tracker.deadline();
+            else
+                tracker.unavailable();
+            failureCode = !expired && (!device || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE';
+        }
+    });
+    const state = tracker.summary.state;
+    const success = !failureCode && (wait ? state === 'settled' : state !== 'unknown');
+    return { success, device, readiness: tracker.summary, elapsed_ms: performance.now() - started,
+        ...(!success ? { failure_code: failureCode ?? (wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE') } : {}) };
+}
+export async function withReadyWait(target, timeoutMs, operation, failure) {
+    const started = performance.now();
+    let tracker = new ReadinessTracker(target.platform ?? 'android', target.deviceId ?? '');
+    let resolved = false;
+    return runWithBudget(timeoutMs, async () => {
+        try {
+            const device = await resolve(target);
+            resolved = true;
+            remainingBudget();
+            tracker = new ReadinessTracker(device.platform, device.id);
+            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 { ...result, readiness: tracker.summary };
+        }
+        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 };
+        }
+    });
+}

package/dist/observe/readiness.js

@@ -0,0 +1,81 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { remainingBudget } from '../utils/operation-budget.js';
+import { computeSnapshotSignature, getSnapshotSessionId } from './snapshot-metadata.js';
+const baselineLimitations = ['NORMALIZED_UI_ONLY', 'FOREGROUND_APP_UNVERIFIED', 'UNRESPONSIVE_SIGNAL_UNSUPPORTED', 'DEBUGGER_SIGNAL_UNSUPPORTED'];
+const capabilities = { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: false };
+export function isDeviceUnavailable(error) {
+    return /device.*(?:not found|offline|disconnected)|no devices found|READINESS_DEVICE_UNAVAILABLE/i.test(String(error));
+}
+export class ReadinessTracker {
+    platform;
+    deviceId;
+    stabilityMs;
+    signature = null;
+    stableSince = 0;
+    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, 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities }
+    };
+    constructor(platform, deviceId, stabilityMs = 500) {
+        this.platform = platform;
+        this.deviceId = deviceId;
+        this.stabilityMs = stabilityMs;
+    }
+    unavailable(code = 'OBSERVATION_FAILED') {
+        this.signature = null;
+        this.summary = { ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
+            sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, code],
+            evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8) };
+        return this.summary;
+    }
+    deadline() {
+        this.summary = { ...this.summary, limitations: [...new Set([...this.summary.limitations, 'DEADLINE_EXCEEDED'])] };
+        return this.summary;
+    }
+    observe(tree, acquisitionStartedAtMs, now = performance.now()) {
+        if (tree?.error)
+            return this.unavailable('OBSERVATION_FAILED');
+        if (!tree || tree.device?.platform !== this.platform || tree.device?.id !== this.deviceId ||
+            tree.snapshot_session_id !== getSnapshotSessionId() || !Number.isSafeInteger(tree.snapshot_revision) || tree.snapshot_revision <= 0 ||
+            !Number.isFinite(tree.captured_at_ms) || tree.captured_at_ms < acquisitionStartedAtMs || tree.captured_at_ms <= 0 ||
+            !Array.isArray(tree.elements) || !tree.elements.length || tree.elements.some((element) => !element || typeof element !== 'object') ||
+            !Number.isFinite(tree.resolution?.width) || !Number.isFinite(tree.resolution?.height) || tree.resolution.width <= 0 || tree.resolution.height <= 0)
+            return this.unavailable('OBSERVATION_INVALID');
+        const signature = computeSnapshotSignature(tree);
+        if (!signature)
+            return this.unavailable('OBSERVATION_INVALID');
+        const nativeLoading = tree.elements.some((element) => element.visible === true && ['android.widget.ProgressBar', 'ActivityIndicator', 'ProgressIndicator'].includes(element.type));
+        const textLoading = tree.elements.some((element) => element.visible === true && [element.text, element.contentDescription].some(label => typeof label === 'string' && /^(loading|please\s+wait)[.\s…]*$/i.test(label.trim())));
+        const previous = this.signature;
+        const unchanged = previous === signature;
+        if (!unchanged || nativeLoading || textLoading)
+            this.stableSince = now;
+        this.signature = signature;
+        const stableFor = unchanged && !nativeLoading && !textLoading ? Math.max(0, now - this.stableSince) : 0;
+        const state = nativeLoading || textLoading ? 'loading' : !previous ? 'unknown' : !unchanged ? 'transitioning' : stableFor >= this.stabilityMs ? 'settled' : 'unknown';
+        const code = nativeLoading ? 'NATIVE_LOADING_INDICATOR' : textLoading ? 'LOADING_LABEL' : state === 'transitioning' ? 'SNAPSHOT_CHANGED' : state === 'settled' ? 'SNAPSHOT_STABLE' : 'INSUFFICIENT_SAMPLES';
+        this.summary = {
+            state, scope: 'device_ui', basis: textLoading && !nativeLoading ? 'heuristic' : state === 'unknown' ? 'insufficient' : 'observed',
+            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, ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities }
+        };
+        return this.summary;
+    }
+}
+const waits = new AsyncLocalStorage();
+export function currentReadinessWait() { return waits.getStore(); }
+export function withReadinessTracker(tracker, operation) { return waits.run(tracker, operation); }
+export function observeReadinessWait(tree, startedAtMs) {
+    const tracker = waits.getStore();
+    if (!tracker)
+        return;
+    remainingBudget();
+    const summary = tracker.observe(tree, startedAtMs);
+    if (isDeviceUnavailable(tree?.error))
+        throw new Error('READINESS_DEVICE_UNAVAILABLE');
+    if (summary.limitations.some(code => ['OBSERVATION_INVALID', 'OBSERVATION_FAILED'].includes(code)))
+        throw new Error('READINESS_SAMPLE_INVALID');
+}

package/dist/observe/recording.js

@@ -0,0 +1,165 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execCmd } from '../utils/exec.js';
+import { getAdbCmd } from '../utils/android/utils.js';
+import { resolveTargetDevice } from '../utils/resolve-device.js';
+const recordings = new Map();
+const activeDevices = new Map();
+const adb = (deviceId, args, timeout = 15000) => execCmd(getAdbCmd(), ['-s', deviceId, ...args], { timeout });
+const tool = (name, args, timeout = 30000) => execCmd(name, args, { timeout });
+const swiftScript = fileURLToPath(new URL('../../scripts/recording-frames.swift', import.meta.url));
+async function swiftDecode(video, directory, startMs, endMs) {
+    const result = await tool('xcrun', ['swift', swiftScript, video, directory, String(startMs), String(endMs)], 120000);
+    if (result.exitCode !== 0)
+        throw new Error(`Swift frame decoder failed: ${result.stderr}`);
+    return JSON.parse(result.stdout);
+}
+function positiveInteger(value, name, max) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > max)
+        throw new Error(`${name} must be an integer from 1 to ${max}`);
+    return value;
+}
+async function probe(video) {
+    let result;
+    try {
+        result = await tool('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height,nb_frames:format=duration', '-of', 'json', video]);
+    }
+    catch (error) {
+        if (process.platform !== 'darwin')
+            throw error;
+        const metadata = await swiftDecode(video, path.join(path.dirname(video), 'metadata'), 1, 0);
+        const { frames: _frames, ...rest } = metadata;
+        return rest;
+    }
+    if (result.exitCode !== 0)
+        throw new Error(`ffprobe failed: ${result.stderr || 'ffprobe is required for recording metadata and frame extraction'}`);
+    const data = JSON.parse(result.stdout);
+    const stream = data.streams?.[0];
+    if (!stream)
+        throw new Error('Recording contains no video stream');
+    const frames = await frameTimes(video);
+    return { durationMs: Math.round(Number(data.format.duration) * 1000), resolution: { width: stream.width, height: stream.height }, frameCount: frames.length, frameTimestampsMs: frames };
+}
+async function frameTimes(video) {
+    const result = await tool('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'frame=best_effort_timestamp_time', '-of', 'json', video], 60000);
+    if (result.exitCode !== 0)
+        throw new Error(`ffprobe failed: ${result.stderr || 'ffprobe is required'}`);
+    return (JSON.parse(result.stdout).frames ?? []).map((frame) => Math.round(Number(frame.best_effort_timestamp_time) * 1000)).filter((value) => Number.isFinite(value));
+}
+export async function startScreenRecording(deviceId, maxDurationSeconds = 15) {
+    if (deviceId !== undefined && (typeof deviceId !== 'string' || !deviceId))
+        throw new Error('deviceId must be a nonempty string');
+    const durationLimit = positiveInteger(maxDurationSeconds, 'maxDurationSeconds', 180);
+    const device = await resolveTargetDevice({ platform: 'android', deviceId: deviceId });
+    if (activeDevices.has(device.id))
+        throw new Error(`A recording is already active for device ${device.id}`);
+    const id = randomUUID();
+    const directory = path.join(tmpdir(), 'mobile-debug-mcp-recordings', id);
+    const remote = `/sdcard/mobile-debug-mcp-${id}.mp4`;
+    await mkdir(directory, { recursive: true });
+    let finish;
+    const finished = new Promise(resolve => { finish = resolve; });
+    const child = spawn(getAdbCmd(), ['-s', device.id, 'shell', 'screenrecord', '--time-limit', String(durationLimit), remote], { stdio: 'ignore' });
+    const timer = setTimeout(() => { void stopScreenRecording(id).catch(() => undefined); }, (durationLimit + 2) * 1000);
+    timer.unref();
+    const recording = { id, deviceId: device.id, remote, directory, video: path.join(directory, 'recording.mp4'), startedAt: new Date().toISOString(), durationLimit, process: child, timer, state: 'recording', finished, finish };
+    recordings.set(id, recording);
+    activeDevices.set(device.id, id);
+    child.once('close', () => { finish(); if (recording.state === 'recording')
+        void stopScreenRecording(id).catch(() => undefined); });
+    child.once('error', () => { finish(); if (recording.state === 'recording')
+        void stopScreenRecording(id).catch(() => undefined); });
+    return { recordingId: id, deviceId: device.id, startedAt: recording.startedAt, maxDurationSeconds: durationLimit };
+}
+export async function stopScreenRecording(recordingId) {
+    const recording = typeof recordingId === 'string' ? recordings.get(recordingId) : undefined;
+    if (!recording)
+        throw new Error('Unknown recordingId');
+    if (recording.stopPromise)
+        return recording.stopPromise;
+    recording.state = 'stopping';
+    clearTimeout(recording.timer);
+    recording.stopPromise = (async () => {
+        try {
+            if (recording.process.exitCode === null) {
+                const processes = await adb(recording.deviceId, ['shell', 'ps', '-A', '-o', 'PID,ARGS']).catch(() => null);
+                const pid = processes?.stdout.split('\n').find(line => line.includes('screenrecord') && line.includes(recording.remote))?.trim().match(/^\d+/)?.[0];
+                if (pid)
+                    await adb(recording.deviceId, ['shell', 'kill', '-2', pid]).catch(() => undefined);
+            }
+            await Promise.race([recording.finished, new Promise(resolve => setTimeout(resolve, 3000))]);
+            if (recording.process.exitCode === null)
+                recording.process.kill('SIGKILL');
+            const pulled = await adb(recording.deviceId, ['pull', recording.remote, recording.video], 30000);
+            if (pulled.exitCode !== 0)
+                throw new Error(`Could not pull recording: ${pulled.stderr}`);
+            if ((await stat(recording.video)).size === 0)
+                throw new Error('Recording is empty');
+            let metadata;
+            try {
+                metadata = await probe(recording.video);
+            }
+            catch (error) {
+                metadata = { metadataError: String(error), durationMs: null, resolution: null, frameCount: null, frameTimestampsMs: [] };
+            }
+            recording.result = { recordingId: recording.id, deviceId: recording.deviceId, videoPath: recording.video, startedAt: recording.startedAt, stoppedAt: new Date().toISOString(), ...metadata };
+            return recording.result;
+        }
+        finally {
+            await adb(recording.deviceId, ['shell', 'rm', '-f', recording.remote]).catch(() => undefined);
+            activeDevices.delete(recording.deviceId);
+            recording.state = 'stopped';
+            if (!recording.result) {
+                recordings.delete(recording.id);
+                await rm(recording.directory, { recursive: true, force: true }).catch(() => undefined);
+            }
+        }
+    })();
+    return recording.stopPromise;
+}
+export async function extractRecordingFrames(recordingId, startMs, endMs) {
+    const recording = typeof recordingId === 'string' ? recordings.get(recordingId) : undefined;
+    if (!recording || recording.state !== 'stopped' || !recording.result)
+        throw new Error('Unknown or unfinished recordingId');
+    if (typeof startMs !== 'number' || !Number.isInteger(startMs) || startMs < 0 || typeof endMs !== 'number' || !Number.isInteger(endMs) || endMs <= startMs || endMs - startMs > 10000)
+        throw new Error('Window must be 1 to 10000 ms with nonnegative integer timestamps');
+    const directory = path.join(recording.directory, `frames-${startMs}-${endMs}`);
+    await rm(directory, { recursive: true, force: true });
+    await mkdir(directory, { recursive: true });
+    let allTimes;
+    let frames;
+    try {
+        allTimes = await frameTimes(recording.video);
+        const selected = allTimes.filter(time => time >= startMs && time <= endMs);
+        const result = await tool('ffmpeg', ['-v', 'error', '-i', recording.video, '-vf', `select=between(t\,${startMs / 1000}\,${endMs / 1000})`, '-vsync', '0', path.join(directory, '%06d.png')], 60000);
+        if (result.exitCode !== 0)
+            throw new Error(`ffmpeg failed: ${result.stderr || 'ffmpeg is required for frame extraction'}`);
+        const files = (await readdir(directory)).filter(file => file.endsWith('.png')).sort();
+        if (files.length !== selected.length)
+            throw new Error(`Frame count mismatch: ffprobe found ${selected.length}, ffmpeg extracted ${files.length}`);
+        frames = files.map((file, index) => ({ timestampMs: selected[index], path: path.join(directory, file) }));
+    }
+    catch (error) {
+        if (process.platform !== 'darwin')
+            throw error;
+        const decoded = await swiftDecode(recording.video, directory, startMs, endMs);
+        allTimes = decoded.frameTimestampsMs;
+        frames = decoded.frames;
+    }
+    const selected = frames.map(frame => frame.timestampMs);
+    const deltas = allTimes.slice(1).map((time, index) => time - allTimes[index]).filter(delta => delta > 0).sort((a, b) => a - b);
+    const nominalMs = deltas.length ? deltas[Math.floor((deltas.length - 1) / 2)] : null;
+    const gaps = allTimes.slice(1).flatMap((time, index) => nominalMs && time - allTimes[index] > nominalMs * 1.5 && time >= startMs && allTimes[index] <= endMs ? [{ startMs: allTimes[index], endMs: time, durationMs: time - allTimes[index] }] : []);
+    if (selected.length === 0 || selected[0] > startMs + (nominalMs ?? 0) * 1.5)
+        gaps.unshift({ startMs, endMs: selected[0] ?? endMs, durationMs: (selected[0] ?? endMs) - startMs });
+    if (selected.length && selected[selected.length - 1] < endMs - (nominalMs ?? 0) * 1.5)
+        gaps.push({ startMs: selected[selected.length - 1], endMs, durationMs: endMs - selected[selected.length - 1] });
+    return { recordingId, startMs, endMs, frames, frameCount: frames.length, nominalFrameIntervalMs: nominalMs, captureGaps: gaps, continuousCoverage: gaps.length === 0, note: 'Frames are encoded samples. A gap may hide a brief flash; absence cannot be established across gaps.' };
+}
+export async function shutdownRecordings() {
+    await Promise.allSettled([...activeDevices.values()].map(id => stopScreenRecording(id)));
+}

package/dist/observe/snapshot-metadata.js

@@ -1,6 +1,14 @@
 import crypto from 'crypto';
 let nextRevision = 1;
+const snapshotSessionId = crypto.randomUUID();
 const snapshotStateByDevice = new Map();
+export function getSnapshotSessionId() { return snapshotSessionId; }
+export function hasSnapshotBaseline(deviceKey, revision) {
+    const state = snapshotStateByDevice.get(deviceKey);
+    const capturedAt = state?.historyTimes.get(revision);
+    return !!state && capturedAt !== undefined && state.history.has(revision) &&
+        Date.now() - capturedAt <= 10 * 60 * 1000 && Date.now() - state.updatedAt <= 10 * 60 * 1000;
+}
 function normalize(value) {
     if (value === null || value === undefined)
         return '';
@@ -135,8 +143,7 @@ export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverrid
     const oversized = previous?.oversized ?? new Map();
     if (hasValidTree) {
         history.set(revision, currentElements);
-        if (!historyTimes.has(revision))
-            historyTimes.set(revision, Date.now());
+        historyTimes.set(revision, Date.now());
         if ((tree.elements?.length ?? 0) > 500)
             oversized.set(revision, (tree.elements?.length ?? 0) - 500);
     }
@@ -164,6 +171,7 @@ export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverrid
         updatedAt: Date.now()
     });
     return {
+        snapshot_session_id: snapshotSessionId,
         snapshot_revision: revision,
         captured_at_ms: Date.now(),
         snapshot_delta: hasValidTree ? summarizeSnapshotDelta(previous, currentElementSignatures) : null,

package/dist/server/common.js

@@ -1,5 +1,7 @@
+import { currentEvidenceActionId } from '../observe/evidence.js';
 import { recordTiming } from '../utils/timing.js';
 import { ToolsObserve } from '../observe/index.js';
+import { isConditionBlocked } from '../interact/conditional-action.js';
 export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3;
 export const DEFAULT_MAX_RETRY_DEPTH = 3;
 export function wrapResponse(data, includeSerializationTiming = true) {
@@ -62,10 +64,15 @@ export function getArrayArg(args, key) {
 }
 let actionSequence = 0;
 export function nextActionId(actionType, timestamp) {
+    const current = currentEvidenceActionId();
+    if (current)
+        return current;
     actionSequence += 1;
     return `${actionType}_${timestamp}_${actionSequence}`;
 }
 export async function captureActionFingerprint(platform, deviceId) {
+    if (isConditionBlocked())
+        return null;
     if (!platform)
         return null;
     try {
@@ -235,6 +242,8 @@ function mapFailureCodeToFailureClass(code) {
         case 'STALE_REFERENCE':
             return 'TargetResolutionFailure';
         case 'ELEMENT_NOT_INTERACTABLE':
+        case 'PRECONDITION_FAILED':
+        case 'PRECONDITION_UNAVAILABLE':
         case 'ACTION_TIMEOUT':
             return 'ExecutionFailure';
         case 'TIMEOUT':

package/dist/server/condition-schema.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export const conditionalTools = new Set(['tap', 'tap_element', 'swipe', 'type_text', 'press_back']);
+export const expectedStateSchema = z.object({
+    snapshotSessionId: z.string().min(1),
+    snapshotRevision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    timeoutMs: z.number().int().min(100).max(60000).optional()
+}).strict();
+export const expectedStateJson = {
+    type: 'object', additionalProperties: false,
+    properties: {
+        snapshotSessionId: { type: 'string', minLength: 1 },
+        snapshotRevision: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER },
+        timeoutMs: { type: 'integer', minimum: 100, maximum: 60000, default: 15000 }
+    },
+    required: ['snapshotSessionId', 'snapshotRevision']
+};
+export function validateExpectedState(name, args) {
+    if (args.expectedState === undefined)
+        return undefined;
+    if (!conditionalTools.has(name))
+        throw new Error('INVALID_ARGUMENT: expectedState is not supported on this tool');
+    const parsed = expectedStateSchema.safeParse(args.expectedState);
+    if (!parsed.success)
+        throw new Error('INVALID_ARGUMENT: invalid expectedState');
+    if ((args.platform !== 'android' && args.platform !== 'ios') ||
+        typeof args.deviceId !== 'string' || !args.deviceId.trim() ||
+        ['booted', 'default'].includes(args.deviceId))
+        throw new Error('INVALID_ARGUMENT: expectedState requires an explicit platform and concrete deviceId');
+    if (['type_text', 'press_back'].includes(name) && args.platform !== 'android')
+        throw new Error('INVALID_ARGUMENT: this action supports only Android');
+    return parsed.data;
+}

package/dist/server/journey-schema.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { expectedStateSchema, expectedStateJson } from './condition-schema.js';
 const selector = z.object({
     text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
     accessibility_id: z.string().min(1).optional(), contains: z.boolean().optional()
@@ -22,7 +23,7 @@ const assertion = z.union([
 const id = z.string().min(1);
 const step = z.union([
     z.object({ id, type: z.literal('start_app'), appId: z.string().min(1), verificationMode: verificationMode.optional() }).strict(),
-    z.object({ id, type: z.literal('tap'), ...target, waitFor: waitFor.optional(), verificationMode: verificationMode.optional() }).strict().refine(exactlyOneTarget),
+    z.object({ id, type: z.literal('tap'), ...target, waitFor: waitFor.optional(), verificationMode: verificationMode.optional(), expectedState: expectedStateSchema.optional() }).strict().refine(exactlyOneTarget),
     z.object({ id, type: z.literal('wait'), selector, condition: z.enum(['exists', 'not_exists', 'visible', 'clickable']).optional(), timeoutMs, pollIntervalMs }).strict(),
     z.object({ id, type: z.literal('assert'), assertion, timeoutMs, pollIntervalMs }).strict()
 ]);
@@ -46,7 +47,7 @@ const objectJson = (properties, required, extra = {}) => ({ type: 'object', addi
 export const journeyStepsJson = {
     type: 'array', minItems: 1, maxItems: 50, items: { oneOf: [
             objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'start_app' }, appId: { type: 'string', minLength: 1 }, verificationMode: modeJson }, ['id', 'type', 'appId']),
-            objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'tap' }, ...targetJson, verificationMode: modeJson,
+            objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'tap' }, ...targetJson, verificationMode: modeJson, expectedState: expectedStateJson,
                 waitFor: objectJson({ ...intervalJson, timeoutMs: { type: 'integer', minimum: 100, maximum: 10000 }, condition: { enum: ['exists', 'visible', 'clickable'] }, match: objectJson({ index: { type: 'integer', minimum: 0 } }, []) }, [])
             }, ['id', 'type'], { oneOf: oneTargetJson }),
             objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'wait' }, selector: selectorJson, condition: { enum: ['exists', 'not_exists', 'visible', 'clickable'] }, ...intervalJson }, ['id', 'type', 'selector']),

package/dist/server/readiness-schema.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+const timeout = z.number().int().min(100).max(60000);
+export const readinessSchema = z.object({
+    platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(),
+    timeoutMs: timeout.optional(), stabilityMs: z.number().int().min(100).max(10000).optional()
+}).strict();
+export const readinessWaitSchema = readinessSchema.extend({ pollIntervalMs: z.number().int().min(100).max(1000).optional() }).strict();
+export const readinessPropertiesJson = {
+    platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 },
+    timeoutMs: { type: 'integer', minimum: 100, maximum: 60000 },
+    stabilityMs: { type: 'integer', minimum: 100, maximum: 10000, default: 500 }
+};

package/dist/server/tool-definitions.js

@@ -1,5 +1,16 @@
 import { journeyStepsJson } from './journey-schema.js';
+import { conditionalTools, expectedStateJson } from './condition-schema.js';
+import { readinessPropertiesJson } from './readiness-schema.js';
 export const toolDefinitions = [
+    ...['get_app_readiness', 'wait_for_app_ready'].map(name => ({
+        name,
+        description: `${name === 'get_app_readiness' ? 'Observe readiness with at most two fresh UI-tree samples.' : 'Wait within a single bounded budget for settled UI evidence.'} Reports loading, transitioning, settled or unknown with evidence and limitations. Unresponsive/debugger-paused detection is unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
+        inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties: {
+                ...readinessPropertiesJson,
+                timeoutMs: { ...readinessPropertiesJson.timeoutMs, default: name === 'get_app_readiness' ? 15000 : 30000 },
+                ...(name === 'wait_for_app_ready' ? { pollIntervalMs: { type: 'integer', minimum: 100, maximum: 1000, default: 500 } } : {})
+            } }
+    })),
     {
         name: 'start_app',
         description: `Purpose:
@@ -1128,6 +1139,29 @@ Returns { requests: [], count: 0 } when no credible network signals are found.`,
 ];
 // Keep the additive execution controls consistent across all action tools.
 for (const tool of toolDefinitions) {
+    if (['wait_for_ui', 'wait_for_ui_change'].includes(tool.name)) {
+        tool.inputSchema.properties.requireReady = { type: 'boolean', default: false };
+        tool.description += '\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.';
+    }
+    if (tool.name === 'get_ui_tree')
+        tool.description += '\nSuccessful observations include snapshot_session_id and snapshot_revision for same-device conditional input. Compact errors preserve the error and cannot authorize an expectation.';
+    if (tool.name === 'run_journey')
+        tool.description += '\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence even in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.';
+    if (conditionalTools.has(tool.name)) {
+        tool.inputSchema.properties.expectedState = expectedStateJson;
+        tool.inputSchema.properties.platform ??= { type: 'string', enum: ['android'] };
+        tool.inputSchema.allOf = [...(tool.inputSchema.allOf ?? []), {
+                if: { required: ['expectedState'] },
+                then: { required: ['platform', 'deviceId'], properties: {
+                        platform: { enum: ['type_text', 'press_back'].includes(tool.name) ? ['android'] : ['android', 'ios'] },
+                        deviceId: { type: 'string', minLength: 1, pattern: '\\S', not: { enum: ['booted', 'default'] } }
+                    } }
+            }];
+        tool.description += '\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.';
+    }
+    else {
+        tool.inputSchema.allOf = [...(tool.inputSchema.allOf ?? []), { not: { required: ['expectedState'] } }];
+    }
     if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back'].includes(tool.name)) {
         Object.assign(tool.inputSchema.properties, {
             verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
@@ -1148,3 +1182,15 @@ for (const tool of toolDefinitions) {
                 } }
         });
 }
+// Correlation is explicit; an omitted reference creates an independent observation.
+for (const tool of toolDefinitions) {
+    if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream'].includes(tool.name)) {
+        Object.assign(tool.inputSchema.properties, { actionRef: {
+                type: 'object', additionalProperties: false, required: ['sessionId', 'actionId'], properties: {
+                    sessionId: { type: 'string', minLength: 1, maxLength: 128 },
+                    actionId: { type: 'string', minLength: 1, maxLength: 128 }
+                }
+            } });
+        tool.description += '\nReturns evidence metadata with acquisition intervals and conservative freshness. Optional actionRef links a known same-session/device action; unavailable references collect independently. Device log times are not comparable with host dispatch times.';
+    }
+}