mobile-debug-mcp 0.32.4 → 0.33.0

package/dist/observe/index.js

@@ -1,4 +1,7 @@
+import { omitEvidence } from './evidence.js';
+import { withResolvedDevice } from '../utils/resolve-device.js';
 import { measure } from '../utils/timing.js';
+import { ReadinessTracker } from './readiness.js';
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidObserve } from './android.js';
 import { iOSObserve } from './ios.js';
@@ -136,16 +139,22 @@ export class ToolsObserve {
     }
     static async getUITreeHandler({ platform, deviceId, responseMode = 'debug', sinceSnapshotRevision }) {
         const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId);
+        const acquisitionStarted = Date.now();
         const tree = await observe.getUITree(resolved.id);
+        tree.readiness = new ReadinessTracker(resolved.platform, resolved.id).observe(tree, acquisitionStarted);
         if (responseMode !== 'compact')
             return tree;
         const revision = tree?.snapshot_revision ?? null;
+        const session = { snapshot_session_id: tree?.snapshot_session_id, readiness: tree.readiness };
+        if (tree?.error)
+            return { ...session, delta_available: false, snapshot_revision: revision, error: tree.error };
         const baseRevision = sinceSnapshotRevision;
         if (!Number.isInteger(baseRevision) || revision === null) {
-            return { delta_available: false, snapshot_revision: revision };
+            return { ...session, delta_available: false, snapshot_revision: revision };
         }
         const delta = getStateDelta(`${resolved.platform}:${resolved.id}`, baseRevision, revision);
