taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/adapters/runtime/mobile-mcp/mobile-mcp-responses.js

@@ -0,0 +1,180 @@
+import { normalizeBounds, normalizeResourceId } from "../../ui/layout-normalization.js";
+import { MobileMcpToolError } from "./mobile-mcp-errors.js";
+const DEVICES_TOOL = "mobile_list_available_devices";
+const SCREEN_SIZE_TOOL = "mobile_get_screen_size";
+const ELEMENTS_TOOL = "mobile_list_elements_on_screen";
+const ANDROID_PACKAGE_PATTERN = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/;
+export function assertMobileMcpToolText(toolName, text, expected) {
+    if (text !== expected) {
+        throw new MobileMcpToolError(toolName, `unexpected response from ${toolName}: expected "${expected}", received "${text}"`);
+    }
+}
+export function parseMobileMcpDevices(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new MobileMcpToolError(DEVICES_TOOL, `${DEVICES_TOOL} returned malformed JSON`, { cause: error });
+    }
+    if (parsed === null
+        || typeof parsed !== "object"
+        || !Array.isArray(parsed.devices)) {
+        throw new MobileMcpToolError(DEVICES_TOOL, `${DEVICES_TOOL} response is missing the devices array`);
+    }
+    const devices = parsed.devices;
+    return devices.map((entry) => {
+        if (entry === null
+            || typeof entry !== "object"
+            || typeof entry.id !== "string"
+            || typeof entry.platform !== "string") {
+            throw new MobileMcpToolError(DEVICES_TOOL, `${DEVICES_TOOL} returned an invalid device entry`);
+        }
+        const record = entry;
+        return {
+            id: record.id,
+            platform: record.platform,
+            ...(typeof record.name === "string" ? { name: record.name } : {}),
+            ...(typeof record.type === "string" ? { type: record.type } : {}),
+            ...(typeof record.version === "string" ? { version: record.version } : {}),
+            ...(typeof record.state === "string" ? { state: record.state } : {}),
+            ...(typeof record.model === "string" ? { model: record.model } : {})
+        };
+    });
+}
+export function parseMobileMcpScreenSize(text) {
+    const match = /^Screen size is (\d+)x(\d+) pixels$/.exec(text);
+    if (match === null) {
+        throw new MobileMcpToolError(SCREEN_SIZE_TOOL, `${SCREEN_SIZE_TOOL} returned an unrecognized response: "${text}"`);
+    }
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (width <= 0 || height <= 0) {
+        throw new MobileMcpToolError(SCREEN_SIZE_TOOL, `${SCREEN_SIZE_TOOL} returned a non-positive screen size`);
+    }
+    return { width, height };
+}
+export function parseMobileMcpElements(text) {
+    const prefix = "Found these elements on screen: ";
+    if (!text.startsWith(prefix)) {
+        throw new MobileMcpToolError(ELEMENTS_TOOL, `${ELEMENTS_TOOL} returned an unrecognized response: "${text}"`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text.slice(prefix.length));
+    }
+    catch (error) {
+        throw new MobileMcpToolError(ELEMENTS_TOOL, `${ELEMENTS_TOOL} returned a malformed element payload`, { cause: error });
+    }
+    if (!Array.isArray(parsed)) {
+        throw new MobileMcpToolError(ELEMENTS_TOOL, `${ELEMENTS_TOOL} returned a non-array element payload`);
+    }
+    return parsed.map((entry) => {
+        if (entry === null
+            || typeof entry !== "object"
+            || !isElementRect(entry.coordinates)) {
+            throw new MobileMcpToolError(ELEMENTS_TOOL, `${ELEMENTS_TOOL} returned an invalid element entry`);
+        }
+        const record = entry;
+        return {
+            coordinates: record.coordinates,
+            ...(typeof record.type === "string" ? { type: record.type } : {}),
+            ...(typeof record.text === "string" ? { text: record.text } : {}),
+            ...(typeof record.label === "string" ? { label: record.label } : {}),
+            ...(typeof record.name === "string" ? { name: record.name } : {}),
+            ...(typeof record.value === "string" ? { value: record.value } : {}),
+            ...(typeof record.identifier === "string"
+                ? { identifier: record.identifier }
+                : {}),
+            ...(record.focused === true ? { focused: true } : {})
+        };
+    });
+}
+function isElementRect(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const record = value;
+    return (Number.isInteger(record.x)
+        && Number.isInteger(record.y)
+        && Number.isInteger(record.width)
+        && Number.isInteger(record.height)
+        && record.x >= 0
+        && record.y >= 0
+        && record.width >= 0
+        && record.height >= 0);
+}
+export function parseMobileMcpAppPackages(text) {
+    const packages = [];
+    const seen = new Set();
+    for (const match of text.matchAll(/\(([^()]+)\)/g)) {
+        const candidate = match[1] ?? "";
+        if (!ANDROID_PACKAGE_PATTERN.test(candidate) || seen.has(candidate)) {
+            continue;
+        }
+        seen.add(candidate);
+        packages.push(candidate);
+    }
+    return packages;
+}
+export function mapMobileMcpElement(element, index) {
+    const { coordinates } = element;
+    const bounds = normalizeBounds({
+        left: coordinates.x,
+        top: coordinates.y,
+        right: coordinates.x + coordinates.width,
+        bottom: coordinates.y + coordinates.height
+    });
+    const center = bounds === undefined
+        ? undefined
+        : {
+            x: Math.floor((bounds.left + bounds.right) / 2),
+            y: Math.floor((bounds.top + bounds.bottom) / 2)
+        };
+    const resourceId = element.identifier === undefined
+        ? undefined
+        : normalizeResourceId(element.identifier);
+    return {
+        id: `mobile-mcp-${String(index)}`,
+        ...(resourceId === undefined ? {} : { resourceId }),
+        ...(element.text === undefined || element.text === ""
+            ? {}
+            : { text: element.text }),
+        ...(element.label === undefined || element.label === ""
+            ? {}
+            : { contentDescription: element.label }),
+        ...(element.focused === true ? { focused: true } : {}),
+        enabled: true,
+        ...(bounds === undefined || center === undefined
+            ? {}
+            : { bounds, center }),
+        children: []
+    };
+}
+export function mapMobileMcpSwipe(from, to) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    if (dx === 0 && dy === 0) {
+        throw new MobileMcpToolError("mobile_swipe_on_screen", "swipe requires movement: from and to coordinates are identical");
+    }
+    if (Math.abs(dx) >= Math.abs(dy)) {
+        return {
+            direction: dx > 0 ? "right" : "left",
+            x: from.x,
+            y: from.y,
+            distance: Math.abs(dx)
+        };
+    }
+    return {
+        direction: dy > 0 ? "down" : "up",
+        x: from.x,
+        y: from.y,
+        distance: Math.abs(dy)
+    };
+}
+export function mobileMcpSwipeResponse(mapping) {
+    return [
+        `Swiped ${mapping.direction} ${String(mapping.distance)} pixels`,
+        `from coordinates: ${String(mapping.x)}, ${String(mapping.y)}`
+    ].join(" ");
+}

