mobile-debug-mcp 0.34.0 → 0.36.0

package/dist/observe/evidence.js

@@ -8,7 +8,8 @@ const orders = new Map();
 const stamp = () => ({ wall: Date.now(), mono: performance.now() });
 const deviceKey = (d) => `${d.platform}:${d.id}`;
 const sameDevice = (a, b) => !!a && !!b && deviceKey(a) === deviceKey(b);
-function validDevice(d) {
+function validDevice(value) {
+    const d = value;
     return d && ['android', 'ios'].includes(d.platform) && typeof d.id === 'string' && d.id && !['default', 'booted'].includes(d.id)
         ? { platform: d.platform, id: d.id } : null;
 }
@@ -106,11 +107,13 @@ export function omitEvidence(kind) {
     if (!current)
         return;
     const start = stamp();
-    current.observations.push({ value: {
+    current.observations.push({
+        value: {
             evidence_id: randomUUID(), kind, status: 'omitted', capture_started_at_ms: null,
             capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
             freshness: kind === 'logs' ? 'not_applicable' : 'unknown', freshness_reasons: [], device: current.device
-        }, start, end: null, order: null, startSequence: 0, endSequence: 0, overlapping: false, reused: false });
+        }, start, end: null, order: null, startSequence: 0, endSequence: 0, overlapping: false, reused: false
+    });
 }
 export async function captureEvidence(kind, device, operation) {
     const current = context.getStore();
@@ -121,45 +124,19 @@ export async function captureEvidence(kind, device, operation) {
         bindEvidenceDevice(target);
     const order = orderFor(target);
     const start = stamp();
-    const acquisition = { value: {
+    const acquisition = {
+        value: {
             evidence_id: randomUUID(), kind, status: 'failed', capture_started_at_ms: start.wall,
             capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
             freshness: 'unknown', freshness_reasons: [], device: target
         }, start, end: null, order, startSequence: order?.sequence ?? 0,
-        endSequence: 0, overlapping: !!order?.active, reused: false };
+        endSequence: 0, overlapping: !!order?.active, reused: false
+    };
     current.observations.push(acquisition);
     try {
-        const result = await operation();
-        const value = acquisition.value;
-        const resolved = validDevice(result?.device) ?? target;
-        value.device = resolved;
-        if (resolved)
-            bindEvidenceDevice(resolved);
-        const failure = result?.error ?? result?.meta?.error;
-        value.status = failure || result?.success === false || (kind === 'fingerprint' && !result?.fingerprint) ? 'failed' : 'captured';
-        if (failure)
-            value.error = failure;
-        const source = result?.captured_at_ms;
-        if (Number.isFinite(source) && source > 0) {
-            value.source_captured_at_ms = source;
-            acquisition.reused = source < start.wall;
-        }
-        if (kind === 'ui_tree') {
-            value.snapshot_session_id = result?.snapshot_session_id;
-            value.snapshot_revision = result?.snapshot_revision;
-        }
-        if (kind === 'logs') {
-            const entries = result?.logs ?? result?.entries ?? [];
-            const times = entries.map((e) => {
-                const t = e?.timestamp ?? e?._iso;
-                return typeof t === 'number' ? t : typeof t === 'string' ? Date.parse(t) : NaN;
-            }).filter((t) => Number.isFinite(t));
-            value.clock = 'device_or_unknown';
-            value.event_time_comparable = false;
-            value.earliest_entry_at_ms = times.length ? times.reduce((a, b) => Math.min(a, b)) : null;
-            value.latest_entry_at_ms = times.length ? times.reduce((a, b) => Math.max(a, b)) : null;
-        }
-        return result;
+        const original = await operation();
+        recordObservationResult(acquisition, original, kind, target, start);
+        return original;
     }
     catch (error) {
         acquisition.value.error = error instanceof Error ? error.message : String(error);
@@ -189,46 +166,13 @@ function assemble(current) {
     const link = association(current);
     const action = link.association === 'unavailable' ? null : current.action;
     const clockChanged = end.wall < current.start.wall;
-    const observations = current.observations.map(a => {
-        const v = { ...a.value, freshness_reasons: [] };
-        if (v.status === 'omitted')
-            return v;
-        const componentAction = sameDevice(v.device, action?.device ?? null) ? action : null;
-        const sourceMono = a.end && v.source_captured_at_ms !== null ? a.end.mono + v.source_captured_at_ms - a.end.wall : a.end?.mono;
-        const reason = (freshness, code) => { v.freshness = freshness; v.freshness_reasons.push(code); };
-        if (v.kind === 'logs')
-            reason('unknown', 'DEVICE_CLOCK_UNVERIFIED');
-        else if (clockChanged || (a.end && a.end.wall < a.start.wall))
-            reason('unknown', 'CLOCK_DISCONTINUITY');
-        else if (v.source_captured_at_ms !== null && a.end && v.source_captured_at_ms > a.end.wall)
-            reason('unknown', 'CLOCK_DISCONTINUITY');
-        else if (!v.device || !a.order || orders.get(deviceKey(v.device)) !== a.order || v.status !== 'captured' || !a.end)
-            reason('unknown', 'CAPTURE_TIME_UNKNOWN');
-        else if (componentAction?.dispatchStart && sourceMono !== undefined && sourceMono < componentAction.dispatchStart.mono)
-            reason('stale', 'BEFORE_ACTION');
-        else if (a.order && (a.order.sequence > a.endSequence || (a.reused && sourceMono !== undefined && sourceMono < a.order.lastStarted)))
-            reason('stale', 'SUPERSEDED_BY_ACTION');
-        else if (a.overlapping)
-            reason('unknown', 'OVERLAPPING_ACTION');
-        else if (a.reused)
-            reason('unknown', 'REUSED_OBSERVATION');
-        else {
-            v.freshness = 'fresh';
-        }
-        if (!clockChanged && a.end && a.end.wall >= a.start.wall && v.source_captured_at_ms !== null && v.source_captured_at_ms <= end.wall) {
-            v.age_ms = Math.max(0, end.mono - a.end.mono + a.end.wall - v.source_captured_at_ms);
-        }
-        return { ...v, session_id: sessionId, correlation_id: componentAction?.correlationId ?? current.correlationId,
-            action_id: componentAction?.id ?? null, association: componentAction ? 'internal' : link.association };
-    });
+    const observations = current.observations.map(a => assembleObservation(a, action, current, link, end, clockChanged));
     return {
         session_id: sessionId, correlation_id: action?.correlationId ?? current.correlationId,
         action_id: action?.id ?? null, device: current.device, ...link,
         ...(current.ref ? { requested_action_ref: current.ref } : {}),
         operation_started_at_ms: current.start.wall, operation_completed_at_ms: current.end?.wall ?? end.wall,
-        dispatch_started_at_ms: action?.dispatchStart?.wall ?? null,
-        dispatch_completed_at_ms: action?.dispatchEnd?.wall ?? null,
-        verification_completed_at_ms: current.verification?.wall ?? action?.verification?.wall ?? null,
+        ...actionTimes(action, current),
         observations, trace_context: { supported: !!current.systemTraceId, trace_id: current.systemTraceId ?? null, markers: [] }
     };
 }
@@ -236,10 +180,14 @@ export async function withEvidence(options, operation) {
     prune();
     const parent = context.getStore();
     const id = randomUUID();
-    const record = options.action ? { id, correlationId: parent?.correlationId ?? id, device: null,
-        dispatchStart: null, dispatchEnd: null, verification: null, completed: null } : options.ref?.sessionId === sessionId ? active.get(options.ref.actionId) ?? history.get(options.ref.actionId) ?? null : null;
-    const current = { systemTraceId: parent?.systemTraceId, correlationId: options.action ? record.correlationId : options.journey ? id : randomUUID(),
-        action: record, ref: options.ref, device: null, start: stamp(), end: null, verification: null, observations: [], children: [], isAction: !!options.action };
+    const record = options.action ? {
+        id, correlationId: parent?.correlationId ?? id, device: null,
+        dispatchStart: null, dispatchEnd: null, verification: null, completed: null
+    } : options.ref?.sessionId === sessionId ? active.get(options.ref.actionId) ?? history.get(options.ref.actionId) ?? null : null;
+    const current = {
+        systemTraceId: parent?.systemTraceId, correlationId: options.action ? record.correlationId : options.journey ? id : randomUUID(),
+        action: record, ref: options.ref, device: null, start: stamp(), end: null, verification: null, observations: [], children: [], isAction: !!options.action
+    };
     if (options.action && record)
         active.set(id, record);
     if (parent && options.action)
@@ -278,3 +226,94 @@ export function completeJourneyVerification(actionId) {
         child.action.verification = child.verification;
     }
 }
+function recordObservationResult(acquisition, result, kind, target, start) {
+    const value = acquisition.value;
+    const resolved = validDevice(result?.device) ?? target;
+    value.device = resolved;
+    if (resolved)
+        bindEvidenceDevice(resolved);
+    const failure = result?.error ?? result?.meta?.error;
+    value.status = failure || result?.success === false || (kind === 'fingerprint' && !result?.fingerprint) ? 'failed' : 'captured';
+    if (failure)
+        value.error = failure;
+    recordCaptureTime(acquisition, result, start);
+    if (kind === 'ui_tree') {
+        value.snapshot_session_id = result?.snapshot_session_id;
+        value.snapshot_revision = result?.snapshot_revision;
+    }
+    if (kind === 'logs')
+        recordLogWindow(value, result);
+}
+function recordLogWindow(value, result) {
+    const entries = result?.logs ?? result?.entries ?? [];
+    const times = entries.map((e) => {
+        const t = e?.timestamp ?? e?._iso;
+        return typeof t === 'number' ? t : typeof t === 'string' ? Date.parse(t) : NaN;
+    }).filter((t) => Number.isFinite(t));
+    value.clock = 'device_or_unknown';
+    value.event_time_comparable = false;
+    value.earliest_entry_at_ms = times.length ? times.reduce((a, b) => Math.min(a, b)) : null;
+    value.latest_entry_at_ms = times.length ? times.reduce((a, b) => Math.max(a, b)) : null;
+}
+function assembleObservation(a, action, current, link, end, clockChanged) {
+    const v = { ...a.value, freshness_reasons: [] };
+    if (v.status === 'omitted')
+        return v;
+    const componentAction = sameDevice(v.device, action?.device ?? null) ? action : null;
+    const sourceMono = a.end && v.source_captured_at_ms !== null ? a.end.mono + v.source_captured_at_ms - a.end.wall : a.end?.mono;
+    const freshness = observationFreshness(a, componentAction, sourceMono, clockChanged);
+    if (freshness) {
+        v.freshness = freshness[0];
+        v.freshness_reasons.push(freshness[1]);
+    }
+    else
+        v.freshness = 'fresh';
+    if (!clockChanged && a.end && a.end.wall >= a.start.wall && v.source_captured_at_ms !== null && v.source_captured_at_ms <= end.wall) {
+        v.age_ms = Math.max(0, end.mono - a.end.mono + a.end.wall - v.source_captured_at_ms);
+    }
+    return {
+        ...v, session_id: sessionId, correlation_id: componentAction?.correlationId ?? current.correlationId,
+        action_id: componentAction?.id ?? null, association: componentAction ? 'internal' : link.association
+    };
+}
+function observationFreshness(a, action, sourceMono, clockChanged) {
+    const v = a.value;
+    if (v.kind === 'logs')
+        return ['unknown', 'DEVICE_CLOCK_UNVERIFIED'];
+    if (clockDiscontinuity(a, clockChanged))
+        return ['unknown', 'CLOCK_DISCONTINUITY'];
+    if (!knownCapture(a))
+        return ['unknown', 'CAPTURE_TIME_UNKNOWN'];
+    if (action?.dispatchStart && sourceMono !== undefined && sourceMono < action.dispatchStart.mono)
+        return ['stale', 'BEFORE_ACTION'];
+    if (superseded(a, sourceMono))
+        return ['stale', 'SUPERSEDED_BY_ACTION'];
+    if (a.overlapping)
+        return ['unknown', 'OVERLAPPING_ACTION'];
+    if (a.reused)
+        return ['unknown', 'REUSED_OBSERVATION'];
+    return null;
+}
+function clockDiscontinuity(a, changed) {
+    return changed || !!(a.end && a.end.wall < a.start.wall) || !!(a.value.source_captured_at_ms !== null && a.end && a.value.source_captured_at_ms > a.end.wall);
+}
+function knownCapture(a) {
+    return !!a.value.device && !!a.order && orders.get(deviceKey(a.value.device)) === a.order && a.value.status === 'captured' && !!a.end;
+}
+function superseded(a, sourceMono) {
+    return !!a.order && (a.order.sequence > a.endSequence || (a.reused && sourceMono !== undefined && sourceMono < a.order.lastStarted));
+}
+function actionTimes(action, current) {
+    return {
+        dispatch_started_at_ms: action?.dispatchStart?.wall ?? null,
+        dispatch_completed_at_ms: action?.dispatchEnd?.wall ?? null,
+        verification_completed_at_ms: current.verification?.wall ?? action?.verification?.wall ?? null,
+    };
+}
+function recordCaptureTime(acquisition, result, start) {
+    const source = result?.captured_at_ms;
+    if (typeof source === 'number' && Number.isFinite(source) && source > 0) {
+        acquisition.value.source_captured_at_ms = source;
+        acquisition.reused = source < start.wall;
+    }
+}

package/dist/observe/index.js

@@ -1,118 +1,12 @@
-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';
-import { deriveSnapshotMetadata, getLatestStateDelta, getStateDelta } from './snapshot-metadata.js';
+import { getLatestStateDelta, getStateDelta } from './snapshot-metadata.js';
 export { AndroidObserve } from './android.js';
 export { iOSObserve } from './ios.js';
-function normalizeHint(value) {
-    if (value === null || value === undefined)
-        return '';
-    return String(value).trim().replace(/\s+/g, ' ').toLowerCase();
-}
-function titleCase(value) {
-    return value
-        .replace(/[_-]+/g, ' ')
-        .replace(/\s+/g, ' ')
-        .trim()
-        .replace(/\b\w/g, (match) => match.toUpperCase());
-}
-function shortActivityName(activity) {
-    if (!activity)
-        return null;
-    const trimmed = String(activity).trim();
-    if (!trimmed)
-        return null;
-    const lastSegment = trimmed.split('.').pop() || trimmed;
-    const withoutSuffix = lastSegment.replace(/Activity$/, '');
-    return withoutSuffix ? titleCase(withoutSuffix) : titleCase(lastSegment);
-}
-function collectSnapshotTexts(tree) {
-    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
-    const texts = [];
-    const actionables = [];
-    for (const element of elements) {
-        const rawText = element?.text ?? element?.contentDescription ?? element?.contentDesc ?? element?.accessibilityLabel ?? element?.resourceId ?? element?.id ?? '';
-        const text = normalizeHint(rawText);
-        if (text)
-            texts.push(text);
-        if (element?.clickable && element?.enabled !== false && text) {
-            actionables.push(text);
-        }
-    }
-    return {
-        texts: Array.from(new Set(texts)),
-        actionables: Array.from(new Set(actionables))
-    };
-}
-function inferSnapshotScreen(raw) {
-    const tree = raw.ui_tree;
-    const treeScreen = normalizeHint(tree?.screen);
-    if (treeScreen)
-        return titleCase(treeScreen);
-    const activity = shortActivityName(raw.activity);
-    if (activity)
-        return activity;
-    const { texts } = collectSnapshotTexts(tree);
-    if (texts.length > 0)
-        return titleCase(texts[0]);
-    return null;
-}
-function deriveSnapshotSemantic(raw) {
-    const tree = raw.ui_tree;
-    const { texts, actionables } = collectSnapshotTexts(tree);
-    const screenFromTree = normalizeHint(tree?.screen);
-    const activityHint = normalizeHint(raw.activity);
-    const screen = inferSnapshotScreen(raw);
-    if (!screen && !activityHint && texts.length === 0 && !raw.logs.length)
-        return null;
-    const hasErrorLogs = raw.logs.some((entry) => /error|fatal exception|exception|failed/i.test(entry.message));
-    const hasLoadingSignals = texts.some((text) => /loading|please wait|spinner|progress/i.test(text));
-    const hasPrimaryText = texts.some((text) => /sign in|log in|login|home|checkout|settings|menu|profile|search/i.test(text));
-    const hasScreenshot = typeof raw.screenshot === 'string' && raw.screenshot.length > 0;
-    const hasUiTree = !!tree && Array.isArray(tree.elements);
-    const signals = {
-        has_activity: !!activityHint,
-        has_ui_tree: hasUiTree,
-        has_screenshot: hasScreenshot,
-        has_visible_text: texts.length > 0,
-        has_clickable_elements: actionables.length > 0,
-        has_error_logs: hasErrorLogs,
-        has_loading_signals: hasLoadingSignals,
-        has_primary_text: hasPrimaryText
-    };
-    const warnings = [];
-    if (screenFromTree && activityHint && screenFromTree !== activityHint) {
-        warnings.push('ui_tree.screen and activity hints differ');
-    }
-    if (!hasUiTree)
-        warnings.push('ui tree unavailable');
-    if (!activityHint)
-        warnings.push('activity unavailable');
-    if (hasErrorLogs)
-        warnings.push('error signals present in logs');
-    const evidenceScore = (hasUiTree ? 0.35 : 0) +
-        (screen ? 0.2 : 0) +
-        (activityHint ? 0.15 : 0) +
-        (actionables.length > 0 ? 0.15 : 0) +
-        (texts.length > 0 ? 0.1 : 0) +
-        (hasScreenshot ? 0.05 : 0) +
-        (hasErrorLogs ? -0.15 : 0) +
-        (hasLoadingSignals ? -0.05 : 0);
-    const confidence = Math.max(0, Math.min(1, Number(evidenceScore.toFixed(2))));
-    if (!screen && confidence < 0.3)
-        return null;
-    return {
-        screen,
-        signals,
-        actions_available: actionables.length > 0 ? actionables.slice(0, 10) : null,
-        confidence,
-        warnings
-    };
-}
+import { collectDebugSnapshot } from './snapshot-collection.js';
 export class ToolsObserve {
     static getLatestStateDelta(platform, deviceId) {
         return getLatestStateDelta(`${platform}:${deviceId}`);
@@ -172,24 +66,13 @@ export class ToolsObserve {
         if (level && !['VERBOSE', 'DEBUG', 'INFO', 'WARN', 'ERROR'].includes(level.toString().toUpperCase())) {
             return { device: resolved, logs: [], crashLines: [], logCount: 0, error: { code: 'INVALID_FILTER', message: `Unsupported level filter: ${level}` } };
         }
-        if (observe instanceof AndroidObserve) {
-            const response = await observe.getLogs(filters);
-            const logs = Array.isArray(response.logs) ? response.logs : [];
-            const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message));
-            const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds);
-            if (anyFilterApplied && logs.length === 0)
-                return { device: response.device, logs: [], crashLines: [], logCount: 0, source: response.source, meta: response.meta, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } };
-            return { device: response.device, logs, crashLines, logCount: response.logCount, source: response.source, meta: response.meta };
-        }
-        else {
-            const resp = await observe.getLogs(filters);
-            const logs = Array.isArray(resp.logs) ? resp.logs : [];
-            const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message));
-            const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds);
-            if (anyFilterApplied && logs.length === 0)
-                return { device: resp.device, logs: [], crashLines: [], logCount: 0, source: resp.source, meta: resp.meta, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } };
-            return { device: resp.device, logs, crashLines, logCount: resp.logCount, source: resp.source, meta: resp.meta };
-        }
+        const response = await observe.getLogs(filters);
+        const logs = Array.isArray(response.logs) ? response.logs : [];
+        const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message));
+        const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds);
+        if (anyFilterApplied && logs.length === 0)
+            return { device: response.device, logs: [], crashLines: [], logCount: 0, source: response.source, meta: response.meta, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } };
+        return { device: response.device, logs, crashLines, logCount: response.logCount, source: response.source, meta: response.meta };
     }
     static async startLogStreamHandler({ platform, packageName, level, sessionId, deviceId }) {
         const sid = sessionId || 'default';
@@ -232,146 +115,16 @@ export class ToolsObserve {
     static async getScreenFingerprintHandler({ platform, deviceId } = {}) {
         const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId);
         // Both observes implement getScreenFingerprint
-        return await observe.getScreenFingerprint(resolved.id);
+        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 }));
+        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,
-            snapshot_revision: 0,
-            captured_at_ms: timestamp,
-            reason: reason || '',
-            activity: null,
-            fingerprint: null,
-            screenshot: null,
-            ui_tree: null,
-            logs: []
-        };
-        // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
-        const sid = sessionId || 'default';
-        const tasks = {
-            screenshot: includeScreenshot ? measure('screenshot_ms', () => ToolsObserve.captureScreenshotHandler({ platform, deviceId })) : Promise.resolve(null),
-            currentScreen: (!platform || platform === 'android') ? ToolsObserve.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
-            fingerprint: ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }),
-            uiTree: ToolsObserve.getUITreeHandler({ platform, deviceId }),
-            readLogStream: includeLogs ? ToolsObserve.readLogStreamHandler({ platform, deviceId, sessionId: sid, limit: logLines }) : Promise.resolve({ entries: [] }),
-        };
-        const results = await Promise.allSettled(Object.values(tasks));
-        const keys = Object.keys(tasks);
-        // Map results back to keys
-        for (let i = 0; i < results.length; i++) {
-            const key = keys[i];
-            const res = results[i];
-            if (res.status === 'fulfilled') {
-                const val = res.value;
-                if (key === 'screenshot') {
-                    raw.screenshot = val && val.screenshot ? val.screenshot : null;
-                }
-                else if (key === 'currentScreen') {
-                    raw.activity = val && ((val.activity || val.shortActivity)) ? (val.activity || val.shortActivity) : raw.activity || '';
-                }
-                else if (key === 'fingerprint') {
-                    if (val && val.fingerprint)
-                        raw.fingerprint = val.fingerprint;
-                    if (val && val.activity)
-                        raw.activity = raw.activity || val.activity;
-                    if (val && val.error)
-                        raw.fingerprint_error = val.error;
-                }
-                else if (key === 'uiTree') {
-                    raw.ui_tree = val;
-                    if (val && val.error)
-                        raw.ui_tree_error = val.error;
-                }
-                else if (key === 'readLogStream') {
-                    // handle below after evaluating fallback
-                    // temporarily attach to out._streamEntries
-                    raw.logs = Array.isArray(val?.entries) ? val.entries : [];
-                }
-            }
-            else {
-                const errMsg = res.reason instanceof Error ? res.reason.message : String(res.reason);
-                if (key === 'screenshot')
-                    raw.screenshot_error = errMsg;
-                if (key === 'currentScreen')
-                    raw.activity_error = errMsg;
-                if (key === 'fingerprint') {
-                    raw.fingerprint = null;
-                    raw.fingerprint_error = errMsg;
-                }
-                if (key === 'uiTree') {
-                    raw.ui_tree = null;
-                    raw.ui_tree_error = errMsg;
-                }
-                if (key === 'readLogStream') {
-                    raw.logs = [];
-                    raw.logs_error = errMsg;
-                }
-            }
-        }
-        // Logs: prefer stream entries, fallback to snapshot logs when empty
-        if (includeLogs) {
-            try {
-                let entries = Array.isArray(raw.logs) ? raw.logs : [];
-                if (!entries || entries.length === 0) {
-                    const gl = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines: logLines });
-                    const snapshotLogs = (gl && gl.logs) ? gl.logs : [];
-                    // raw may be structured entries or strings
-                    entries = snapshotLogs.slice(-Math.max(0, logLines)).map(item => {
-                        if (!item)
-                            return { timestamp: null, level: 'INFO', message: '' };
-                        if (typeof item === 'string') {
-                            const level = /\b(FATAL EXCEPTION|ERROR| E )\b/i.test(item) ? 'ERROR' : /\b(WARN| W )\b/i.test(item) ? 'WARN' : 'INFO';
-                            return { timestamp: null, level, message: item };
-                        }
-                        const msg = item.message || item.msg || JSON.stringify(item);
-                        const levelRaw = item.level || item.levelName || item._level || '';
-                        const level = (levelRaw && String(levelRaw)).toUpperCase() || (/\bERROR\b/i.test(msg) ? 'ERROR' : /\bWARN\b/i.test(msg) ? 'WARN' : 'INFO');
-                        const ts = item.timestamp || item._iso || null;
-                        const tsNum = (ts && typeof ts === 'string') ? (isNaN(new Date(ts).getTime()) ? null : new Date(ts).getTime()) : (typeof ts === 'number' ? ts : null);
-                        return { timestamp: tsNum, level, message: msg };
-                    });
-                }
-                else {
-                    entries = entries.map(ent => {
-                        const msg = (ent && (ent.message || ent.msg)) ? (ent.message || ent.msg) : (typeof ent === 'string' ? ent : JSON.stringify(ent));
-                        const levelRaw = (ent && (ent.level || ent.levelName || ent._level)) ? (ent.level || ent.levelName || ent._level) : '';
-                        const level = (levelRaw && String(levelRaw)).toString().toUpperCase() || (/\bERROR\b/i.test(msg) ? 'ERROR' : /\bWARN\b/i.test(msg) ? 'WARN' : 'INFO');
-                        let tsNum = null;
-                        const maybeIso = ent && (ent._iso || ent.timestamp);
-                        if (maybeIso && typeof maybeIso === 'string') {
-                            const d = new Date(maybeIso);
-                            if (!isNaN(d.getTime()))
-                                tsNum = d.getTime();
-                        }
-                        return { timestamp: tsNum, level, message: msg };
-                    });
-                }
-                raw.logs = entries;
-            }
-            catch (e) {
-                raw.logs = [];
-                raw.logs_error = e instanceof Error ? e.message : String(e);
-            }
-        }
-        const snapshotDeviceKey = raw.ui_tree?.device
-            ? `${raw.ui_tree.device.platform}:${raw.ui_tree.device.id}`
-            : `${platform || 'unknown'}:${deviceId || 'default'}`;
-        const snapshotMetadata = deriveSnapshotMetadata(snapshotDeviceKey, raw.ui_tree, 'snapshot', raw.ui_tree?.snapshot_revision ? null : (raw.fingerprint || raw.activity || null));
-        raw.snapshot_revision = raw.ui_tree?.snapshot_revision ?? snapshotMetadata.snapshot_revision;
-        raw.captured_at_ms = raw.ui_tree?.captured_at_ms ?? snapshotMetadata.captured_at_ms;
-        raw.snapshot_delta = raw.ui_tree?.snapshot_delta ?? snapshotMetadata.snapshot_delta ?? null;
-        raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state;
-        const semantic = deriveSnapshotSemantic(raw);
-        return semantic ? { raw, semantic } : { raw };
+    static collectDebugSnapshot(input = {}) {
+        return collectDebugSnapshot(input, ToolsObserve);
     }
 }

package/dist/observe/ios/context.js

@@ -0,0 +1,16 @@
+import { execCommand } from "../../utils/ios/utils.js";
+export const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+export let iosExecCommand = execCommand;
+export function _setIOSExecCommandForTests(fn) {
+    iosExecCommand = fn;
+}
+export function _resetIOSExecCommandForTests() {
+    iosExecCommand = execCommand;
+}
+export const iosActiveLogStreams = new Map();
+export function _setIOSActiveLogStream(sessionId, file, device) {
+    iosActiveLogStreams.set(sessionId, { proc: { kill: () => false }, file, device });
+}
+export function _clearIOSActiveLogStream(sessionId) {
+    iosActiveLogStreams.delete(sessionId);
+}

package/dist/observe/ios/fingerprint.js

@@ -0,0 +1,12 @@
+import { computeScreenFingerprint } from '../../utils/ui/index.js';
+export async function collectGetScreenFingerprint(source, deviceId = 'booted') {
+    try {
+        const tree = await source.getUITree(deviceId);
+        if (!tree || tree.error)
+            return { fingerprint: null, error: tree && tree.error };
+        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) };
+    }
+}