mobile-debug-mcp 0.31.0 → 0.32.0

package/dist/observe/snapshot-metadata.js

@@ -1,4 +1,5 @@
 import crypto from 'crypto';
+let nextRevision = 1;
 const snapshotStateByDevice = new Map();
 function normalize(value) {
     if (value === null || value === undefined)
@@ -43,17 +44,19 @@ function stableElementIdentity(element, index) {
         index
     })).digest('hex')}`;
 }
-function buildElementSignatures(tree) {
+function buildElementRecords(tree) {
     const signatures = new Map();
+    const elementsByIdentity = new Map();
     const elements = Array.isArray(tree?.elements) ? tree.elements : [];
-    for (let index = 0; index < elements.length; index++) {
+    for (let index = 0; index < Math.min(elements.length, 500); index++) {
         const element = elements[index];
         if (!element)
             continue;
         const identity = stableElementIdentity(element, index);
         signatures.set(identity, crypto.createHash('sha1').update(JSON.stringify(stableElementSignature(element))).digest('hex'));
+        elementsByIdentity.set(identity, structuredClone(element));
     }
-    return signatures;
+    return { signatures, elementsByIdentity };
 }
 function summarizeSnapshotDelta(previous, currentElements) {
     if (!previous)
@@ -118,24 +121,47 @@ export function detectLoadingState(tree, source) {
 }
 export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverride) {
     const signature = signatureOverride ?? computeSnapshotSignature(tree);
-    const previous = snapshotStateByDevice.get(deviceKey);
+    const existing = snapshotStateByDevice.get(deviceKey);
+    const previous = existing && Date.now() - existing.updatedAt <= 10 * 60 * 1000 ? existing : undefined;
+    if (!previous && existing)
+        snapshotStateByDevice.delete(deviceKey);
     const hasValidTree = !!tree && !tree.error;
-    const currentElementSignatures = hasValidTree
-        ? buildElementSignatures(tree)
-        : previous?.elementSignatures ?? new Map();
-    let revision = 1;
-    if (previous) {
-        if (signature === null) {
-            revision = previous.revision;
-        }
-        else {
-            revision = previous.signature === signature ? previous.revision : previous.revision + 1;
+    const records = hasValidTree ? buildElementRecords(tree) : null;
+    const currentElementSignatures = records?.signatures ?? previous?.elementSignatures ?? new Map();
+    const currentElements = records?.elementsByIdentity ?? previous?.elements ?? new Map();
+    const revision = previous && (signature === null || previous.signature === signature) ? previous.revision : nextRevision++;
+    const history = previous?.history ?? new Map();
+    const historyTimes = previous?.historyTimes ?? new Map();
+    const oversized = previous?.oversized ?? new Map();
+    if (hasValidTree) {
+        history.set(revision, currentElements);
+        if (!historyTimes.has(revision))
+            historyTimes.set(revision, Date.now());
+        if ((tree.elements?.length ?? 0) > 500)
+            oversized.set(revision, (tree.elements?.length ?? 0) - 500);
+    }
+    for (const [id, timestamp] of historyTimes) {
+        if (Date.now() - timestamp > 10 * 60 * 1000) {
+            history.delete(id);
+            historyTimes.delete(id);
+            oversized.delete(id);
         }
     }
+    while (history.size > 8) {
+        const oldest = history.keys().next().value;
+        if (oldest === undefined)
+            break;
+        history.delete(oldest);
+        historyTimes.delete(oldest);
+        oversized.delete(oldest);
+    }
     snapshotStateByDevice.set(deviceKey, {
         revision,
         signature,
-        elementSignatures: currentElementSignatures
+        elementSignatures: currentElementSignatures,
+        elements: currentElements,
+        history, historyTimes, oversized, previousRevision: previous?.revision ?? null,
+        updatedAt: Date.now()
     });
     return {
         snapshot_revision: revision,
@@ -144,6 +170,59 @@ export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverrid
         loading_state: detectLoadingState(tree, source)
     };
 }
+export function getStateDelta(deviceKey, baseRevision, currentRevision) {
+    const state = snapshotStateByDevice.get(deviceKey);
+    if (!state || Date.now() - (state.historyTimes.get(baseRevision) ?? 0) > 10 * 60 * 1000 || Date.now() - state.updatedAt > 10 * 60 * 1000)
+        return null;
+    const base = state.history.get(baseRevision);
+    const current = state?.history.get(currentRevision);
+    if (!base || !current)
+        return null;
+    const added = [];
+    const changed = [];
+    const removed = [];
+    for (const [identity, element] of current) {
+        const before = base.get(identity);
+        if (!before)
+            added.push(element);
+        else if (JSON.stringify(stableElementSignature(before)) !== JSON.stringify(stableElementSignature(element)))
+            changed.push(element);
+    }
+    let index = 0;
+    for (const [identity, element] of base) {
+        if (!current.has(identity))
+            removed.push({ stable_id: element.stable_id ?? undefined, resourceId: element.resourceId ?? undefined, contentDescription: element.contentDescription ?? undefined, text: element.text ?? undefined, index });
+        index++;
+    }
+    const all = added.length + changed.length + removed.length;
+    const limit = 200;
+    return {
+        base_snapshot_revision: baseRevision,
+        snapshot_revision: currentRevision,
+        added: added.slice(0, limit),
+        changed: changed.slice(0, Math.max(0, limit - added.length)),
+        removed: removed.slice(0, Math.max(0, limit - added.length - changed.length)),
+        truncated: all > limit || state.oversized.has(baseRevision) || state.oversized.has(currentRevision),
+        ...((all > limit || state.oversized.has(baseRevision) || state.oversized.has(currentRevision))
+            ? { omitted_changes: Math.max(all - limit, state.oversized.get(baseRevision) ?? 0, state.oversized.get(currentRevision) ?? 0) } : {})
+    };
+}
+export function getLatestStateDelta(deviceKey) {
+    const state = snapshotStateByDevice.get(deviceKey);
+    if (!state || state.previousRevision === null)
+        return null;
+    return getStateDelta(deviceKey, state.previousRevision, state.revision);
+}
+export function retainConnectedDeviceSnapshots(platform, deviceIds) {
+    const keys = new Set(deviceIds.map(id => `${platform}:${id}`));
+    for (const key of snapshotStateByDevice.keys())
+        if (key.startsWith(`${platform}:`) && !keys.has(key))
+            snapshotStateByDevice.delete(key);
+}
+export function clearDeviceSnapshots(deviceKey) {
+    snapshotStateByDevice.delete(deviceKey);
+}
 export function resetSnapshotMetadataForTests() {
     snapshotStateByDevice.clear();
+    nextRevision = 1;
 }

package/dist/server/common.js

@@ -1,13 +1,18 @@
+import { recordTiming } from '../utils/timing.js';
 import { ToolsObserve } from '../observe/index.js';
 export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3;
 export const DEFAULT_MAX_RETRY_DEPTH = 3;
-export function wrapResponse(data) {
-    return {
-        content: [{
-                type: 'text',
-                text: JSON.stringify(data, null, 2)
-            }]
-    };
+export function wrapResponse(data, includeSerializationTiming = true) {
+    const start = performance.now();
+    let text = JSON.stringify(data, null, 2);
+    const elapsed = performance.now() - start;
+    const value = data;
+    if (includeSerializationTiming && value && typeof value === 'object' && value.timing && typeof value.timing === 'object') {
+        value.timing.serialization_ms = (value.timing.serialization_ms ?? 0) + elapsed;
+        recordTiming('serialization_ms', elapsed);
+        text = JSON.stringify(value, null, 2);
+    }
+    return { content: [{ type: 'text', text }] };
 }
 export function getStringArg(args, key) {
     const value = args[key];
@@ -230,6 +235,7 @@ function mapFailureCodeToFailureClass(code) {
         case 'STALE_REFERENCE':
             return 'TargetResolutionFailure';
         case 'ELEMENT_NOT_INTERACTABLE':
+        case 'ACTION_TIMEOUT':
             return 'ExecutionFailure';
         case 'TIMEOUT':
         case 'ACTION_REJECTED':
@@ -238,6 +244,7 @@ function mapFailureCodeToFailureClass(code) {
             return 'ExecutionFailure';
         case 'VERIFICATION_FAILED':
         case 'EXPECT_STATE_MISMATCH':
+        case 'ASSERTION_TIMEOUT':
             return 'VerificationFailure';
         case 'CONTROL_CONVERGENCE_FAILED':
             return 'ControlConvergenceFailure';

package/dist/server/journey-schema.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+const selector = z.object({
+    text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
+    accessibility_id: z.string().min(1).optional(), contains: z.boolean().optional()
+}).strict().refine(value => !!(value.text || value.resource_id || value.accessibility_id), 'Selector requires a target');
+const verificationMode = z.enum(['none', 'light', 'full']);
+const timeoutMs = z.number().int().min(100).max(60000).optional();
+const pollIntervalMs = z.number().int().min(50).max(1000).optional();
+const waitFor = z.object({
+    condition: z.enum(['exists', 'visible', 'clickable']).optional(),
+    timeoutMs: z.number().int().min(100).max(10000).optional(), pollIntervalMs,
+    match: z.object({ index: z.number().int().nonnegative().optional() }).strict().optional()
+}).strict();
+const target = { selector: selector.optional(), elementId: z.string().min(1).optional() };
+const exactlyOneTarget = (value) => Number(!!value.selector) + Number(!!value.elementId) === 1;
+const assertion = z.union([
+    z.object({ kind: z.literal('element_visible'), selector }).strict(),
+    z.object({ kind: z.literal('element_absent'), selector }).strict(),
+    z.object({ kind: z.literal('screen_fingerprint'), fingerprint: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal('state_equals'), property: z.string().min(1), expected: z.union([z.boolean(), z.number().finite(), z.string()]), ...target }).strict().refine(exactlyOneTarget)
+]);
+const id = z.string().min(1);
+const step = z.union([
+    z.object({ id, type: z.literal('start_app'), appId: z.string().min(1), verificationMode: verificationMode.optional() }).strict(),
+    z.object({ id, type: z.literal('tap'), ...target, waitFor: waitFor.optional(), verificationMode: verificationMode.optional() }).strict().refine(exactlyOneTarget),
+    z.object({ id, type: z.literal('wait'), selector, condition: z.enum(['exists', 'not_exists', 'visible', 'clickable']).optional(), timeoutMs, pollIntervalMs }).strict(),
+    z.object({ id, type: z.literal('assert'), assertion, timeoutMs, pollIntervalMs }).strict()
+]);
+export const tapElementControlsSchema = z.object({
+    elementId: z.string().min(1).optional(), selector: selector.optional(), waitFor: waitFor.optional()
+}).strict().refine(value => Number(!!value.elementId) + Number(!!value.selector) === 1 && (!value.elementId || !value.waitFor));
+export const journeySchema = z.object({
+    platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(),
+    responseMode: z.enum(['compact', 'debug']).default('compact'), captureOnFailure: z.boolean().default(false),
+    defaults: z.object({ verificationMode: verificationMode.optional(), actionTimeoutMs: z.number().int().finite().optional(), verificationTimeoutMs: z.number().int().finite().optional() }).strict().optional(),
+    steps: z.array(step).min(1).max(50)
+}).strict().refine(value => new Set(value.steps.map(step => step.id)).size === value.steps.length, 'Step IDs must be unique');
+const selectorJson = { type: 'object', additionalProperties: false, properties: {
+        text: { type: 'string', minLength: 1 }, resource_id: { type: 'string', minLength: 1 }, accessibility_id: { type: 'string', minLength: 1 }, contains: { type: 'boolean' }
+    }, anyOf: ['text', 'resource_id', 'accessibility_id'].map(key => ({ required: [key] })) };
+const targetJson = { selector: selectorJson, elementId: { type: 'string', minLength: 1 } };
+const oneTargetJson = [{ required: ['selector'], not: { required: ['elementId'] } }, { required: ['elementId'], not: { required: ['selector'] } }];
+const intervalJson = { timeoutMs: { type: 'integer', minimum: 100, maximum: 60000 }, pollIntervalMs: { type: 'integer', minimum: 50, maximum: 1000 } };
+const modeJson = { type: 'string', enum: ['none', 'light', 'full'] };
+const objectJson = (properties, required, extra = {}) => ({ type: 'object', additionalProperties: false, properties, required, ...extra });
+export const journeyStepsJson = {
+    type: 'array', minItems: 1, maxItems: 50, items: { oneOf: [
+            objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'start_app' }, appId: { type: 'string', minLength: 1 }, verificationMode: modeJson }, ['id', 'type', 'appId']),
+            objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'tap' }, ...targetJson, verificationMode: modeJson,
+                waitFor: objectJson({ ...intervalJson, timeoutMs: { type: 'integer', minimum: 100, maximum: 10000 }, condition: { enum: ['exists', 'visible', 'clickable'] }, match: objectJson({ index: { type: 'integer', minimum: 0 } }, []) }, [])
+            }, ['id', 'type'], { oneOf: oneTargetJson }),
+            objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'wait' }, selector: selectorJson, condition: { enum: ['exists', 'not_exists', 'visible', 'clickable'] }, ...intervalJson }, ['id', 'type', 'selector']),
+            objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'assert' }, ...intervalJson, assertion: { oneOf: [
+                        objectJson({ kind: { const: 'element_visible' }, selector: selectorJson }, ['kind', 'selector']),
+                        objectJson({ kind: { const: 'element_absent' }, selector: selectorJson }, ['kind', 'selector']),
+                        objectJson({ kind: { const: 'screen_fingerprint' }, fingerprint: { type: 'string', minLength: 1 } }, ['kind', 'fingerprint']),
+                        objectJson({ kind: { const: 'state_equals' }, ...targetJson, property: { type: 'string', minLength: 1 }, expected: { type: ['boolean', 'number', 'string'] } }, ['kind', 'property', 'expected'], { oneOf: oneTargetJson })
+                    ] } }, ['id', 'type', 'assertion'])
+        ] }
+};

package/dist/server/tool-definitions.js

@@ -1,3 +1,4 @@
+import { journeyStepsJson } from './journey-schema.js';
 export const toolDefinitions = [
     {
         name: 'start_app',
@@ -47,7 +48,11 @@ Failure Handling:
                 deviceId: {
                     type: 'string',
                     description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
-                }
+                },
+                verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
+                responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
+                actionTimeoutMs: { type: 'number', minimum: 100, maximum: 30000 },
+                verificationTimeoutMs: { type: 'number', minimum: 100, maximum: 60000 }
             },
             required: ['platform', 'appId']
         }
@@ -250,6 +255,7 @@ Failure Handling:
             properties: {
                 reason: { type: 'string', description: 'Optional reason for snapshot' },
                 includeLogs: { type: 'boolean', description: 'Whether to include logs', default: true },
+                includeScreenshot: { type: 'boolean', description: 'Whether to collect screenshot bytes', default: true },
                 logLines: { type: 'number', description: 'Maximum number of log lines to include', default: 200 },
                 platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
                 appId: { type: 'string', description: 'Optional appId to scope logs (package/bundle id)' },
@@ -307,7 +313,9 @@ Failure Handling:
                 deviceId: {
                     type: 'string',
                     description: 'Device Serial (Android) or UDID (iOS). Defaults to connected/booted device.'
-                }
+                },
+                responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
+                sinceSnapshotRevision: { type: 'number', minimum: 1 }
             },
             required: ['platform']
         }
@@ -729,7 +737,11 @@ Failure Handling:
                 deviceId: {
                     type: 'string',
                     description: 'Device Serial/UDID. Defaults to connected/booted device.'
-                }
+                },
+                verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
+                responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
+                actionTimeoutMs: { type: 'number', minimum: 100, maximum: 30000 },
+                verificationTimeoutMs: { type: 'number', minimum: 100, maximum: 60000 }
             },
             required: ['x', 'y']
         }
@@ -783,9 +795,14 @@ This tool reports execution success only. Verification must be done with a separ
                 elementId: {
                     type: 'string',
                     description: 'A unique element identifier returned by wait_for_ui'
-                }
-            },
-            required: ['elementId']
+                },
+                selector: { type: 'object', properties: { text: { type: 'string' }, resource_id: { type: 'string' }, accessibility_id: { type: 'string' }, contains: { type: 'boolean' } } },
+                waitFor: { type: 'object', properties: { condition: { type: 'string', enum: ['exists', 'visible', 'clickable'] }, timeoutMs: { type: 'number', minimum: 100, maximum: 10000 }, pollIntervalMs: { type: 'number', minimum: 50, maximum: 1000 }, match: { type: 'object', properties: { index: { type: 'number' } } } } },
+                platform: { type: 'string', enum: ['android', 'ios'] },
+                deviceId: { type: 'string' },
+                verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
+                responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' }
+            }
         }
     },
     {
@@ -1062,6 +1079,20 @@ BEHAVIOUR after outcome:
             required: ['uiChanged']
         }
     },
+    {
+        name: 'run_journey',
+        description: 'Run an ordered, bounded sequence of start_app, tap, wait, and deterministic assertion steps against one device. Stops after the first failed step.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: { type: 'string', enum: ['android', 'ios'] },
+                deviceId: { type: 'string' },
+                responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'compact' },
+                steps: { type: 'array', minItems: 1, maxItems: 50, items: { type: 'object', properties: { id: { type: 'string' }, type: { type: 'string', enum: ['start_app', 'tap', 'wait', 'assert'] } }, required: ['id', 'type'] } }
+            },
+            required: ['platform', 'steps']
+        }
+    },
     {
         name: 'get_network_activity',
         description: `Returns structured network events captured from platform logs since the last action.