package/dist/adapters/runtime/mobile-mcp/mobile-mcp-runtime-backend.d.ts

@@ -0,0 +1,78 @@
+import type { Point } from "../../../domain/geometry.js";
+import type { DisplayViewport } from "../../../domain/geometry.js";
+import type { DeviceInfo, RuntimeBackendDescriptor, RuntimeCapabilities } from "../../../domain/runtime.js";
+import type { UiBackendDescriptor } from "../../../domain/ui-backend.js";
+import type { CommandResult } from "../../../ports/process-runner.js";
+import type { OpenRuntimeSessionOptions, OpenRuntimeUiSnapshotsOptions, RuntimeAppQuery, RuntimeBackend, RuntimeLaunchOptions, RuntimeScreenshotOptions, RuntimeSession } from "../../../ports/runtime-backend.js";
+import type { CaptureUiSnapshotOptions, UiSnapshot, UiSnapshotProvider } from "../../../ports/ui-snapshot.js";
+import type { UiStabilityObservation, UiStabilityProbe, UiStabilitySampleOptions } from "../../../ports/ui-stability.js";
+import type { MobileMcpTools } from "./mobile-mcp-tools.js";
+export declare const MOBILE_MCP_RUNTIME_ADAPTER_VERSION = "mobile-mcp-runtime-v1";
+export declare const MOBILE_MCP_UI_ADAPTER_VERSION = "mobile-mcp-layout-v1";
+export declare const DEFAULT_MOBILE_MCP_SNAPSHOT_TIMEOUT_MS = 10000;
+export declare function mobileMcpRuntimeCapabilities(): RuntimeCapabilities;
+export declare function mobileMcpUiBackendDescriptor(engineVersion: string | undefined): UiBackendDescriptor;
+export declare class MobileMcpSnapshotProvider implements UiSnapshotProvider {
+    private readonly tools;
+    private readonly deviceSerial;
+    readonly descriptor: UiBackendDescriptor;
+    private readonly viewport;
+    private closed;
+    constructor(tools: MobileMcpTools, deviceSerial: string, descriptor: UiBackendDescriptor, viewport: DisplayViewport);
+    capture(options: CaptureUiSnapshotOptions): Promise<UiSnapshot>;
+    close(): Promise<void>;
+}
+export declare class MobileMcpUiStabilityProbe implements UiStabilityProbe {
+    private readonly tools;
+    private readonly signatures;
+    constructor(tools: MobileMcpTools);
+    reset(): void;
+    sample(options: UiStabilitySampleOptions): Promise<UiStabilityObservation>;
+}
+export interface MobileMcpRuntimeSessionDependencies {
+    tools: MobileMcpTools;
+    deviceSerial: string;
+    descriptor: RuntimeBackendDescriptor;
+}
+export declare class MobileMcpRuntimeSession implements RuntimeSession {
+    private readonly dependencies;
+    readonly descriptor: RuntimeBackendDescriptor;
+    readonly deviceSerial: string;
+    readonly currentActivity: undefined;
+    readonly deviceIdentity: undefined;
+    readonly foregroundComponent: undefined;
+    readonly appProcesses: undefined;
+    readonly windowTopology: undefined;
+    readonly startLogcat: undefined;
+    readonly dumpLogcat: undefined;
+    readonly annotatedScreens: undefined;
+    readonly startActivityByIntent: undefined;
+    readonly uiStability: UiStabilityProbe;
+    private uiSnapshotProvider;
+    constructor(dependencies: MobileMcpRuntimeSessionDependencies);
+    openUiSnapshots(options?: OpenRuntimeUiSnapshotsOptions): Promise<UiSnapshotProvider>;
+    private openSnapshotProvider;
+    isInstalled(app: RuntimeAppQuery): Promise<boolean>;
+    launchApp(options: RuntimeLaunchOptions): Promise<CommandResult>;
+    forceStop(app: RuntimeAppQuery): Promise<CommandResult>;
+    tap(point: Point, signal?: AbortSignal): Promise<CommandResult>;
+    longClick(point: Point, durationMs: number, signal?: AbortSignal): Promise<CommandResult>;
+    swipe(from: Point, to: Point, _durationMs: number, signal?: AbortSignal): Promise<CommandResult>;
+    back(signal?: AbortSignal): Promise<CommandResult>;
+    inputText(text: string, signal?: AbortSignal): Promise<CommandResult>;
+    captureScreenshot(options: RuntimeScreenshotOptions): Promise<CommandResult>;
+    private runToolAction;
+    close(): Promise<void>;
+}
+export interface MobileMcpRuntimeBackendDependencies {
+    createTools: () => MobileMcpTools;
+    engineVersion?: string | undefined;
+}
+export declare class MobileMcpRuntimeBackend implements RuntimeBackend {
+    private readonly dependencies;
+    readonly descriptor: RuntimeBackendDescriptor;
+    readonly capabilities: RuntimeCapabilities;
+    constructor(dependencies: MobileMcpRuntimeBackendDependencies);
+    listDevices(signal?: AbortSignal): Promise<readonly DeviceInfo[]>;
+    openSession(options: OpenRuntimeSessionOptions): Promise<RuntimeSession>;
+}

