agent-device 0.12.5 → 0.12.6

package/dist/src/backend.d.ts

@@ -11,12 +11,44 @@ export declare type AgentDeviceBackend = {
     typeText?(context: BackendCommandContext, text: string, options?: {
         delayMs?: number;
     }): Promise<BackendActionResult>;
+    focus?(context: BackendCommandContext, point: Point): Promise<BackendActionResult>;
+    longPress?(context: BackendCommandContext, point: Point, options?: BackendLongPressOptions): Promise<BackendActionResult>;
+    swipe?(context: BackendCommandContext, from: Point, to: Point, options?: BackendSwipeOptions): Promise<BackendActionResult>;
+    scroll?(context: BackendCommandContext, target: BackendScrollTarget, options: BackendScrollOptions): Promise<BackendActionResult>;
+    pinch?(context: BackendCommandContext, options: BackendPinchOptions): Promise<BackendActionResult>;
     pressKey?(context: BackendCommandContext, key: string, options?: {
         modifiers?: string[];
     }): Promise<BackendActionResult>;
-    openApp?(context: BackendCommandContext, target: BackendOpenTarget): Promise<BackendActionResult>;
+    pressBack?(context: BackendCommandContext, options?: BackendBackOptions): Promise<BackendActionResult>;
+    pressHome?(context: BackendCommandContext): Promise<BackendActionResult>;
+    rotate?(context: BackendCommandContext, orientation: BackendDeviceOrientation): Promise<BackendActionResult>;
+    setKeyboard?(context: BackendCommandContext, options: BackendKeyboardOptions): Promise<BackendKeyboardResult | BackendActionResult>;
+    getClipboard?(context: BackendCommandContext): Promise<string | BackendClipboardTextResult>;
+    setClipboard?(context: BackendCommandContext, text: string): Promise<BackendActionResult>;
+    openSettings?(context: BackendCommandContext, target?: string): Promise<BackendActionResult>;
+    handleAlert?(context: BackendCommandContext, action: BackendAlertAction, options?: {
+        timeoutMs?: number;
+    }): Promise<BackendAlertResult>;
+    openAppSwitcher?(context: BackendCommandContext): Promise<BackendActionResult>;
+    openApp?(context: BackendCommandContext, target: BackendOpenTarget, options?: BackendOpenOptions): Promise<BackendActionResult>;
     closeApp?(context: BackendCommandContext, app?: string): Promise<BackendActionResult>;
-    installApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendActionResult>;
+    listApps?(context: BackendCommandContext, filter?: BackendAppListFilter): Promise<readonly BackendAppInfo[]>;
+    getAppState?(context: BackendCommandContext, app: string): Promise<BackendAppState>;
+    pushFile?(context: BackendCommandContext, input: BackendPushInput, target: string): Promise<BackendActionResult>;
+    triggerAppEvent?(context: BackendCommandContext, event: BackendAppEvent): Promise<BackendActionResult>;
+    listDevices?(context: BackendCommandContext, filter?: BackendDeviceFilter): Promise<readonly BackendDeviceInfo[]>;
+    bootDevice?(context: BackendCommandContext, target?: BackendDeviceTarget): Promise<BackendActionResult>;
+    ensureSimulator?(context: BackendCommandContext, options: BackendEnsureSimulatorOptions): Promise<BackendEnsureSimulatorResult>;
+    resolveInstallSource?(context: BackendCommandContext, source: BackendInstallSource): Promise<BackendInstallSource>;
+    installApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendInstallResult>;
+    reinstallApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendInstallResult>;
+    startRecording?(context: BackendCommandContext, options?: BackendRecordingOptions): Promise<BackendRecordingResult>;
+    stopRecording?(context: BackendCommandContext, options?: BackendRecordingOptions): Promise<BackendRecordingResult>;
+    startTrace?(context: BackendCommandContext, options?: BackendTraceOptions): Promise<BackendTraceResult>;
+    stopTrace?(context: BackendCommandContext, options?: BackendTraceOptions): Promise<BackendTraceResult>;
+    readLogs?(context: BackendCommandContext, options?: BackendReadLogsOptions): Promise<BackendReadLogsResult>;
+    dumpNetwork?(context: BackendCommandContext, options?: BackendDumpNetworkOptions): Promise<BackendDumpNetworkResult>;
+    measurePerf?(context: BackendCommandContext, options?: BackendMeasurePerfOptions): Promise<BackendMeasurePerfResult>;
 };
 
 export declare type AgentDeviceBackendPlatform = 'ios' | 'android' | 'macos' | 'linux';
