@midscene/android 1.9.8 → 1.10.0

package/dist/types/mcp-server.d.ts

@@ -1,298 +0,0 @@
-import { AbstractInterface } from '@midscene/core/device';
-import type { ActionParam } from '@midscene/core';
-import type { ActionReturn } from '@midscene/core';
-import { ADB } from 'appium-adb';
-import { Agent } from '@midscene/core/agent';
-import { AgentBehaviorInitArgs } from '@midscene/shared/mcp/agent-behavior-init-args';
-import { AgentOpt } from '@midscene/core/agent';
-import { AndroidDeviceInputOpt } from '@midscene/core/device';
-import { AndroidDeviceOpt } from '@midscene/core/device';
-import { BaseMCPServer } from '@midscene/shared/mcp';
-import { BaseMidsceneTools } from '@midscene/shared/mcp/base-tools';
-import { DeviceAction } from '@midscene/core';
-import type { ElementInfo } from '@midscene/shared/extractor';
-import { InitArgSpec } from '@midscene/shared/mcp/base-tools';
-import { InterfaceType } from '@midscene/core';
-import { LaunchMCPServerOptions } from '@midscene/shared/mcp';
-import { LaunchMCPServerResult } from '@midscene/shared/mcp';
-import { MobileInputPrimitives } from '@midscene/core/device';
-import { Point } from '@midscene/core';
-import { Size } from '@midscene/core';
-import { Tool } from '@midscene/shared/mcp';
-import type { ToolDefinition } from '@midscene/shared/mcp/types';
-
-declare type ActionArgs<T extends DeviceAction> = [ActionParam<T>] extends [undefined] ? [] : [ActionParam<T>];
-
-declare class AndroidAgent extends Agent<AndroidDevice> {
-    /**
-     * Trigger the system back operation on Android devices
-     */
-    back: WrappedAction<DeviceActionAndroidBackButton>;
-    /**
-     * Trigger the system home operation on Android devices
-     */
-    home: WrappedAction<DeviceActionAndroidHomeButton>;
-    /**
-     * Trigger the system recent apps operation on Android devices
-     */
-    recentApps: WrappedAction<DeviceActionAndroidRecentAppsButton>;
-    /**
-     * User-provided app name to package name mapping
-     */
-    private appNameMapping;
-    constructor(device: AndroidDevice, opts?: AndroidAgentOpt);
-    /**
-     * Launch an Android app or URL
-     * @param uri - App package name, URL, or app name to launch
-     */
-    launch(uri: string): Promise<void>;
-    /**
-     * Terminate (force-stop) an Android app by package name
-     * @param uri - Package name or app name to terminate
-     */
-    terminate(uri: string): Promise<void>;
-    /**
-     * Execute ADB shell command on Android device
-     * @param command - ADB shell command to execute
-     * @param opt - Optional ADB shell execution settings
-     */
-    runAdbShell(command: string, opt?: RunAdbShellOpt): Promise<string>;
-    private createActionWrapper;
-}
-
-declare type AndroidAgentOpt = AgentOpt & {
-    /**
-     * Custom mapping of app names to package names
-     * User-provided mappings will take precedence over default mappings
-     */
-    appNameMapping?: Record<string, string>;
-};
-
-declare class AndroidDevice implements AbstractInterface {
-    private deviceId;
-    private yadbPushed;
-    private devicePixelRatio;
-    private devicePixelRatioInitialized;
-    private adb;
-    private connectingAdb;
-    private destroyed;
-    private description;
-    private customActions?;
-    private cachedScreenSize;
-    private cachedOrientation;
-    private cachedPhysicalDisplayId;
-    private scrcpyAdapter;
-    private appNameMapping;
-    private cachedAdjustScale;
-    private takeScreenshotFailCount;
-    private static readonly TAKE_SCREENSHOT_FAIL_THRESHOLD;
-    private static readonly DEFAULT_MIN_SCREENSHOT_BUFFER_SIZE;
-    interfaceType: InterfaceType;
-    uri: string | undefined;
-    options?: AndroidDeviceOpt;
-    readonly inputPrimitives: MobileInputPrimitives;
-    actionSpace(): DeviceAction<any>[];
-    private performActionScroll;
-    constructor(deviceId: string, options?: AndroidDeviceOpt);
-    describe(): string;
-    connect(): Promise<ADB>;
-    getAdb(): Promise<ADB>;
-    private createAdbProxy;
-    /**
-     * Get or create the scrcpy adapter (lazy initialization)
-     */
-    private getScrcpyAdapter;
-    /**
-     * Get device physical info needed by scrcpy adapter
-     */
-    private getDevicePhysicalInfo;
-    /**
-     * Set the app name to package name mapping
-     */
-    setAppNameMapping(mapping: Record<string, string>): void;
-    /**
-     * Resolve app name to package name using the mapping
-     * Comparison is case-insensitive and ignores spaces, dashes, and underscores.
-     * Keys in appNameMapping are pre-normalized, so we only need to normalize the input.
-     * @param appName The app name to resolve
-     */
-    private resolvePackageName;
-    launch(uri: string): Promise<AndroidDevice>;
-    /**
-     * Terminate (force-stop) an Android app by package name.
-     * Supports app name resolution via setAppNameMapping.
-     * If uri contains "/" (e.g. com.example.app/.MainActivity), only the package part is used.
-     */
-    terminate(uri: string): Promise<void>;
-    execYadb(keyboardContent: string): Promise<void>;
-    getElementsInfo(): Promise<ElementInfo[]>;
-    getElementsNodeTree(): Promise<any>;
-    getScreenSize(): Promise<{
-        override: string;
-        physical: string;
-        orientation: number;
-        isCurrentOrientation?: boolean;
-    }>;
-    private initializeDevicePixelRatio;
-    getDisplayDensity(): Promise<number>;
-    getDisplayOrientation(): Promise<number>;
-    /**
-     * Get physical screen dimensions adjusted for current orientation.
-     * Swaps width/height when the device is in landscape and the reported
-     * dimensions do not already reflect the current orientation.
-     */
-    private getOrientedPhysicalSize;
-    size(): Promise<Size>;
-    /**
-     * Compute and cache the coordinate adjustment scale by comparing
-     * physical dimensions with logical dimensions from size().
-     * Cached after first call; invalidated on destroy().
-     */
-    private getAdjustScale;
-    /**
-     * Convert logical coordinates (from AI) back to physical coordinates (for ADB).
-     * The ratio is derived from size(), so overriding size() alone is sufficient.
-     */
-    private adjustCoordinates;
-    /**
-     * Calculate the end point for scroll operations based on start point, scroll delta, and screen boundaries.
-     * This method ensures that scroll operations stay within screen bounds and maintain a minimum scroll distance
-     * for effective scrolling gestures on Android devices.
-     *
-     * @param start - The starting point of the scroll gesture
-     * @param deltaX - The horizontal scroll distance (positive = scroll right, negative = scroll left)
-     * @param deltaY - The vertical scroll distance (positive = scroll down, negative = scroll up)
-     * @param maxWidth - The maximum width boundary (screen width)
-     * @param maxHeight - The maximum height boundary (screen height)
-     * @returns The calculated end point for the scroll gesture
-     */
-    private calculateScrollEndPoint;
-    private warnScrollDistanceClamped;
-    screenshotBase64(): Promise<string>;
-    clearInput(element?: ElementInfo): Promise<void>;
-    forceScreenshot(path: string): Promise<void>;
-    url(): Promise<string>;
-    scrollUntilTop(startPoint?: Point): Promise<void>;
-    scrollUntilBottom(startPoint?: Point): Promise<void>;
-    scrollUntilLeft(startPoint?: Point): Promise<void>;
-    scrollUntilRight(startPoint?: Point): Promise<void>;
-    scrollUp(distance?: number, startPoint?: Point): Promise<void>;
-    scrollDown(distance?: number, startPoint?: Point): Promise<void>;
-    scrollLeft(distance?: number, startPoint?: Point): Promise<void>;
-    scrollRight(distance?: number, startPoint?: Point): Promise<void>;
-    ensureYadb(): Promise<void>;
-    /**
-     * Check if text contains characters that may cause issues with ADB inputText.
-     * appium-adb's inputText has known bugs with certain characters:
-     * - Backslash causes broken shell quoting
-     * - Backtick is not escaped at all
-     * - Text containing both " and ' throws an error
-     * - Dollar sign can cause variable expansion issues
-     *
-     * For these characters, we route through yadb which handles them correctly
-     * via escapeForShell + double-quoted shell context.
-     */
-    private shouldUseYadbForText;
-    private typeText;
-    private normalizeKeyName;
-    private pressKey;
-    private tapPoint;
-    private doubleTapPoint;
-    mouseMove(): Promise<void>;
-    private dragPoint;
-    private swipePoint;
-    scroll(deltaX: number, deltaY: number, duration?: number, warnOnClamp?: boolean, direction?: ScrollDirection): Promise<void>;
-    destroy(): Promise<void>;
-    /**
-     * Get the current device-local time as a formatted string.
-     * This avoids formatting an Android epoch timestamp in the host machine's
-     * timezone, which can disagree with the device status bar.
-     */
-    getDeviceLocalTimeString(format?: string): Promise<string>;
-    back(): Promise<void>;
-    home(): Promise<void>;
-    recentApps(): Promise<void>;
-    private longPressPoint;
-    pullDown(startPoint?: Point, distance?: number, duration?: number): Promise<void>;
-    pullDrag(from: {
-        x: number;
-        y: number;
-    }, to: {
-        x: number;
-        y: number;
-    }, duration: number): Promise<void>;
-    pullUp(startPoint?: Point, distance?: number, duration?: number): Promise<void>;
-    private getDisplayArg;
-    getPhysicalDisplayId(): Promise<string | null>;
-    hideKeyboard(options?: AndroidDeviceInputOpt, timeoutMs?: number): Promise<boolean>;
-}
-
-declare type AndroidInitArgs = AgentBehaviorInitArgs & {
-    deviceId?: string;
-    useScrcpy?: boolean;
-};
-
-/**
- * Android MCP Server
- * Provides MCP tools for Android automation through ADB
- */
-export declare class AndroidMCPServer extends BaseMCPServer {
-    constructor(toolsManager?: AndroidMidsceneTools);
-    protected createToolsManager(): AndroidMidsceneTools;
-}
-
-/**
- * Android-specific tools manager
- * Extends BaseMidsceneTools to provide Android ADB device connection tools
- */
-declare class AndroidMidsceneTools extends BaseMidsceneTools<AndroidAgent, AndroidInitArgs> {
-    private lastInitArgsSignature?;
-    protected getCliReportSessionName(): string;
-    protected readonly initArgSpec: InitArgSpec<AndroidInitArgs>;
-    protected createTemporaryDevice(): AndroidDevice;
-    protected ensureAgent(initArgs?: AndroidInitArgs): Promise<AndroidAgent>;
-    /**
-     * Provide Android-specific platform tools
-     */
-    protected preparePlatformTools(): ToolDefinition[];
-}
-
-declare type DeviceActionAndroidBackButton = DeviceAction<undefined, void>;
-
-declare type DeviceActionAndroidHomeButton = DeviceAction<undefined, void>;
-
-declare type DeviceActionAndroidRecentAppsButton = DeviceAction<undefined, void>;
-
-/**
- * Create MCP kit for a specific Android Agent
- */
-export declare function mcpKitForAgent(agent: Agent | AndroidAgent): Promise<{
-    description: string;
-    tools: Tool[];
-}>;
-
-/**
- * Create an MCP server launcher for a specific Android Agent
- */
-export declare function mcpServerForAgent(agent: Agent | AndroidAgent): {
-    launch(options?: {
-        verbose?: boolean;
-    }): Promise<LaunchMCPServerResult>;
-    launchHttp(options: LaunchMCPServerOptions): Promise<LaunchMCPServerResult>;
-};
-
-declare type RunAdbShellOpt = {
-    /**
-     * ADB shell command execution timeout in milliseconds.
-     */
-    timeout?: number;
-};
-
-declare type ScrollDirection = 'up' | 'down' | 'left' | 'right';
-
-/**
- * Helper type to convert DeviceAction to wrapped method signature
- */
-declare type WrappedAction<T extends DeviceAction> = (...args: ActionArgs<T>) => Promise<ActionReturn<T>>;
-
-export { }