package/dist/adapters/runtime/mobile-mcp/mobile-mcp-runtime-backend.js

@@ -0,0 +1,379 @@
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, rename, copyFile, rm, unlink } from "node:fs/promises";
+import { dirname, extname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { performance } from "node:perf_hooks";
+import { snapshotFromCapture } from "../../ui/ui-snapshot-support.js";
+import { UiSnapshotError } from "../../ui/ui-snapshot-error.js";
+import { MobileMcpToolError } from "./mobile-mcp-errors.js";
+import { assertMobileMcpToolText, mapMobileMcpElement, mapMobileMcpSwipe, mobileMcpSwipeResponse, parseMobileMcpAppPackages, parseMobileMcpDevices, parseMobileMcpElements, parseMobileMcpScreenSize } from "./mobile-mcp-responses.js";
+export const MOBILE_MCP_RUNTIME_ADAPTER_VERSION = "mobile-mcp-runtime-v1";
+export const MOBILE_MCP_UI_ADAPTER_VERSION = "mobile-mcp-layout-v1";
+export const DEFAULT_MOBILE_MCP_SNAPSHOT_TIMEOUT_MS = 10_000;
+const SCREENSHOT_EXTENSIONS = [".png", ".jpg", ".jpeg"];
+export function mobileMcpRuntimeCapabilities() {
+    return {
+        layoutSnapshot: true,
+        screenshot: true,
+        annotatedScreens: false,
+        frameStatsIdle: false,
+        logs: false,
+        processDiscovery: false,
+        windowTopology: false,
+        intentStart: false,
+        foregroundActivity: false
+    };
+}
+export function mobileMcpUiBackendDescriptor(engineVersion) {
+    const config = { source: "mobile_list_elements_on_screen", version: 1 };
+    return {
+        id: "mobile-mcp",
+        adapterVersion: MOBILE_MCP_UI_ADAPTER_VERSION,
+        ...(engineVersion === undefined ? {} : { engineVersion }),
+        configSha256: createHash("sha256")
+            .update(JSON.stringify(config))
+            .digest("hex")
+    };
+}
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function successResult(stdout, durationMs) {
+    return {
+        exitCode: 0,
+        signal: null,
+        stdout,
+        stderr: "",
+        durationMs,
+        timedOut: false,
+        cancelled: false
+    };
+}
+function failureResult(stderr, durationMs, cancelled) {
+    return {
+        exitCode: 1,
+        signal: null,
+        stdout: "",
+        stderr,
+        durationMs,
+        timedOut: false,
+        cancelled
+    };
+}
+export class MobileMcpSnapshotProvider {
+    tools;
+    deviceSerial;
+    descriptor;
+    viewport;
+    closed = false;
+    constructor(tools, deviceSerial, descriptor, viewport) {
+        this.tools = tools;
+        this.deviceSerial = deviceSerial;
+        this.descriptor = descriptor;
+        this.viewport = viewport;
+    }
+    async capture(options) {
+        if (this.closed) {
+            throw new UiSnapshotError("UI_SNAPSHOT_FAILED", this.descriptor.id, "UI snapshot provider is closed");
+        }
+        const startedAt = performance.now();
+        let elements;
+        try {
+            const text = await this.tools.listElements(this.deviceSerial, {
+                timeoutMs: options.timeoutMs,
+                ...(options.signal === undefined ? {} : { signal: options.signal })
+            });
+            elements = parseMobileMcpElements(text);
+        }
+        catch (error) {
+            if (error instanceof UiSnapshotError) {
+                throw error;
+            }
+            throw new UiSnapshotError("UI_SNAPSHOT_FAILED", this.descriptor.id, errorMessage(error), { cause: error });
+        }
+        if (elements.length === 0) {
+            throw new UiSnapshotError("UI_SNAPSHOT_INVALID", this.descriptor.id, "mobile-mcp returned an empty layout");
+        }
+        const roots = elements.map(mapMobileMcpElement);
+        return snapshotFromCapture({
+            startedAt,
+            roots,
+            backend: this.descriptor,
+            viewport: this.viewport,
+            timing: {}
+        });
+    }
+    close() {
+        this.closed = true;
+        return Promise.resolve();
+    }
+}
+export class MobileMcpUiStabilityProbe {
+    tools;
+    signatures = new Map();
+    constructor(tools) {
+        this.tools = tools;
+    }
+    reset() {
+        this.signatures.clear();
+    }
+    async sample(options) {
+        const startedAt = performance.now();
+        const text = await this.tools.listElements(options.deviceSerial, {
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs })
+        });
+        const layout = parseMobileMcpElements(text).map(mapMobileMcpElement);
+        const signature = createHash("sha256")
+            .update(JSON.stringify(layout))
+            .digest("hex");
+        const key = options.deviceSerial;
+        const previous = this.signatures.get(key);
+        this.signatures.set(key, signature);
+        return {
+            changes: previous === signature
+                ? []
+                : [{ layoutSha256: signature }],
+            layout,
+            backend: "mobileMcp",
+            durationMs: performance.now() - startedAt
+        };
+    }
+}
+export class MobileMcpRuntimeSession {
+    dependencies;
+    descriptor;
+    deviceSerial;
+    currentActivity;
+    deviceIdentity;
+    foregroundComponent;
+    appProcesses;
+    windowTopology;
+    startLogcat;
+    dumpLogcat;
+    annotatedScreens;
+    startActivityByIntent;
+    uiStability;
+    uiSnapshotProvider;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        this.descriptor = dependencies.descriptor;
+        this.deviceSerial = dependencies.deviceSerial;
+        this.uiStability = new MobileMcpUiStabilityProbe(dependencies.tools);
+    }
+    openUiSnapshots(options) {
+        if (options?.backend !== undefined && options.backend !== "auto") {
+            return Promise.reject(new UiSnapshotError("UI_SNAPSHOT_FAILED", "mobile-mcp", `UI backend "${options.backend}" is not available through the mobile-mcp runtime backend`));
+        }
+        if (this.uiSnapshotProvider !== undefined) {
+            return this.uiSnapshotProvider;
+        }
+        const opened = this.openSnapshotProvider(options);
+        opened.catch(() => {
+            if (this.uiSnapshotProvider === opened) {
+                this.uiSnapshotProvider = undefined;
+            }
+        });
+        this.uiSnapshotProvider = opened;
+        return opened;
+    }
+    async openSnapshotProvider(options) {
+        try {
+            const text = await this.dependencies.tools.getScreenSize(this.deviceSerial, {
+                timeoutMs: options?.timeoutMs
+                    ?? DEFAULT_MOBILE_MCP_SNAPSHOT_TIMEOUT_MS,
+                ...(options?.signal === undefined ? {} : { signal: options.signal })
+            });
+            const size = parseMobileMcpScreenSize(text);
+            return new MobileMcpSnapshotProvider(this.dependencies.tools, this.deviceSerial, mobileMcpUiBackendDescriptor(this.dependencies.tools.serverVersion()), {
+                width: size.width,
+                height: size.height,
+                rotation: 0,
+                coordinateSpace: "physicalDisplayPixels"
+            });
+        }
+        catch (error) {
+            if (error instanceof UiSnapshotError) {
+                throw error;
+            }
+            throw new UiSnapshotError("UI_SNAPSHOT_FAILED", "mobile-mcp", errorMessage(error), { cause: error });
+        }
+    }
+    isInstalled(app) {
+        return this.dependencies.tools
+            .listApps(this.deviceSerial, {
+            ...(app.signal === undefined ? {} : { signal: app.signal }),
+            ...(app.timeoutMs === undefined ? {} : { timeoutMs: app.timeoutMs })
+        })
+            .then((text) => (parseMobileMcpAppPackages(text).includes(app.packageName)));
+    }
+    launchApp(options) {
+        return this.runToolAction(options.signal, async () => {
+            const text = await this.dependencies.tools.launchApp(this.deviceSerial, options.packageName, {
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+                ...(options.timeoutMs === undefined
+                    ? {}
+                    : { timeoutMs: options.timeoutMs })
+            });
+            assertMobileMcpToolText("mobile_launch_app", text, `Launched app ${options.packageName}`);
+            return text;
+        });
+    }
+    forceStop(app) {
+        return this.runToolAction(app.signal, async () => {
+            const text = await this.dependencies.tools.terminateApp(this.deviceSerial, app.packageName, {
+                ...(app.signal === undefined ? {} : { signal: app.signal }),
+                ...(app.timeoutMs === undefined ? {} : { timeoutMs: app.timeoutMs })
+            });
+            assertMobileMcpToolText("mobile_terminate_app", text, `Terminated app ${app.packageName}`);
+            return text;
+        });
+    }
+    tap(point, signal) {
+        return this.runToolAction(signal, async () => {
+            const text = await this.dependencies.tools.tap(this.deviceSerial, point.x, point.y, signal === undefined ? undefined : { signal });
+            assertMobileMcpToolText("mobile_click_on_screen_at_coordinates", text, `Clicked on screen at coordinates: ${String(point.x)}, ${String(point.y)}`);
+            return text;
+        });
+    }
+    longClick(point, durationMs, signal) {
+        return this.runToolAction(signal, async () => {
+            if (!Number.isInteger(durationMs) || durationMs < 1 || durationMs > 10_000) {
+                throw new MobileMcpToolError("mobile_long_press_on_screen_at_coordinates", `long press duration must be an integer between 1 and 10000 ms, received ${String(durationMs)}`);
+            }
+            const text = await this.dependencies.tools.longPress(this.deviceSerial, point.x, point.y, durationMs, signal === undefined ? undefined : { signal });
+            assertMobileMcpToolText("mobile_long_press_on_screen_at_coordinates", text, [
+                "Long pressed on screen at coordinates:",
+                `${String(point.x)}, ${String(point.y)}`,
+                `for ${String(durationMs)}ms`
+            ].join(" "));
+            return text;
+        });
+    }
+    swipe(from, to, _durationMs, signal) {
+        return this.runToolAction(signal, async () => {
+            const mapping = mapMobileMcpSwipe(from, to);
+            const text = await this.dependencies.tools.swipe(this.deviceSerial, mapping.direction, mapping.x, mapping.y, mapping.distance, signal === undefined ? undefined : { signal });
+            assertMobileMcpToolText("mobile_swipe_on_screen", text, mobileMcpSwipeResponse(mapping));
+            return text;
+        });
+    }
+    back(signal) {
+        return this.runToolAction(signal, async () => {
+            const text = await this.dependencies.tools.pressButton(this.deviceSerial, "BACK", signal === undefined ? undefined : { signal });
+            assertMobileMcpToolText("mobile_press_button", text, "Pressed the button: BACK");
+            return text;
+        });
+    }
+    inputText(text, signal) {
+        return this.runToolAction(signal, async () => {
+            const response = await this.dependencies.tools.typeKeys(this.deviceSerial, text, false, signal === undefined ? undefined : { signal });
+            assertMobileMcpToolText("mobile_type_keys", response, `Typed text: ${text}`);
+            return response;
+        });
+    }
+    captureScreenshot(options) {
+        if (options.annotate === true) {
+            return Promise.resolve(failureResult("the mobile-mcp runtime backend cannot annotate screenshots", 0, false));
+        }
+        const extension = extname(options.outputPath).toLowerCase();
+        if (!SCREENSHOT_EXTENSIONS.includes(extension)) {
+            return Promise.resolve(failureResult(`screenshot output must end with ${SCREENSHOT_EXTENSIONS.join(", ")}, received "${options.outputPath}"`, 0, false));
+        }
+        return this.runToolAction(options.signal, async () => {
+            const tempDir = await mkdtemp(join(tmpdir(), "taphound-mobile-mcp-"));
+            let tempPath;
+            try {
+                tempPath = join(tempDir, `screenshot${extension}`);
+                const text = await this.dependencies.tools.saveScreenshot(this.deviceSerial, tempPath, {
+                    ...(options.signal === undefined ? {} : { signal: options.signal }),
+                    ...(options.timeoutMs === undefined
+                        ? {}
+                        : { timeoutMs: options.timeoutMs })
+                });
+                assertMobileMcpToolText("mobile_save_screenshot", text, `Screenshot saved to: ${tempPath}`);
+                await mkdir(dirname(options.outputPath), { recursive: true });
+                try {
+                    await rename(tempPath, options.outputPath);
+                }
+                catch {
+                    await copyFile(tempPath, options.outputPath);
+                    await unlink(tempPath).catch(() => { });
+                }
+                return `Screenshot saved to: ${options.outputPath}`;
+            }
+            finally {
+                await rm(tempDir, { recursive: true, force: true }).catch(() => { });
+            }
+        });
+    }
+    async runToolAction(signal, invoke) {
+        const startedAt = performance.now();
+        try {
+            const stdout = await invoke();
+            return successResult(stdout, performance.now() - startedAt);
+        }
+        catch (error) {
+            return failureResult(errorMessage(error), performance.now() - startedAt, signal?.aborted === true);
+        }
+    }
+    async close() {
+        const provider = this.uiSnapshotProvider;
+        this.uiSnapshotProvider = undefined;
+        if (provider !== undefined) {
+            await provider.then((snapshotProvider) => snapshotProvider.close(), () => undefined);
+        }
+        await this.dependencies.tools.close();
+    }
+}
+export class MobileMcpRuntimeBackend {
+    dependencies;
+    descriptor;
+    capabilities;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        const capabilities = mobileMcpRuntimeCapabilities();
+        this.capabilities = capabilities;
+        this.descriptor = {
+            id: "mobile-mcp",
+            adapterVersion: MOBILE_MCP_RUNTIME_ADAPTER_VERSION,
+            ...(dependencies.engineVersion === undefined
+                ? {}
+                : { engineVersion: dependencies.engineVersion }),
+            configSha256: createHash("sha256").update(JSON.stringify({
+                id: "mobile-mcp",
+                adapterVersion: MOBILE_MCP_RUNTIME_ADAPTER_VERSION,
+                ...(dependencies.engineVersion === undefined
+                    ? {}
+                    : { engineVersion: dependencies.engineVersion }),
+                capabilities
+            })).digest("hex"),
+            capabilities
+        };
+    }
+    async listDevices(signal) {
+        const tools = this.dependencies.createTools();
+        try {
+            const text = await tools.listDevices(signal === undefined ? undefined : { signal });
+            return parseMobileMcpDevices(text)
+                .filter((device) => (device.platform === "android" && device.state === "online"))
+                .map((device) => ({
+                serial: device.id,
+                status: "device"
+            }));
+        }
+        finally {
+            await tools.close();
+        }
+    }
+    openSession(options) {
+        return Promise.resolve(new MobileMcpRuntimeSession({
+            tools: this.dependencies.createTools(),
+            deviceSerial: options.deviceSerial,
+            descriptor: this.descriptor
+        }));
+    }
+}