@@ -1095,3 +1126,25 @@ Returns { requests: [], count: 0 } when no credible network signals are found.`,
         }
     }
 ];
+// Keep the additive execution controls consistent across all action tools.
+for (const tool of toolDefinitions) {
+    if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back'].includes(tool.name)) {
+        Object.assign(tool.inputSchema.properties, {
+            verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
+            responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
+            actionTimeoutMs: { type: 'integer', description: 'Dispatch budget in milliseconds, clamped to 100–30000.' },
+            verificationTimeoutMs: { type: 'integer', description: 'Light observation budget in milliseconds, clamped to 100–60000.' }
+        });
+    }
+    if (tool.name === 'tap_element')
+        Object.assign(tool.inputSchema, { oneOf: [{ required: ['elementId'], not: { required: ['selector'] } }, { required: ['selector'], not: { required: ['elementId'] } }] });
+    if (tool.name === 'run_journey')
+        Object.assign(tool.inputSchema.properties, {
+            steps: journeyStepsJson,
+            captureOnFailure: { type: 'boolean', default: false },
+            defaults: { type: 'object', additionalProperties: false, properties: {
+                    verificationMode: { type: 'string', enum: ['none', 'light', 'full'] },
+                    actionTimeoutMs: { type: 'integer' }, verificationTimeoutMs: { type: 'integer' }
+                } }
+        });
+}