mobile-debug-mcp 0.32.4 → 0.34.0

package/dist/server/condition-schema.js

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

package/dist/server/debugger-handlers.js

@@ -0,0 +1,38 @@
+import { debuggerContracts } from './debugger-schema.js';
+import { debuggerSessions, debuggerCapabilities } from '../debugger/sessions.js';
+import { DebuggerError, withDebuggerBudget } from '../debugger/worker.js';
+import { wrapResponse } from './common.js';
+function failure(code, summary = {}) {
+    return { ...wrapResponse({ debug_session_id: null, device: null, target: null, state: null,
+            captured_at_ms: Date.now(), capabilities: debuggerCapabilities, limitations: [], cleanup: null,
+            ...summary, success: false, error: { code, message: code, retryable: false } }), isError: true };
+}
+export async function handleDebugger(name, args, signal) {
+    const parsed = debuggerContracts[name].schema.safeParse(args);
+    if (!parsed.success)
+        return failure('INVALID_ARGUMENT');
+    const a = parsed.data;
+    const command = debuggerContracts[name].command;
+    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));
+        if (signal?.aborted && command === 'capabilities')
+            throw new DebuggerError('DEBUGGER_CANCELLED');
+        return { ...wrapResponse(result), ...(!result.success ? { isError: true } : {}) };
+    }
+    catch (e) {
+        const code = e instanceof DebuggerError ? e.code : 'DEBUGGER_WORKER_FAILED';
+        let summary = {};
+        if (a.debugSessionId) {
+            try {
+                summary = debuggerSessions.summary(a.debugSessionId);
+            }
+            catch { /* Unknown session */ }
+        }
+        return failure(code, { debug_session_id: a.debugSessionId ?? null,
+            device: a.deviceId ? { platform: 'android', id: a.deviceId } : null, ...summary });
+    }
+}

package/dist/server/debugger-schema.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+const text = z.string().min(1).max(512);
+const integer = z.number().int().safe().positive();
+const timeout = z.number().int().min(100).max(30000);
+const target = { platform: z.literal('android'), deviceId: text, appId: text.regex(/^[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/), processId: integer.optional() };
+const session = { debugSessionId: text };
+const stop = { ...session, stopId: text };
+const specs = {
+    get_debugger_capabilities: { fields: target, command: 'capabilities', description: 'Probe optional Android JDK/JDWP prerequisites and matching running debuggable processes; does not attach.' },
+    attach_debugger: { fields: target, command: 'attach', description: 'Attach an owned Android JDI session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.' },
+    get_debugger_state: { fields: session, command: 'state', description: 'Read debugger state, current stop and breakpoint/cleanup status.' },
+    set_debugger_breakpoint: { fields: { ...session, className: text.regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/), line: integer }, command: 'set', description: 'Set an exact binary-class and executable-source-line breakpoint; unloaded classes remain pending. No silent line relocation.' },
+    remove_debugger_breakpoint: { fields: { ...session, breakpointId: text }, command: 'remove', description: 'Remove an owned breakpoint; repeated removal succeeds.' },
+    wait_for_debugger_event: { fields: { ...session, afterSequence: z.number().int().safe().min(0).optional() }, command: 'events', description: 'Wait for bounded debugger events after a sequence cursor. Empty timeout does not affect execution; overflow is explicit.' },
+    get_debugger_stack: { fields: { ...stop, threadId: text, offset: z.number().int().min(0).max(999).optional(), limit: z.number().int().min(1).max(100).optional() }, command: 'stack', description: 'Read bounded stack frames for a stopped thread; IDs expire on resume.' },
+    get_debugger_locals: { fields: { ...stop, frameId: text }, command: 'locals', description: 'Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters. No evaluation or field traversal.' },
+    step_debugger: { fields: { ...stop, threadId: text, kind: z.enum(['into', 'over', 'out']) }, command: 'step', description: 'Acknowledge one-shot line stepping and resume. Wait for a subsequent stop event separately.' },
+    resume_debugger: { fields: stop, command: 'resume', description: 'Resume owned debugger suspension and immediately expire stopped references.' },
+    detach_debugger: { fields: session, command: 'detach', description: 'Dispose the owned debugger connection, release owned suspension and remove its exact forward. Idempotent; retries incomplete cleanup.' }
+};
+// Derive JSON schemas and runtime validation from the same small Zod field vocabulary.
+function jsonField(schema) {
+    if (schema instanceof z.ZodOptional)
+        return jsonField(schema.unwrap());
+    if (schema instanceof z.ZodLiteral)
+        return { type: 'string', enum: [schema.value] };
+    if (schema instanceof z.ZodEnum)
+        return { type: 'string', enum: schema.options };
+    if (schema instanceof z.ZodString)
+        return { type: 'string', minLength: 1, maxLength: 512, ...Object.assign({}, ...schema._def.checks.filter(c => c.kind === 'regex').map(c => ({ pattern: c.regex.source }))) };
+    if (schema instanceof z.ZodNumber)
+        return { type: 'integer', minimum: schema.minValue, maximum: schema.maxValue };
+    throw new Error('Unsupported debugger field schema');
+}
+export const debuggerContracts = Object.fromEntries(Object.entries(specs).map(([name, spec]) => [name, {
+        ...spec, schema: z.object({ ...spec.fields, timeoutMs: timeout.default(name === 'wait_for_debugger_event' ? 1000 : 10000) }).strict()
+    }]));
+export const debuggerTools = Object.entries(debuggerContracts).map(([name, spec]) => ({ name, description: spec.description,
+    inputSchema: { type: 'object', additionalProperties: false,
+        required: Object.entries(spec.fields).filter(([, field]) => !field.isOptional()).map(([key]) => key),
+        properties: { ...Object.fromEntries(Object.entries(spec.fields).map(([key, field]) => [key, jsonField(field)])), timeoutMs: { type: 'integer', minimum: 100, maximum: 30000, default: name === 'wait_for_debugger_event' ? 1000 : 10000 } } }
+}));

package/dist/server/journey-schema.js

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

package/dist/server/readiness-schema.js

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

package/dist/server/system-trace-schema.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+const target = { platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional() };
+export const traceTargetSchema = z.object(target).strict();
+export const traceStartSchema = z.object({ ...target, durationMs: z.number().int().min(1000).max(120000).default(30000) }).strict();
+export const traceControlSchema = z.object({ traceId: z.string().uuid() }).strict();
+const properties = { platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 } };
+export const systemTraceTools = [
+    { name: 'get_system_trace_capabilities', description: 'Probe Android Perfetto prerequisites without recording. Device-wide system tracing is optional; iOS is unsupported.',
+        inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties } },
+    { name: 'start_system_trace', description: 'Start bounded Android Perfetto recording, returning an owned trace_id. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Device-wide traces may contain sensitive system annotations; no upload.',
+        inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties: { ...properties, durationMs: { type: 'integer', minimum: 1000, maximum: 120000, default: 30000 } } } },
+    ...['get_system_trace_status', 'stop_system_trace', 'cancel_system_trace'].map(name => ({ name,
+        description: name === 'get_system_trace_status' ? 'Reconcile an owned trace and retrieve its state; finalise duration-completed capture.' :
+            name === 'stop_system_trace' ? 'Stop owned capture gracefully and retrieve a local Perfetto artifact. Retry after a transfer/cleanup failure.' : 'Stop owned capture and discard partial files. Already completed local artifacts are retained.',
+        inputSchema: { type: 'object', additionalProperties: false, required: ['traceId'], properties: { traceId: { type: 'string', format: 'uuid' } } }
+    }))
+];

package/dist/server/tool-definitions.js

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