mobile-debug-mcp 0.35.0 → 0.37.0

package/dist/observe/snapshot-collection.js

@@ -3,6 +3,7 @@ import { measure } from '../utils/timing.js';
 import { deriveSnapshotMetadata } from './snapshot-metadata.js';
 import { deriveSnapshotSemantic } from './snapshot-semantic.js';
 import { snapshotLog, streamLog } from './snapshot-logs.js';
+import { collectGetScreenFingerprint } from './android/fingerprint.js';
 async function settle(tasks) {
     const results = await Promise.allSettled(Object.values(tasks));
     return Object.fromEntries(Object.keys(tasks).map((key, index) => [key, results[index]]));
@@ -15,11 +16,15 @@ function apply(result, success, failure) {
 }
 async function collect(raw, input, deps) {
     const { platform, deviceId, includeScreenshot = true, includeLogs = true, sessionId, logLines = 200 } = input;
+    const androidTree = platform === 'android' ? deps.getUITreeHandler({ platform, deviceId }) : undefined;
     const results = await settle({
         screenshot: includeScreenshot ? measure('screenshot_ms', () => deps.captureScreenshotHandler({ platform, deviceId })) : Promise.resolve(null),
         currentScreen: !platform || platform === 'android' ? deps.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
-        fingerprint: deps.getScreenFingerprintHandler({ platform, deviceId }),
-        uiTree: deps.getUITreeHandler({ platform, deviceId }),
+        fingerprint: androidTree ? collectGetScreenFingerprint({
+            getUITree: () => androidTree,
+            getCurrentScreen: id => deps.getCurrentScreenHandler({ deviceId: id })
+        }, deviceId) : deps.getScreenFingerprintHandler({ platform, deviceId }),
+        uiTree: androidTree ?? deps.getUITreeHandler({ platform, deviceId }),
         readLogStream: includeLogs ? deps.readLogStreamHandler({ platform, deviceId, sessionId: sessionId || 'default', limit: logLines }) : Promise.resolve({ entries: [] })
     });
     let entries = [];

package/dist/observe/system-trace-error.js

@@ -0,0 +1,7 @@
+export class TraceError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}

package/dist/observe/system-trace-router.js

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

package/dist/observe/system-trace.js

@@ -1,3 +1,4 @@
+import { SystemTraceRouter } from './system-trace-router.js';
 import { randomUUID } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
@@ -5,13 +6,8 @@ import path from 'node:path';
 import { AndroidTraceNative, TRACE_MAX_BYTES } from './system-trace-android.js';
 import { evidenceSessionId } from './evidence.js';
 import { runWithBudget, remainingBudget } from '../utils/operation-budget.js';
-export class TraceError extends Error {
-    code;
-    constructor(code) {
-        super(code);
-        this.code = code;
-    }
-}
+export { TraceError } from './system-trace-error.js';
+import { TraceError } from './system-trace-error.js';
 const clock = {
     wall: Date.now, mono: () => performance.now(), sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
     schedule: (fn, ms) => { const t = setTimeout(fn, ms); t.unref(); return t; }, clear: clearTimeout
@@ -291,4 +287,4 @@ export class SystemTraceSessions {
         });
     }
 }
-export const systemTraces = new SystemTraceSessions();
+export const systemTraces = new SystemTraceRouter(new SystemTraceSessions());

package/dist/server/definitions/manage.js

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

package/dist/server/handlers/action-execution.js

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

package/dist/server/handlers/compact-interaction.js

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

package/dist/server/handlers/compact-state.js

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

package/dist/server/handlers/debugger-handlers.js

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

package/dist/server/handlers/diagnostic.js

