mobile-debug-mcp 0.33.0 → 0.34.0

package/dist/observe/system-trace.js

@@ -0,0 +1,285 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+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;
+    }
+}
+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
+};
+export class SystemTraceSessions {
+    native;
+    time;
+    sessions = new Map();
+    closing = false;
+    constructor(native = new AndroidTraceNative(), time = clock) {
+        this.native = native;
+        this.time = time;
+    }
+    prune() {
+        const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.result.cleanup.status === 'complete');
+        for (const s of terminal)
+            if (this.time.mono() - s.terminalAt >= 600000)
+                this.sessions.delete(s.result.trace_id);
+        const remaining = terminal.filter(s => this.sessions.has(s.result.trace_id));
+        for (const s of remaining.slice(0, Math.max(0, remaining.length - 100)))
+            this.sessions.delete(s.result.trace_id);
+    }
+    get(id) { this.prune(); const s = this.sessions.get(id); if (!s)
+        throw new TraceError('TRACE_NOT_FOUND'); return s; }
+    snapshot(s) { return structuredClone(s.result); }
+    serial(s, fn) {
+        const result = s.queue.then(fn);
+        s.queue = result.catch(() => { });
+        return result;
+    }
+    async capabilities(device) { return this.native.capabilities(device); }
+    async start(device, duration = 30000) {
+        if (!Number.isInteger(duration) || duration < 1000 || duration > 120000)
+            throw new TraceError('INVALID_ARGUMENT');
+        this.prune();
+        const reserved = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete');
+        if (this.closing || reserved.length >= 4 || reserved.some(s => s.result.device.id === device))
+            throw new TraceError('TRACE_BUSY');
+        const id = randomUUID();
+        const result = { trace_id: id, session_id: evidenceSessionId(), device: { platform: 'android', id: device }, backend: 'perfetto',
+            state: 'starting', reason: null, completion_reason: null, capture_started_at_ms: null, capture_completed_at_ms: null,
+            artifact: null, cleanup: { status: 'pending', remaining_resources: [] }, correlation_ids: [], enabled_sources: [], unavailable_categories: [] };
+        const s = { result, remote: `/data/misc/perfetto-traces/mcp-${id}.perfetto-trace`, owner: null, stopped: true,
+            discard: false, deadline: Infinity, queue: Promise.resolve(), linked: new Set(), partial: new Set() };
+        this.sessions.set(id, s);
+        return this.serial(s, async () => {
+            let cap;
+            try {
+                cap = await this.native.capabilities(device);
+            }
+            catch {
+                this.fail(s, 'TRACE_UNSUPPORTED');
+                this.clean(s);
+                return this.snapshot(s);
+            }
+            s.result.enabled_sources = cap.enabled_sources;
+            s.result.unavailable_categories = cap.unavailable_categories;
+            if (!cap.supported || this.closing) {
+                this.fail(s, this.closing ? 'TRACE_BUSY' : 'TRACE_UNSUPPORTED');
+                this.clean(s);
+                return this.snapshot(s);
+            }
+            s.stopped = false;
+            s.result.cleanup.remaining_resources = [s.remote, 'device_capture'];
+            // Conservative host bounds include acknowledgement latency, not exact device start.
+            s.result.capture_started_at_ms = this.time.wall();
+            s.deadline = this.time.mono() + duration;
+            try {
+                await this.native.start(device, s.remote, duration, cap.enabled_sources);
+                s.owner = await this.native.find(device, s.remote);
+                s.result.state = 'recording';
+                s.timer = this.time.schedule(() => { void this.control(id, 'duration').catch(() => { }); }, Math.max(0, s.deadline - this.time.mono()));
+            }
+            catch (error) {
+                s.discard = true;
+                this.fail(s, this.code(error, 'TRACE_START_FAILED'));
+                try {
+                    await this.halt(s);
+                    await this.remove(s);
+                }
+                catch {
+                    s.result.cleanup.status = 'failed';
+                }
+            }
+            return this.snapshot(s);
+        });
+    }
+    code(error, fallback) { return error instanceof Error && error.message === 'ACTION_TIMEOUT' ? 'ACTION_TIMEOUT' : fallback; }
+    fail(s, reason) {
+        s.result.state = 'failed';
+        s.result.reason = reason;
+        s.result.completion_reason = 'error';
+        s.terminalAt = this.time.mono();
+    }
+    clean(s) {
+        s.result.cleanup = { status: 'complete', remaining_resources: [] };
+        s.terminalAt = this.time.mono();
+        this.prune();
+    }
+    async halt(s) {
+        if (s.stopped)
+            return;
+        const deadline = this.time.mono() + 10000;
+        await runWithBudget(10000, async () => {
+            const found = await this.native.find(s.result.device.id, s.remote);
+            if (found) {
+                if (s.owner && (s.owner.pid !== found.pid || s.owner.startTime !== found.startTime))
+                    throw new TraceError('TRACE_STOP_FAILED');
+                s.owner ??= found;
+                try {
+                    await this.native.stop(s.result.device.id, s.remote, s.owner);
+                }
+                catch (error) {
+                    // Natural expiry can win between identity lookup and SIGTERM. Only
+                    // confirmed absence permits finalisation; unreadable/reused identity fails.
+                    if (await this.native.find(s.result.device.id, s.remote))
+                        throw error;
+                }
+                while (await this.native.find(s.result.device.id, s.remote)) {
+                    if (this.time.mono() >= deadline)
+                        throw new TraceError('ACTION_TIMEOUT');
+                    remainingBudget();
+                    await this.time.sleep(100);
+                }
+            }
+        });
+        s.stopped = true;
+        s.result.capture_completed_at_ms = this.time.wall();
+        s.result.cleanup.remaining_resources = [s.remote];
+        for (const linked of s.linked)
+            s.partial.add(linked);
+    }
+    async remove(s) {
+        if (!s.stopped)
+            throw new TraceError('TRACE_STOP_FAILED');
+        await this.native.remove(s.result.device.id, s.remote);
+        if (s.local && !s.result.artifact) {
+            await fs.rm(s.local, { recursive: true, force: true });
+            s.local = undefined;
+        }
+        this.clean(s);
+    }
+    async artifact(s) {
+        if (s.result.artifact)
+            return;
+        s.local ??= await fs.mkdtemp(path.join(os.tmpdir(), 'mobile-debug-trace-'));
+        const local = s.local;
+        const partial = path.join(local, 'capture.partial');
+        try {
+            await fs.chmod(s.local, 0o700);
+            await this.native.pull(s.result.device.id, s.remote, partial);
+            const stat = await fs.stat(partial);
+            if (!stat.isFile() || stat.size <= 0 || stat.size > TRACE_MAX_BYTES)
+                throw new TraceError('TRACE_ARTIFACT_FAILED');
+            await fs.chmod(partial, 0o600);
+            const target = path.join(s.local, `${s.result.trace_id}.perfetto-trace`);
+            await fs.rename(partial, target);
+            s.result.artifact = { path: target, format: 'perfetto', size_bytes: stat.size };
+        }
+        catch (error) {
+            try {
+                await fs.rm(local, { recursive: true, force: true });
+                s.local = undefined;
+            }
+            catch {
+                s.result.cleanup.remaining_resources = [s.remote, local];
+            }
+            throw error;
+        }
+    }
+    async control(id, operation) {
+        const s = this.get(id);
+        return this.serial(s, async () => {
+            if (s.result.cleanup.status === 'complete')
+                return this.snapshot(s);
+            if (operation === 'status' && s.result.state === 'recording') {
+                try {
+                    if (await this.native.find(s.result.device.id, s.remote) && this.time.mono() < s.deadline)
+                        return this.snapshot(s);
+                }
+                catch (error) {
+                    this.fail(s, this.code(error, 'TRACE_STOP_FAILED'));
+                    s.result.cleanup.status = 'failed';
+                    return this.snapshot(s);
+                }
+            }
+            if (s.timer) {
+                this.time.clear(s.timer);
+                s.timer = undefined;
+            }
+            if (operation === 'cancel')
+                s.discard = true;
+            const hadStartFailure = s.discard && s.result.state === 'failed' && operation !== 'cancel';
+            s.result.state = 'stopping';
+            s.result.cleanup.status = 'pending';
+            try {
+                await this.halt(s);
+            }
+            catch (error) {
+                this.fail(s, this.code(error, 'TRACE_STOP_FAILED'));
+                s.result.cleanup.status = 'failed';
+                return this.snapshot(s);
+            }
+            if (!s.discard) {
+                try {
+                    await this.artifact(s);
+                }
+                catch (error) {
+                    this.fail(s, this.code(error, 'TRACE_ARTIFACT_FAILED'));
+                    s.result.cleanup.status = 'failed';
+                    return this.snapshot(s);
+                }
+            }
+            try {
+                await this.remove(s);
+            }
+            catch {
+                this.fail(s, 'TRACE_STOP_FAILED');
+                s.result.cleanup.status = 'failed';
+                return this.snapshot(s);
+            }
+            if (hadStartFailure)
+                s.result.state = 'failed';
+            else {
+                s.result.state = s.discard ? 'cancelled' : 'completed';
+                s.result.reason = s.discard ? 'TRACE_CANCELLED' : null;
+                s.result.completion_reason = s.discard ? 'cancelled' : operation === 'duration' || this.time.mono() >= s.deadline ? 'duration_limit' : 'requested';
+            }
+            return this.snapshot(s);
+        });
+    }
+    async link(id, device, correlation) {
+        const s = this.get(id);
+        if (device.platform !== 'android' || device.id !== s.result.device.id)
+            throw new TraceError('TRACE_NOT_FOUND');
+        const status = await this.control(id, 'status');
+        if (device.platform !== 'android' || device.id !== status.device.id || status.state !== 'recording')
+            throw new TraceError('TRACE_NOT_FOUND');
+        // Validate again after the asynchronous status call: stop/cancel may have won.
+        return this.serial(s, async () => {
+            if (s.result.state !== 'recording' || this.time.mono() >= s.deadline)
+                throw new TraceError('TRACE_NOT_FOUND');
+            if (!s.result.correlation_ids.includes(correlation)) {
+                if (s.result.correlation_ids.length >= 1000)
+                    throw new TraceError('TRACE_BUSY');
+                s.result.correlation_ids.push(correlation);
+            }
+            s.linked.add(correlation);
+            let finish;
+            return () => finish ??= (async () => {
+                let recording = false;
+                try {
+                    recording = (await this.control(id, 'status')).state === 'recording';
+                }
+                catch { /* Unavailable state cannot establish complete coverage. */ }
+                s.linked.delete(correlation);
+                return { trace_id: id, coverage: !recording || s.partial.has(correlation) || this.time.mono() >= s.deadline ? 'partial' : 'covered',
+                    clock_alignment: 'unknown' };
+            })();
+        });
+    }
+    async shutdown() {
+        this.closing = true;
+        // Independent device cleanup in parallel under one overall deadline.
+        return runWithBudget(10000, async () => {
+            await Promise.allSettled([...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete').map(s => this.control(s.result.trace_id, 'cancel')));
+            return [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete').map(s => this.snapshot(s));
+        });
+    }
+}
+export const systemTraces = new SystemTraceSessions();

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

@@ -32,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)

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,10 +1,14 @@
+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. Unresponsive/debugger-paused detection is unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
+        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 },
@@ -1175,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'] },