taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/adapters/runtime/fake-runtime-backend.js

@@ -0,0 +1,240 @@
+import { createHash } from "node:crypto";
+export const FAKE_RUNTIME_ADAPTER_VERSION = "fake-runtime-v1";
+export function fakeRuntimeCapabilities() {
+    return {
+        layoutSnapshot: true,
+        screenshot: true,
+        annotatedScreens: false,
+        frameStatsIdle: false,
+        logs: true,
+        processDiscovery: true,
+        windowTopology: false,
+        intentStart: false,
+        foregroundActivity: false
+    };
+}
+function successResult() {
+    return {
+        exitCode: 0,
+        signal: null,
+        stdout: "",
+        stderr: "",
+        durationMs: 0,
+        timedOut: false,
+        cancelled: false
+    };
+}
+function fakeViewport() {
+    return {
+        width: 1080,
+        height: 1920,
+        rotation: 0,
+        coordinateSpace: "physicalDisplayPixels"
+    };
+}
+export function fakeRuntimeUiSnapshotProvider(provider) {
+    const descriptor = {
+        id: "system-uiautomator",
+        adapterVersion: "fake-runtime-v1",
+        configSha256: "0".repeat(64)
+    };
+    return {
+        descriptor,
+        capture: () => Promise.resolve({
+            observationId: "fake-observation",
+            capturedAt: "2026-01-01T00:00:00.000Z",
+            durationMs: 0,
+            backend: descriptor,
+            viewport: fakeViewport(),
+            roots: []
+        }),
+        close: () => Promise.resolve(),
+        ...(provider === undefined ? {} : provider)
+    };
+}
+export class FakeRuntimeSession {
+    descriptor;
+    deviceSerial;
+    uiSnapshotProvider;
+    capabilities;
+    currentActivity;
+    deviceIdentity;
+    foregroundComponent;
+    appProcesses;
+    windowTopology;
+    startLogcat;
+    dumpLogcat;
+    annotatedScreens = undefined;
+    uiStability;
+    startActivityByIntent = undefined;
+    state;
+    calls = [];
+    lastUiSnapshotOptions;
+    openedUiSnapshots;
+    constructor(input) {
+        this.descriptor = input.descriptor;
+        this.deviceSerial = input.deviceSerial;
+        this.capabilities = input.descriptor.capabilities;
+        this.state = input.state ?? {};
+        this.uiSnapshotProvider = input.uiSnapshots
+            ?? fakeRuntimeUiSnapshotProvider();
+        this.uiStability = input.uiStability ?? {
+            reset: () => undefined,
+            sample: () => Promise.resolve([])
+        };
+        this.currentActivity = this.capabilities.foregroundActivity
+            ? (app) => {
+                this.calls.push(`currentActivity:${app.packageName}`);
+                return Promise.resolve(this.state.currentActivity ?? "com.example.app.FakeActivity");
+            }
+            : undefined;
+        this.deviceIdentity = input.deviceIdentity === undefined
+            ? undefined
+            : (app) => {
+                this.calls.push(`deviceIdentity:${app.packageName}`);
+                return Promise.resolve(input.deviceIdentity);
+            };
+        this.foregroundComponent = this.capabilities.foregroundActivity
+            ? (app) => {
+                this.calls.push(`foregroundComponent:${app.packageName}`);
+                return Promise.resolve(this.state.foreground ?? {
+                    packageName: "com.example.app",
+                    activity: "com.example.app.FakeActivity"
+                });
+            }
+            : undefined;
+        this.appProcesses = this.capabilities.processDiscovery
+            ? (app) => {
+                this.calls.push(`appProcesses:${app.packageName}`);
+                return Promise.resolve(this.state.processes ?? [{ pid: 42, name: "com.example.app" }]);
+            }
+            : undefined;
+        this.windowTopology = this.capabilities.windowTopology
+            ? (app) => {
+                this.calls.push(`windowTopology:${app.packageName}`);
+                return Promise.resolve(this.state.topology ?? {
+                    version: 1,
+                    status: "unavailable",
+                    windows: [],
+                    diagnostic: "fake runtime backend has no window topology"
+                });
+            }
+            : undefined;
+        this.startLogcat = this.capabilities.logs
+            ? (options) => {
+                this.calls.push("startLogcat");
+                const completion = Promise.resolve(successResult());
+                return {
+                    started: Promise.resolve(undefined),
+                    completion,
+                    stop: () => {
+                        options.onStdoutLine("01-01 00:00:00.000  42  42 I Fake: ready");
+                        return completion;
+                    }
+                };
+            }
+            : undefined;
+        this.dumpLogcat = this.capabilities.logs
+            ? (options) => {
+                this.calls.push(`dumpLogcat:${String(options.maxLines)}`);
+                return Promise.resolve(this.state.dumpLogcatResult ?? successResult());
+            }
+            : undefined;
+    }
+    openUiSnapshots(options) {
+        this.calls.push("openUiSnapshots");
+        this.lastUiSnapshotOptions = options;
+        this.openedUiSnapshots ??= this.uiSnapshotProvider;
+        return Promise.resolve(this.openedUiSnapshots);
+    }
+    isInstalled(app) {
+        this.calls.push(`isInstalled:${app.packageName}`);
+        return Promise.resolve(this.state.installed ?? true);
+    }
+    launchApp(options) {
+        this.calls.push(`launchApp:${options.packageName}:${options.activity}`);
+        return Promise.resolve(successResult());
+    }
+    forceStop(app) {
+        this.calls.push(`forceStop:${app.packageName}`);
+        return Promise.resolve(successResult());
+    }
+    tap(point) {
+        this.calls.push(`tap:${String(point.x)},${String(point.y)}`);
+        return Promise.resolve(successResult());
+    }
+    longClick(point, durationMs) {
+        this.calls.push(`longClick:${String(point.x)},${String(point.y)}:${String(durationMs)}`);
+        return Promise.resolve(successResult());
+    }
+    swipe(from, to, durationMs) {
+        this.calls.push([
+            "swipe",
+            String(from.x),
+            String(from.y),
+            String(to.x),
+            String(to.y),
+            String(durationMs)
+        ].join(":"));
+        return Promise.resolve(successResult());
+    }
+    back() {
+        this.calls.push("back");
+        return Promise.resolve(successResult());
+    }
+    inputText(text) {
+        this.calls.push(`inputText:${text}`);
+        return Promise.resolve(successResult());
+    }
+    captureScreenshot(options) {
+        this.calls.push(`captureScreenshot:${options.outputPath}`);
+        return Promise.resolve(successResult());
+    }
+    close() {
+        this.calls.push("close");
+        const opened = this.openedUiSnapshots;
+        this.openedUiSnapshots = undefined;
+        return opened === undefined
+            ? Promise.resolve()
+            : opened.close();
+    }
+}
+export class FakeRuntimeBackend {
+    descriptor;
+    capabilities;
+    devices;
+    openCalls = [];
+    sessions = [];
+    createSession;
+    constructor(options = {}) {
+        const capabilities = options.capabilities ?? fakeRuntimeCapabilities();
+        this.capabilities = capabilities;
+        this.devices = options.devices ?? [
+            { serial: "emulator-5554", status: "device" }
+        ];
+        this.createSession = options.sessions ?? ((sessionOptions) => {
+            const session = new FakeRuntimeSession({
+                descriptor: this.descriptor,
+                deviceSerial: sessionOptions.deviceSerial
+            });
+            this.sessions.push(session);
+            return session;
+        });
+        this.descriptor = {
+            id: "adb",
+            adapterVersion: FAKE_RUNTIME_ADAPTER_VERSION,
+            configSha256: createHash("sha256").update(JSON.stringify({
+                adapterVersion: FAKE_RUNTIME_ADAPTER_VERSION,
+                capabilities
+            })).digest("hex"),
+            capabilities
+        };
+    }
+    listDevices() {
+        return Promise.resolve(this.devices);
+    }
+    openSession(options) {
+        this.openCalls.push(options);
+        return Promise.resolve(this.createSession(options));
+    }
+}