-        return delta ? { delta_available: true, state_delta: delta, snapshot_revision: revision } : {
+        return delta ? { ...session, delta_available: true, state_delta: delta, snapshot_revision: revision } : {
+            ...session,
             delta_available: false,
             snapshot_revision: revision,
             reason: 'BASE_REVISION_UNAVAILABLE'
@@ -192,14 +201,23 @@ export class ToolsObserve {
             return await observe.startLogStream(packageName, resolved.id, sid);
         }
     }
-    static async readLogStreamHandler({ platform, sessionId, limit, since }) {
+    static async readLogStreamHandler({ platform, sessionId, limit, since, deviceId }) {
         const sid = sessionId || 'default';
-        const { observe } = await ToolsObserve.resolveObserve(platform);
+        const android = new AndroidObserve();
+        const ios = new iOSObserve();
+        const observe = platform === 'android' ? android : platform === 'ios' ? ios :
+            ios.getLogStreamDevice(sid) && !android.getLogStreamDevice(sid) ? ios : android;
+        const streamDevice = observe.getLogStreamDevice(sid);
+        if (deviceId && streamDevice && streamDevice.id !== deviceId)
+            throw new Error('LOG_STREAM_DEVICE_MISMATCH');
         return await observe.readLogStream(sid, limit ?? 100, since);
     }
     static async stopLogStreamHandler({ platform, sessionId }) {
         const sid = sessionId || 'default';
-        const { observe } = await ToolsObserve.resolveObserve(platform);
+        const android = new AndroidObserve();
+        const ios = new iOSObserve();
+        const observe = platform === 'android' ? android : platform === 'ios' ? ios :
+            ios.getLogStreamDevice(sid) && !android.getLogStreamDevice(sid) ? ios : android;
         return await observe.stopLogStream(sid);
     }
     static async captureScreenshotHandler({ platform, deviceId }) {
@@ -217,6 +235,15 @@ export class ToolsObserve {
         return await observe.getScreenFingerprint(resolved.id);
     }
     static async captureDebugSnapshotHandler({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId } = {}) {
+        const { resolved } = await ToolsObserve.resolveObserve(platform, deviceId, appId);
+        return withResolvedDevice(resolved, () => ToolsObserve.collectDebugSnapshot({ reason, includeLogs, includeScreenshot, logLines,
+            platform: resolved.platform, appId, deviceId: resolved.id, sessionId }));
+    }
+    static async collectDebugSnapshot({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId } = {}) {
+        if (!includeScreenshot)
+            omitEvidence('screenshot');
+        if (!includeLogs)
+            omitEvidence('logs');
         const timestamp = Date.now();
         const raw = {
             timestamp,
@@ -236,7 +263,7 @@ export class ToolsObserve {
             currentScreen: (!platform || platform === 'android') ? ToolsObserve.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
             fingerprint: ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }),
             uiTree: ToolsObserve.getUITreeHandler({ platform, deviceId }),
-            readLogStream: includeLogs ? ToolsObserve.readLogStreamHandler({ platform, sessionId: sid, limit: logLines }) : Promise.resolve({ entries: [] }),
+            readLogStream: includeLogs ? ToolsObserve.readLogStreamHandler({ platform, deviceId, sessionId: sid, limit: logLines }) : Promise.resolve({ entries: [] }),
         };
         const results = await Promise.allSettled(Object.values(tasks));
         const keys = Object.keys(tasks);

package/dist/observe/ios.js

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+import { captureEvidence } from './evidence.js';
 import { spawn } from "child_process";
 import { remainingBudget } from '../utils/operation-budget.js';
 import { execCmd } from '../utils/exec.js';
@@ -256,17 +258,21 @@ export function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
     return currentIndex;
 }
 const iosActiveLogStreams = new Map();
-export function _setIOSActiveLogStream(sessionId, file) {
-    iosActiveLogStreams.set(sessionId, { proc: {}, file });
+export function _setIOSActiveLogStream(sessionId, file, device) {
+    iosActiveLogStreams.set(sessionId, { proc: {}, file, device });
 }
 export function _clearIOSActiveLogStream(sessionId) {
     iosActiveLogStreams.delete(sessionId);
 }
 export class iOSObserve {
+    getLogStreamDevice(sessionId = 'default') { return iosActiveLogStreams.get(sessionId)?.device ?? null; }
     async getDeviceMetadata(deviceId = "booted") {
         return getIOSDeviceMetadata(deviceId);
     }
     async getLogs(filters = {}) {
+        return captureEvidence('logs', { platform: 'ios', id: filters.deviceId ?? '' }, () => this.collectGetLogs(filters));
+    }
+    async collectGetLogs(filters = {}) {
         const { appId, deviceId = 'booted', pid, tag, level, contains, since_seconds, limit } = filters;
         const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog'];
         // Default to last N seconds if no since_seconds provided; limit lines handled after parsing
@@ -418,8 +424,11 @@ export class iOSObserve {
         }
     }
     async captureScreenshot(deviceId = "booted") {
+        return captureEvidence('screenshot', { platform: 'ios', id: deviceId ?? '' }, () => this.collectCaptureScreenshot(deviceId));
+    }
+    async collectCaptureScreenshot(deviceId = "booted") {
         const device = await getIOSDeviceMetadata(deviceId);
-        const tmpFile = `/tmp/mcp-ios-screenshot-${Date.now()}.png`;
+        const tmpFile = `/tmp/mcp-ios-screenshot-${randomUUID()}.png`;
         try {
             await iosExecCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId);
             const buffer = await fs.readFile(tmpFile);
@@ -485,6 +494,9 @@ export class iOSObserve {
         }
     }
     async getUITree(deviceId = "booted") {
+        return captureEvidence('ui_tree', { platform: 'ios', id: deviceId ?? '' }, () => this.collectGetUITree(deviceId));
+    }
+    async collectGetUITree(deviceId = "booted") {
         const measurement = createObservationMeasurement('ios');
         let device;
         try {
@@ -608,11 +620,14 @@ export class iOSObserve {
         }
     }
     async getScreenFingerprint(deviceId = 'booted') {
+        return captureEvidence('fingerprint', { platform: 'ios', id: deviceId ?? '' }, () => this.collectGetScreenFingerprint(deviceId));
+    }
+    async collectGetScreenFingerprint(deviceId = 'booted') {
         try {
             const tree = await this.getUITree(deviceId);
             if (!tree || tree.error)
                 return { fingerprint: null, error: tree && tree.error };
-            return computeScreenFingerprint(tree, null, 'ios', 50);
+            return { ...computeScreenFingerprint(tree, null, 'ios', 50), captured_at_ms: tree.captured_at_ms };
         }
         catch (e) {
             return { fingerprint: null, error: e instanceof Error ? e.message : String(e) };
@@ -652,9 +667,10 @@ export class iOSObserve {
             });
             proc.on('close', () => {
                 stream.end();
-                iosActiveLogStreams.delete(sessionId);
+                if (iosActiveLogStreams.get(sessionId)?.proc === proc)
+                    iosActiveLogStreams.delete(sessionId);
             });
-            iosActiveLogStreams.set(sessionId, { proc, file });
+            iosActiveLogStreams.set(sessionId, { proc, file, device: { platform: 'ios', id: deviceId ?? '' } });
             return { success: true, stream_started: true };
         }
         catch {
@@ -673,6 +689,9 @@ export class iOSObserve {
         return { success: true };
     }
     async readLogStream(sessionId = 'default', limit = 100, since) {
+        return captureEvidence('logs', this.getLogStreamDevice(sessionId), () => this.collectReadLogStream(sessionId, limit, since));
+    }
+    async collectReadLogStream(sessionId = 'default', limit = 100, since) {
         const entry = iosActiveLogStreams.get(sessionId);
         if (!entry)
             return { entries: [] };

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;
+}