package/dist/adapters/runtime/mobile-mcp/mobile-mcp-tools.d.ts

@@ -0,0 +1,46 @@
+export type MobileMcpSwipeDirection = "up" | "down" | "left" | "right";
+export interface MobileMcpDeviceEntry {
+    id: string;
+    name?: string | undefined;
+    platform: string;
+    type?: string | undefined;
+    version?: string | undefined;
+    state?: string | undefined;
+    model?: string | undefined;
+}
+export interface MobileMcpElementRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface MobileMcpElement {
+    type?: string | undefined;
+    text?: string | undefined;
+    label?: string | undefined;
+    name?: string | undefined;
+    value?: string | undefined;
+    identifier?: string | undefined;
+    coordinates: MobileMcpElementRect;
+    focused?: boolean | undefined;
+}
+export interface MobileMcpToolCallOptions {
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface MobileMcpTools {
+    listDevices(options?: MobileMcpToolCallOptions): Promise<string>;
+    getScreenSize(device: string, options?: MobileMcpToolCallOptions): Promise<string>;
+    listElements(device: string, options?: MobileMcpToolCallOptions): Promise<string>;
+    listApps(device: string, options?: MobileMcpToolCallOptions): Promise<string>;
+    launchApp(device: string, packageName: string, options?: MobileMcpToolCallOptions): Promise<string>;
+    terminateApp(device: string, packageName: string, options?: MobileMcpToolCallOptions): Promise<string>;
+    tap(device: string, x: number, y: number, options?: MobileMcpToolCallOptions): Promise<string>;
+    longPress(device: string, x: number, y: number, durationMs: number, options?: MobileMcpToolCallOptions): Promise<string>;
+    swipe(device: string, direction: MobileMcpSwipeDirection, x?: number, y?: number, distance?: number, options?: MobileMcpToolCallOptions): Promise<string>;
+    pressButton(device: string, button: string, options?: MobileMcpToolCallOptions): Promise<string>;
+    typeKeys(device: string, text: string, submit: boolean, options?: MobileMcpToolCallOptions): Promise<string>;
+    saveScreenshot(device: string, saveTo: string, options?: MobileMcpToolCallOptions): Promise<string>;
+    serverVersion(): string | undefined;
+    close(): Promise<void>;
+}