package/dist/adapters/runtime/mobile-mcp/mcp-tool-client.d.ts

@@ -0,0 +1,45 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { MobileMcpToolCallOptions, MobileMcpSwipeDirection, MobileMcpTools } from "./mobile-mcp-tools.js";
+export declare const MCP_TOOL_CLIENT_VERSION = "mcp-tool-client-v1";
+export declare const DEFAULT_MOBILE_MCP_COMMAND = "mcp-server-mobile";
+export declare const DEFAULT_MOBILE_MCP_TOOL_TIMEOUT_MS = 60000;
+export interface McpToolClientOptions {
+    command?: string | undefined;
+    args?: readonly string[] | undefined;
+    env?: Readonly<Record<string, string>> | undefined;
+    clientName?: string | undefined;
+    clientVersion?: string | undefined;
+    defaultTimeoutMs?: number | undefined;
+    transportFactory?: (() => Transport) | undefined;
+}
+export declare function defaultToolEnv(): Record<string, string>;
+export declare class McpToolClient implements MobileMcpTools {
+    private client;
+    private connecting;
+    private closed;
+    private readonly command;
+    private readonly args;
+    private readonly env;
+    private readonly clientName;
+    private readonly clientVersion;
+    private readonly defaultTimeoutMs;
+    private readonly transportFactory;
+    constructor(options?: McpToolClientOptions);
+    private ensureConnected;
+    private connect;
+    private callTool;
+    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>;
+}