@@ -31,10 +63,65 @@ export declare const BACKEND_CAPABILITY_NAMES: readonly ["android.shell", "ios.r
 
 export declare type BackendActionResult = Record<string, unknown> | void;
 
+export declare type BackendAlertAction = 'get' | 'accept' | 'dismiss' | 'wait';
+
+export declare type BackendAlertInfo = {
+    title?: string;
+    message?: string;
+    buttons?: string[];
+};
+
+export declare type BackendAlertResult = {
+    kind: 'alertStatus';
+    alert: BackendAlertInfo | null;
+} | {
+    kind: 'alertHandled';
+    handled: boolean;
+    alert?: BackendAlertInfo;
+    button?: string;
+} | {
+    kind: 'alertWait';
+    alert: BackendAlertInfo | null;
+    waitedMs?: number;
+    timedOut?: boolean;
+};
+
+export declare type BackendAppEvent = {
+    name: string;
+    payload?: Record<string, unknown>;
+};
+
+export declare type BackendAppInfo = {
+    id: string;
+    name?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
+};
+
+export declare type BackendAppListFilter = 'all' | 'user-installed';
+
+export declare type BackendAppState = {
+    appId?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
+    state?: 'unknown' | 'notRunning' | 'running' | 'foreground' | 'background';
+    details?: Record<string, unknown>;
+};
+
+export declare type BackendBackOptions = {
+    mode?: 'in-app' | 'system';
+};
+
 export declare type BackendCapabilityName = (typeof BACKEND_CAPABILITY_NAMES)[number];
 
 export declare type BackendCapabilitySet = readonly BackendCapabilityName[];
 
+export declare type BackendClipboardTextResult = {
+    text: string;
+};
+
 export declare type BackendCommandContext = {
     session?: string;
     requestId?: string;
@@ -44,6 +131,71 @@ export declare type BackendCommandContext = {
     metadata?: Record<string, unknown>;
 };
 
+export declare type BackendDeviceFilter = {
+    platform?: AgentDeviceBackendPlatform | 'apple';
+    target?: 'mobile' | 'tv' | 'desktop';
+    kind?: 'simulator' | 'emulator' | 'device' | 'desktop';
+};
+
+export declare type BackendDeviceInfo = {
+    id: string;
+    name: string;
+    platform: AgentDeviceBackendPlatform;
+    target?: 'mobile' | 'tv' | 'desktop';
+    kind?: 'simulator' | 'emulator' | 'device' | 'desktop';
+    booted?: boolean;
+    details?: Record<string, unknown>;
+};
+
+export declare type BackendDeviceOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
+
+export declare type BackendDeviceTarget = {
+    id?: string;
+    name?: string;
+    platform?: AgentDeviceBackendPlatform;
+    target?: 'mobile' | 'tv' | 'desktop';
+    headless?: boolean;
+};
+
+export declare type BackendDiagnosticsPageOptions = BackendDiagnosticsTimeWindow & {
+    cursor?: string;
+    limit?: number;
+};
+
+export declare type BackendDiagnosticsTimeWindow = {
+    since?: string;
+    until?: string;
+};
+
+export declare type BackendDumpNetworkOptions = BackendDiagnosticsPageOptions & {
+    include?: BackendNetworkIncludeMode;
+};
+
+export declare type BackendDumpNetworkResult = {
+    entries: readonly BackendNetworkEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
+export declare type BackendEnsureSimulatorOptions = {
+    device: string;
+    runtime?: string;
+    boot?: boolean;
+    reuseExisting?: boolean;
+};
+
+export declare type BackendEnsureSimulatorResult = {
+    udid: string;
+    device: string;
+    runtime: string;
+    created: boolean;
+    booted: boolean;
+    simulatorSetPath?: string | null;
+};
+
 export declare type BackendEscapeHatches = {
     androidShell?(context: BackendCommandContext, args: readonly string[]): Promise<BackendShellResult>;
     iosRunnerCommand?(context: BackendCommandContext, command: BackendRunnerCommand): Promise<BackendActionResult>;
@@ -58,21 +210,166 @@ export declare type BackendFindTextResult = {
     found: boolean;
 };
 
+export declare type BackendInstallResult = Record<string, unknown> & {
+    appId?: string;
+    appName?: string;
+    bundleId?: string;
+    packageName?: string;
+    launchTarget?: string;
+    installablePath?: string;
+    archivePath?: string;
+};
+
+export declare type BackendInstallSource = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'uploadedArtifact';
+    id: string;
+} | {
+    kind: 'url';
+    url: string;
+};
+
 export declare type BackendInstallTarget = {
-    app: string;
-    artifactPath: string;
+    app?: string;
+    source: BackendInstallSource;
+};
+
+export declare type BackendKeyboardOptions = {
+    action: 'status' | 'get' | 'dismiss';
+};
+
+export declare type BackendKeyboardResult = {
+    platform?: 'android' | 'ios' | 'macos' | 'linux';
+    action?: BackendKeyboardOptions['action'];
+    visible?: boolean;
+    inputType?: string | null;
+    type?: string | null;
+    wasVisible?: boolean;
+    dismissed?: boolean;
+    attempts?: number;
+};
+
+export declare type BackendLogEntry = {
+    timestamp?: string;
+    level?: 'debug' | 'info' | 'warn' | 'error' | string;
+    message: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+};
+
+export declare type BackendLongPressOptions = {
+    durationMs?: number;
+};
+
+export declare type BackendMeasurePerfOptions = BackendDiagnosticsTimeWindow & {
+    sampleMs?: number;
+    metrics?: readonly string[];
+};
+
+export declare type BackendMeasurePerfResult = {
+    metrics: readonly BackendPerfMetric[];
+    startedAt?: string;
+    endedAt?: string;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
+export declare type BackendNetworkEntry = {
+    timestamp?: string;
+    method?: string;
+    url?: string;
+    status?: number;
+    durationMs?: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: string;
+    responseBody?: string;
+    metadata?: Record<string, unknown>;
+};
+
+export declare type BackendNetworkIncludeMode = 'summary' | 'headers' | 'body' | 'all';
+
+export declare type BackendOpenOptions = {
+    relaunch?: boolean;
 };
 
 export declare type BackendOpenTarget = {
+    /**
+     * Generic app identifier accepted by the backend. Hosted adapters should
+     * prefer structured appId, bundleId, or packageName when available.
+     */
     app?: string;
+    appId?: string;
+    bundleId?: string;
+    packageName?: string;
+    /**
+     * URL may be used by itself for a deep link or with an app identifier when
+     * the backend supports opening a URL in a specific app context.
+     */
     url?: string;
+    /**
+     * Platform-specific activity override, primarily for Android app launches.
+     */
     activity?: string;
 };
 
+export declare type BackendPerfMetric = {
+    name: string;
+    value?: number;
+    unit?: string;
+    status?: 'ok' | 'unavailable' | 'error';
+    message?: string;
+    metadata?: Record<string, unknown>;
+};
+
+export declare type BackendPinchOptions = {
+    scale: number;
+    center?: Point;
+};
+
+export declare type BackendPushInput = {
+    kind: 'json';
+    payload: Record<string, unknown>;
+} | {
+    kind: 'file';
+    path: string;
+};
+
+export declare type BackendReadLogsOptions = BackendDiagnosticsPageOptions & {
+    levels?: readonly string[];
+    search?: string;
+    source?: string;
+};
+
+export declare type BackendReadLogsResult = {
+    entries: readonly BackendLogEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
 export declare type BackendReadTextResult = {
     text: string;
 };
 
+export declare type BackendRecordingOptions = {
+    outPath?: string;
+    fps?: number;
+    quality?: number;
+    showTouches?: boolean;
+};
+
+export declare type BackendRecordingResult = Record<string, unknown> & {
+    path?: string;
+    telemetryPath?: string;
+    warning?: string;
+};
+
 export declare type BackendRunnerCommand = {
     command: string;
     args?: readonly string[];
@@ -90,6 +387,19 @@ export declare type BackendScreenshotResult = {
     overlayRefs?: ScreenshotOverlayRef[];
 };
 
+export declare type BackendScrollOptions = {
+    direction: 'up' | 'down' | 'left' | 'right';
+    amount?: number;
+    pixels?: number;
+};
+
+export declare type BackendScrollTarget = {
+    kind: 'viewport';
+} | {
+    kind: 'point';
+    point: Point;
+};
+
 export declare type BackendShellResult = {
     exitCode: number;
     stdout: string;
@@ -124,6 +434,10 @@ export declare type BackendSnapshotResult = {
     appBundleId?: string;
 };
 
+export declare type BackendSwipeOptions = {
+    durationMs?: number;
+};
+
 export declare type BackendTapOptions = {
     button?: 'primary' | 'secondary' | 'middle';
     count?: number;
@@ -133,6 +447,14 @@ export declare type BackendTapOptions = {
     doubleTap?: boolean;
 };
 
+export declare type BackendTraceOptions = {
+    outPath?: string;
+};
+
+export declare type BackendTraceResult = Record<string, unknown> & {
+    outPath?: string;
+};
+
 export declare function hasBackendCapability(backend: Pick<AgentDeviceBackend, 'platform' | 'capabilities'>, capability: BackendCapabilityName): boolean;
 
 export declare function hasBackendEscapeHatch(backend: Pick<AgentDeviceBackend, 'escapeHatches'>, capability: BackendCapabilityName): boolean;