@@ -44,10 +44,10 @@ export async function handleSystemTrace(name, args) {
         throw new TraceError('INVALID_ARGUMENT');
     if (name === 'get_system_trace_capabilities' || name === 'start_system_trace') {
         const target = parsed.data;
-        if (target.platform !== 'android') {
-            if (name === 'start_system_trace')
-                throw new TraceError('UNSUPPORTED_PLATFORM');
-            return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: {}, reasons: ['UNSUPPORTED_PLATFORM'], enabled_sources: [], unavailable_categories: [], limitations: ['Android only'] });
+        if (target.platform === 'android' && (target.appId !== undefined || target.template !== undefined))
+            throw new TraceError('INVALID_ARGUMENT');
+        if (target.platform === 'ios') {
+            return handleIosTrace(name, target);
         }
         let device;
         try {
@@ -67,3 +67,11 @@ export async function handleSystemTrace(name, args) {
     const result = await systemTraces.control(parsed.data.traceId, operation);
     return { ...wrapResponse(result), ...(['failed', 'cancelled'].includes(result.state) ? { isError: true } : {}) };
 }
+async function handleIosTrace(name, target) {
+    if (!target.deviceId || (name === 'start_system_trace' && !target.appId))
+        throw new TraceError('INVALID_ARGUMENT');
+    if (name === 'get_system_trace_capabilities')
+        return wrapResponse(await systemTraces.iosCapabilities(target.deviceId, target.appId, target.template));
+    const result = await systemTraces.start(target.deviceId, target.durationMs, { appId: target.appId, template: target.template });
+    return { ...wrapResponse(result), ...(result.state === 'failed' ? { isError: true } : {}) };
+}

package/dist/server/handlers/input.js

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

package/dist/server/handlers/interact.js

@@ -1,3 +1,4 @@
+import { observeDeviceReadiness } from '../../observe/device-readiness.js';
 import { markEvidenceVerification } from '../../observe/evidence.js';
 import { withReadyWait } from '../../observe/readiness-service.js';
 import { ToolsInteract } from '../../interact/index.js';
@@ -68,6 +69,7 @@ export async function handleAdjustControl(args) {
         platform,
         deviceId
     });
+    res.device_readiness = await observeDeviceReadiness(res.device);
     markEvidenceVerification();
     return wrapResponse(res);
 }

package/dist/server/handlers/interaction-diagnostics.js

@@ -0,0 +1,62 @@
+import { randomUUID } from 'node:crypto';
+import { evidenceSessionId } from '../../observe/evidence.js';
+import { diagnosticsSchema } from '../schemas/interaction-diagnostics.js';
+import { wrapResponse } from '../common.js';
+const scheduleExpiry = expire => {
+    const timer = setTimeout(expire, 600000);
+    timer.unref();
+    return () => clearTimeout(timer);
+};
+export class InteractionDiagnostics {
+    now;
+    sessionId;
+    schedule;
+    entries = new Map();
+    bytes = 0;
+    constructor(now = () => performance.now(), sessionId = evidenceSessionId(), schedule = scheduleExpiry) {
+        this.now = now;
+        this.sessionId = sessionId;
+        this.schedule = schedule;
+    }
+    remove(id) {
+        const entry = this.entries.get(id);
+        if (entry) {
+            this.bytes -= entry.bytes;
+            entry.cancel();
+        }
+        this.entries.delete(id);
+    }
+    prune() {
+        for (const [id, entry] of this.entries)
+            if (this.now() - entry.completed >= 600000)
+                this.remove(id);
+    }
+    retain(result) {
+        this.prune();
+        const resultId = randomUUID(), text = JSON.stringify(result), bytes = Buffer.byteLength(text);
+        const ref = { session_id: this.sessionId, result_id: resultId };
+        if (bytes > 1024 * 1024)
+            return { ...ref, available: false, reason: 'RESULT_TOO_LARGE' };
+        while (this.entries.size >= 100 || this.bytes + bytes > 16 * 1024 * 1024)
+            this.remove(this.entries.keys().next().value);
+        this.entries.set(resultId, { text, completed: this.now(), bytes, cancel: this.schedule(() => this.remove(resultId)) });
+        this.bytes += bytes;
+        return { ...ref, available: true };
+    }
+    lookup(sessionId, resultId) {
+        this.prune();
+        if (sessionId !== this.sessionId)
+            return { success: false, error: { code: 'SESSION_MISMATCH', message: 'Use the session_id returned with this result.' } };
+        const entry = this.entries.get(resultId);
+        if (!entry)
+            return { success: false, error: { code: 'RESULT_UNAVAILABLE', message: 'Result expired, was evicted, is unknown, or belongs to a previous server process. Do not replay input automatically.' } };
+        return { success: true, result: JSON.parse(entry.text) };
+    }
+}
+export const interactionDiagnostics = new InteractionDiagnostics();
+export async function handleInteractionDiagnostics(args) {
+    const parsed = diagnosticsSchema.safeParse(args);
+    return wrapResponse(parsed.success ? interactionDiagnostics.lookup(parsed.data.sessionId, parsed.data.resultId) : {
+        success: false, error: { code: 'INVALID_ARGUMENT', message: 'Expected only sessionId and resultId UUID strings.' }
+    }, false);
+}