package/dist/adapters/runtime/mobile-mcp/mcp-tool-client.js

@@ -0,0 +1,153 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { MobileMcpToolError, mobileMcpConnectError } from "./mobile-mcp-errors.js";
+export const MCP_TOOL_CLIENT_VERSION = "mcp-tool-client-v1";
+export const DEFAULT_MOBILE_MCP_COMMAND = "mcp-server-mobile";
+export const DEFAULT_MOBILE_MCP_TOOL_TIMEOUT_MS = 60_000;
+export function defaultToolEnv() {
+    const env = {
+        MOBILEMCP_DISABLE_TELEMETRY: "1"
+    };
+    if (process.env.TMPDIR !== undefined) {
+        env.TMPDIR = process.env.TMPDIR;
+    }
+    if (process.env.ANDROID_HOME !== undefined) {
+        env.ANDROID_HOME = process.env.ANDROID_HOME;
+    }
+    return env;
+}
+function outcomeText(outcome) {
+    const parts = [];
+    for (const block of outcome.content) {
+        if (block.type === "text" && typeof block.text === "string") {
+            parts.push(block.text);
+        }
+    }
+    return parts.join("\n");
+}
+export class McpToolClient {
+    client;
+    connecting;
+    closed = false;
+    command;
+    args;
+    env;
+    clientName;
+    clientVersion;
+    defaultTimeoutMs;
+    transportFactory;
+    constructor(options = {}) {
+        this.command = options.command ?? DEFAULT_MOBILE_MCP_COMMAND;
+        this.args = options.args ?? [];
+        this.env = { ...defaultToolEnv(), ...(options.env ?? {}) };
+        this.clientName = options.clientName ?? "taphound";
+        this.clientVersion = options.clientVersion ?? MCP_TOOL_CLIENT_VERSION;
+        this.defaultTimeoutMs = options.defaultTimeoutMs
+            ?? DEFAULT_MOBILE_MCP_TOOL_TIMEOUT_MS;
+        this.transportFactory = options.transportFactory
+            ?? (() => new StdioClientTransport({
+                command: this.command,
+                args: [...this.args],
+                env: this.env,
+                stderr: "ignore"
+            }));
+    }
+    ensureConnected() {
+        if (this.client !== undefined) {
+            return Promise.resolve(this.client);
+        }
+        if (this.connecting === undefined) {
+            const connecting = this.connect().then((client) => {
+                this.client = client;
+                return client;
+            });
+            connecting.catch(() => {
+                if (this.connecting === connecting) {
+                    this.connecting = undefined;
+                }
+            });
+            this.connecting = connecting;
+        }
+        return this.connecting;
+    }
+    async connect() {
+        if (this.closed) {
+            throw new Error("MCP tool client is closed");
+        }
+        const client = new Client({ name: this.clientName, version: this.clientVersion }, { capabilities: {} });
+        const transport = this.transportFactory();
+        try {
+            await client.connect(transport);
+        }
+        catch (error) {
+            throw mobileMcpConnectError(this.command, error);
+        }
+        return client;
+    }
+    async callTool(name, args, options) {
+        const client = await this.ensureConnected();
+        const result = await client.callTool({ name, arguments: args }, undefined, {
+            timeout: options?.timeoutMs ?? this.defaultTimeoutMs,
+            ...(options?.signal === undefined ? {} : { signal: options.signal })
+        });
+        const text = outcomeText(result);
+        if (result.isError === true) {
+            throw new MobileMcpToolError(name, text || `${name} failed without a message`);
+        }
+        return text;
+    }
+    listDevices(options) {
+        return this.callTool("mobile_list_available_devices", {}, options);
+    }
+    getScreenSize(device, options) {
+        return this.callTool("mobile_get_screen_size", { device }, options);
+    }
+    listElements(device, options) {
+        return this.callTool("mobile_list_elements_on_screen", { device }, options);
+    }
+    listApps(device, options) {
+        return this.callTool("mobile_list_apps", { device }, options);
+    }
+    launchApp(device, packageName, options) {
+        return this.callTool("mobile_launch_app", { device, packageName }, options);
+    }
+    terminateApp(device, packageName, options) {
+        return this.callTool("mobile_terminate_app", { device, packageName }, options);
+    }
+    tap(device, x, y, options) {
+        return this.callTool("mobile_click_on_screen_at_coordinates", { device, x, y }, options);
+    }
+    longPress(device, x, y, durationMs, options) {
+        return this.callTool("mobile_long_press_on_screen_at_coordinates", { device, x, y, duration: durationMs }, options);
+    }
+    swipe(device, direction, x, y, distance, options) {
+        return this.callTool("mobile_swipe_on_screen", {
+            device,
+            direction,
+            ...(x === undefined ? {} : { x }),
+            ...(y === undefined ? {} : { y }),
+            ...(distance === undefined ? {} : { distance })
+        }, options);
+    }
+    pressButton(device, button, options) {
+        return this.callTool("mobile_press_button", { device, button }, options);
+    }
+    typeKeys(device, text, submit, options) {
+        return this.callTool("mobile_type_keys", { device, text, submit }, options);
+    }
+    saveScreenshot(device, saveTo, options) {
+        return this.callTool("mobile_save_screenshot", { device, saveTo }, options);
+    }
+    serverVersion() {
+        return this.client?.getServerVersion()?.version;
+    }
+    async close() {
+        this.closed = true;
+        const client = this.client;
+        this.client = undefined;
+        this.connecting = undefined;
+        if (client !== undefined) {
+            await client.close();
+        }
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { FailureCode } from "../../../domain/failure.js";
+export declare class MobileMcpToolError extends Error {
+    readonly name = "MobileMcpToolError";
+    readonly toolName: string;
+    constructor(toolName: string, message: string, options?: ErrorOptions);
+}
+export interface MobileMcpConnectError extends Error {
+    code: FailureCode;
+}
+/**
+ * Detects spawn-level failures ("spawn mcp-server-mobile ENOENT", EACCES,
+ * ...) in either a raised error or a captured `CommandResult.spawnError`
+ * string, so every consumer can offer the same remediation.
+ */
+export declare function isMobileMcpSpawnFailureDetail(detail: string): boolean;
+export declare function mobileMcpServerUnavailableMessage(command: string, detail: string): string;
+/**
+ * Wraps Mobile MCP server connection failures as coded
+ * `ENVIRONMENT_MISSING_TOOL` errors. Spawn failures additionally explain how
+ * to install the server or escape to the adb backend, so a missing
+ * `mcp-server-mobile` binary never surfaces as a bare ENOENT.
+ */
+export declare function mobileMcpConnectError(command: string, cause: unknown): MobileMcpConnectError;

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

@@ -0,0 +1,39 @@
+export class MobileMcpToolError extends Error {
+    name = "MobileMcpToolError";
+    toolName;
+    constructor(toolName, message, options) {
+        super(message, options);
+        this.toolName = toolName;
+    }
+}
+const SPAWN_FAILURE_MARKERS = ["ENOENT", "EACCES"];
+/**
+ * Detects spawn-level failures ("spawn mcp-server-mobile ENOENT", EACCES,
+ * ...) in either a raised error or a captured `CommandResult.spawnError`
+ * string, so every consumer can offer the same remediation.
+ */
+export function isMobileMcpSpawnFailureDetail(detail) {
+    return SPAWN_FAILURE_MARKERS.some((marker) => detail.includes(marker));
+}
+export function mobileMcpServerUnavailableMessage(command, detail) {
+    return `The Mobile MCP server command "${command}" is not available (${detail}). `
+        + 'Install it with "npm install -g @mobilenext/mobile-mcp" and make sure '
+        + `"${command}" is on PATH, or select the adb backend through `
+        + "runtime.backend in .taphound/config.json or the "
+        + "TAPHOUND_RUNTIME_BACKEND environment variable (for example \"adb\").";
+}
+/**
+ * Wraps Mobile MCP server connection failures as coded
+ * `ENVIRONMENT_MISSING_TOOL` errors. Spawn failures additionally explain how
+ * to install the server or escape to the adb backend, so a missing
+ * `mcp-server-mobile` binary never surfaces as a bare ENOENT.
+ */
+export function mobileMcpConnectError(command, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    const message = isMobileMcpSpawnFailureDetail(detail)
+        ? mobileMcpServerUnavailableMessage(command, detail)
+        : `Failed to connect to the Mobile MCP server "${command}": ${detail}`;
+    const error = new Error(message, { cause });
+    error.code = "ENVIRONMENT_MISSING_TOOL";
+    return error;
+}

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

@@ -0,0 +1,20 @@
+import type { LayoutElement } from "../../../domain/layout.js";
+import type { Point } from "../../../domain/geometry.js";
+import type { MobileMcpDeviceEntry, MobileMcpElement, MobileMcpSwipeDirection } from "./mobile-mcp-tools.js";
+export declare function assertMobileMcpToolText(toolName: string, text: string, expected: string): void;
+export declare function parseMobileMcpDevices(text: string): readonly MobileMcpDeviceEntry[];
+export declare function parseMobileMcpScreenSize(text: string): {
+    width: number;
+    height: number;
+};
+export declare function parseMobileMcpElements(text: string): readonly MobileMcpElement[];
+export declare function parseMobileMcpAppPackages(text: string): readonly string[];
+export declare function mapMobileMcpElement(element: MobileMcpElement, index: number): LayoutElement;
+export interface MobileMcpSwipeMapping {
+    direction: MobileMcpSwipeDirection;
+    x: number;
+    y: number;
+    distance: number;
+}
+export declare function mapMobileMcpSwipe(from: Point, to: Point): MobileMcpSwipeMapping;
+export declare function mobileMcpSwipeResponse(mapping: MobileMcpSwipeMapping): string;