agent-device 0.12.5 → 0.12.7

package/dist/src/commands/index.d.ts

@@ -1,3 +1,56 @@
+export declare type AdminBootCommandOptions = CommandContext & {
+    target?: BackendDeviceTarget;
+};
+
+export declare type AdminBootCommandResult = {
+    kind: 'deviceBooted';
+    target?: BackendDeviceTarget;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type AdminDevicesCommandOptions = CommandContext & {
+    filter?: BackendDeviceFilter;
+};
+
+export declare type AdminDevicesCommandResult = {
+    kind: 'adminDevices';
+    devices: readonly BackendDeviceInfo[];
+};
+
+export declare type AdminEnsureSimulatorCommandOptions = CommandContext & BackendEnsureSimulatorOptions;
+
+export declare type AdminEnsureSimulatorCommandResult = {
+    kind: 'simulatorEnsured';
+} & BackendEnsureSimulatorResult;
+
+export declare type AdminInstallCommandOptions = CommandContext & {
+    app: string;
+    source: BackendInstallSource;
+};
+
+export declare type AdminInstallCommandResult = {
+    kind: 'appInstalled' | 'appReinstalled' | 'appInstalledFromSource';
+    app?: string;
+    source: BackendInstallSource;
+    appId?: string;
+    appName?: string;
+    bundleId?: string;
+    packageName?: string;
+    launchTarget?: string;
+    installablePath?: string;
+    archivePath?: string;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type AdminInstallFromSourceCommandOptions = CommandContext & {
+    app?: string;
+    source: BackendInstallSource;
+};
+
+export declare type AdminReinstallCommandOptions = AdminInstallCommandOptions;
+
 declare type AgentDeviceBackend = {
     platform: AgentDeviceBackendPlatform;
     capabilities?: BackendCapabilitySet;
@@ -11,12 +64,44 @@ 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>;
 };
 
 declare type AgentDeviceBackendPlatform = 'ios' | 'android' | 'macos' | 'linux';
@@ -50,6 +135,46 @@ export declare type AgentDeviceCommands = {
         press: RuntimeCommand<PressCommandOptions, PressCommandResult>;
         fill: RuntimeCommand<FillCommandOptions, FillCommandResult>;
         typeText: RuntimeCommand<TypeTextCommandOptions, TypeTextCommandResult>;
+        focus: RuntimeCommand<FocusCommandOptions, FocusCommandResult>;
+        longPress: RuntimeCommand<LongPressCommandOptions, LongPressCommandResult>;
+        swipe: RuntimeCommand<SwipeCommandOptions, SwipeCommandResult>;
+        scroll: RuntimeCommand<ScrollCommandOptions, ScrollCommandResult>;
+        pinch: RuntimeCommand<PinchCommandOptions, PinchCommandResult>;
+    };
+    system: {
+        back: RuntimeCommand<SystemBackCommandOptions | undefined, SystemBackCommandResult>;
+        home: RuntimeCommand<SystemHomeCommandOptions | undefined, SystemHomeCommandResult>;
+        rotate: RuntimeCommand<SystemRotateCommandOptions, SystemRotateCommandResult>;
+        keyboard: RuntimeCommand<SystemKeyboardCommandOptions | undefined, SystemKeyboardCommandResult>;
+        clipboard: RuntimeCommand<SystemClipboardCommandOptions, SystemClipboardCommandResult>;
+        settings: RuntimeCommand<SystemSettingsCommandOptions | undefined, SystemSettingsCommandResult>;
+        alert: RuntimeCommand<SystemAlertCommandOptions | undefined, SystemAlertCommandResult>;
+        appSwitcher: RuntimeCommand<SystemAppSwitcherCommandOptions | undefined, SystemAppSwitcherCommandResult>;
+    };
+    apps: {
+        open: RuntimeCommand<OpenAppCommandOptions, OpenAppCommandResult>;
+        close: RuntimeCommand<CloseAppCommandOptions | undefined, CloseAppCommandResult>;
+        list: RuntimeCommand<ListAppsCommandOptions | undefined, ListAppsCommandResult>;
+        state: RuntimeCommand<GetAppStateCommandOptions, GetAppStateCommandResult>;
+        push: RuntimeCommand<PushAppCommandOptions, PushAppCommandResult>;
+        triggerEvent: RuntimeCommand<TriggerAppEventCommandOptions, TriggerAppEventCommandResult>;
+    };
+    admin: {
+        devices: RuntimeCommand<AdminDevicesCommandOptions | undefined, AdminDevicesCommandResult>;
+        boot: RuntimeCommand<AdminBootCommandOptions | undefined, AdminBootCommandResult>;
+        ensureSimulator: RuntimeCommand<AdminEnsureSimulatorCommandOptions, AdminEnsureSimulatorCommandResult>;
+        install: RuntimeCommand<AdminInstallCommandOptions, AdminInstallCommandResult>;
+        reinstall: RuntimeCommand<AdminReinstallCommandOptions, AdminInstallCommandResult>;
+        installFromSource: RuntimeCommand<AdminInstallFromSourceCommandOptions, AdminInstallCommandResult>;
+    };
+    recording: {
+        record: RuntimeCommand<RecordingRecordCommandOptions, RecordingRecordCommandResult>;
+        trace: RuntimeCommand<RecordingTraceCommandOptions, RecordingTraceCommandResult>;
+    };
+    diagnostics: {
+        logs: RuntimeCommand<DiagnosticsLogsCommandOptions | undefined, DiagnosticsLogsCommandResult>;
+        network: RuntimeCommand<DiagnosticsNetworkCommandOptions | undefined, DiagnosticsNetworkCommandResult>;
+        perf: RuntimeCommand<DiagnosticsPerfCommandOptions | undefined, DiagnosticsPerfCommandResult>;
     };
 };
 
@@ -63,6 +188,11 @@ declare type AgentDeviceRuntime = {
     signal?: AbortSignal;
 };
 
+export declare type AppPushInput = {
+    kind: 'json';
+    payload: Record<string, unknown>;
+} | FileInputRef;
+
 declare type ArtifactAdapter = {
     resolveInput(ref: FileInputRef, options: ResolveInputOptions): Promise<ResolvedInputFile>;
     reserveOutput(ref: FileOutputRef | undefined, options: ReserveOutputOptions): Promise<ReservedOutputFile>;
@@ -89,10 +219,65 @@ declare const BACKEND_CAPABILITY_NAMES: readonly ["android.shell", "ios.runnerCo
 
 declare type BackendActionResult = Record<string, unknown> | void;
 
+declare type BackendAlertAction = 'get' | 'accept' | 'dismiss' | 'wait';
+
+declare type BackendAlertInfo = {
+    title?: string;
+    message?: string;
+    buttons?: string[];
+};
+
+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;
+};
+
+declare type BackendAppEvent = {
+    name: string;
+    payload?: Record<string, unknown>;
+};
+
+declare type BackendAppInfo = {
+    id: string;
+    name?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
+};
+
+declare type BackendAppListFilter = 'all' | 'user-installed';
+
+declare type BackendAppState = {
+    appId?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
+    state?: 'unknown' | 'notRunning' | 'running' | 'foreground' | 'background';
+    details?: Record<string, unknown>;
+};
+
+declare type BackendBackOptions = {
+    mode?: 'in-app' | 'system';
+};
+
 declare type BackendCapabilityName = (typeof BACKEND_CAPABILITY_NAMES)[number];
 
 declare type BackendCapabilitySet = readonly BackendCapabilityName[];
 
+declare type BackendClipboardTextResult = {
+    text: string;
+};
+
 declare type BackendCommandContext = {
     session?: string;
     requestId?: string;
@@ -102,6 +287,71 @@ declare type BackendCommandContext = {
     metadata?: Record<string, unknown>;
 };
 
+declare type BackendDeviceFilter = {
+    platform?: AgentDeviceBackendPlatform | 'apple';
+    target?: 'mobile' | 'tv' | 'desktop';
+    kind?: 'simulator' | 'emulator' | 'device' | 'desktop';
+};
+
+declare type BackendDeviceInfo = {
+    id: string;
+    name: string;
+    platform: AgentDeviceBackendPlatform;
+    target?: 'mobile' | 'tv' | 'desktop';
+    kind?: 'simulator' | 'emulator' | 'device' | 'desktop';
+    booted?: boolean;
+    details?: Record<string, unknown>;
+};
+
+declare type BackendDeviceOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
+
+declare type BackendDeviceTarget = {
+    id?: string;
+    name?: string;
+    platform?: AgentDeviceBackendPlatform;
+    target?: 'mobile' | 'tv' | 'desktop';
+    headless?: boolean;
+};
+
+declare type BackendDiagnosticsPageOptions = BackendDiagnosticsTimeWindow & {
+    cursor?: string;
+    limit?: number;
+};
+
+declare type BackendDiagnosticsTimeWindow = {
+    since?: string;
+    until?: string;
+};
+
+declare type BackendDumpNetworkOptions = BackendDiagnosticsPageOptions & {
+    include?: BackendNetworkIncludeMode;
+};
+
+declare type BackendDumpNetworkResult = {
+    entries: readonly BackendNetworkEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
+declare type BackendEnsureSimulatorOptions = {
+    device: string;
+    runtime?: string;
+    boot?: boolean;
+    reuseExisting?: boolean;
+};
+
+declare type BackendEnsureSimulatorResult = {
+    udid: string;
+    device: string;
+    runtime: string;
+    created: boolean;
+    booted: boolean;
+    simulatorSetPath?: string | null;
+};
+
 declare type BackendEscapeHatches = {
     androidShell?(context: BackendCommandContext, args: readonly string[]): Promise<BackendShellResult>;
     iosRunnerCommand?(context: BackendCommandContext, command: BackendRunnerCommand): Promise<BackendActionResult>;
@@ -116,21 +366,166 @@ declare type BackendFindTextResult = {
     found: boolean;
 };
 
+declare type BackendInstallResult = Record<string, unknown> & {
+    appId?: string;
+    appName?: string;
+    bundleId?: string;
+    packageName?: string;
+    launchTarget?: string;
+    installablePath?: string;
+    archivePath?: string;
+};
+
+declare type BackendInstallSource = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'uploadedArtifact';
+    id: string;
+} | {
+    kind: 'url';
+    url: string;
+};
+
 declare type BackendInstallTarget = {
-    app: string;
-    artifactPath: string;
+    app?: string;
+    source: BackendInstallSource;
+};
+
+declare type BackendKeyboardOptions = {
+    action: 'status' | 'get' | 'dismiss';
+};
+
+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;
+};
+
+declare type BackendLogEntry = {
+    timestamp?: string;
+    level?: 'debug' | 'info' | 'warn' | 'error' | string;
+    message: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+};
+
+declare type BackendLongPressOptions = {
+    durationMs?: number;
+};
+
+declare type BackendMeasurePerfOptions = BackendDiagnosticsTimeWindow & {
+    sampleMs?: number;
+    metrics?: readonly string[];
+};
+
+declare type BackendMeasurePerfResult = {
+    metrics: readonly BackendPerfMetric[];
+    startedAt?: string;
+    endedAt?: string;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
+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>;
+};
+
+declare type BackendNetworkIncludeMode = 'summary' | 'headers' | 'body' | 'all';
+
+declare type BackendOpenOptions = {
+    relaunch?: boolean;
 };
 
 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;
 };
 
+declare type BackendPerfMetric = {
+    name: string;
+    value?: number;
+    unit?: string;
+    status?: 'ok' | 'unavailable' | 'error';
+    message?: string;
+    metadata?: Record<string, unknown>;
+};
+
+declare type BackendPinchOptions = {
+    scale: number;
+    center?: Point;
+};
+
+declare type BackendPushInput = {
+    kind: 'json';
+    payload: Record<string, unknown>;
+} | {
+    kind: 'file';
+    path: string;
+};
+
+declare type BackendReadLogsOptions = BackendDiagnosticsPageOptions & {
+    levels?: readonly string[];
+    search?: string;
+    source?: string;
+};
+
+declare type BackendReadLogsResult = {
+    entries: readonly BackendLogEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
 declare type BackendReadTextResult = {
     text: string;
 };
 
+declare type BackendRecordingOptions = {
+    outPath?: string;
+    fps?: number;
+    quality?: number;
+    showTouches?: boolean;
+};
+
+declare type BackendRecordingResult = Record<string, unknown> & {
+    path?: string;
+    telemetryPath?: string;
+    warning?: string;
+};
+
 declare type BackendRunnerCommand = {
     command: string;
     args?: readonly string[];
@@ -148,6 +543,19 @@ declare type BackendScreenshotResult = {
     overlayRefs?: ScreenshotOverlayRef[];
 };
 
+declare type BackendScrollOptions = {
+    direction: 'up' | 'down' | 'left' | 'right';
+    amount?: number;
+    pixels?: number;
+};
+
+declare type BackendScrollTarget = {
+    kind: 'viewport';
+} | {
+    kind: 'point';
+    point: Point;
+};
+
 declare type BackendShellResult = {
     exitCode: number;
     stdout: string;
@@ -182,6 +590,10 @@ declare type BackendSnapshotResult = {
     appBundleId?: string;
 };
 
+declare type BackendSwipeOptions = {
+    durationMs?: number;
+};
+
 declare type BackendTapOptions = {
     button?: 'primary' | 'secondary' | 'middle';
     count?: number;
@@ -191,6 +603,43 @@ declare type BackendTapOptions = {
     doubleTap?: boolean;
 };
 
+declare type BackendTraceOptions = {
+    outPath?: string;
+};
+
+declare type BackendTraceResult = Record<string, unknown> & {
+    outPath?: string;
+};
+
+export declare type BatchCommandOptions<TContext = unknown> = CommandContext & {
+    steps: readonly CommandRouterRequest<TContext>[];
+    stopOnError?: boolean;
+    maxSteps?: number;
+};
+
+export declare type BatchCommandResult = {
+    kind: 'batch';
+    total: number;
+    executed: number;
+    failed: number;
+    totalDurationMs: number;
+    results: readonly BatchCommandStepResult[];
+};
+
+export declare type BatchCommandStepResult = {
+    step: number;
+    command: string;
+    ok: true;
+    data: CommandRouterResult;
+    durationMs: number;
+} | {
+    step: number;
+    command: string;
+    ok: false;
+    error: NormalizedError;
+    durationMs: number;
+};
+
 export declare function bindCommands(runtime: AgentDeviceRuntime): BoundAgentDeviceCommands;
 
 export declare type BoundAgentDeviceCommands = {
@@ -222,6 +671,46 @@ export declare type BoundAgentDeviceCommands = {
         press: (target: InteractionTarget, options?: Omit<PressCommandOptions, 'target'>) => Promise<PressCommandResult>;
         fill: (target: InteractionTarget, text: string, options?: Omit<FillCommandOptions, 'target' | 'text'>) => Promise<FillCommandResult>;
         typeText: (text: string, options?: Omit<TypeTextCommandOptions, 'text'>) => Promise<TypeTextCommandResult>;
+        focus: (target: InteractionTarget, options?: Omit<FocusCommandOptions, 'target'>) => Promise<FocusCommandResult>;
+        longPress: (target: InteractionTarget, options?: Omit<LongPressCommandOptions, 'target'>) => Promise<LongPressCommandResult>;
+        swipe: BoundRuntimeCommand<SwipeCommandOptions, SwipeCommandResult>;
+        scroll: BoundRuntimeCommand<ScrollCommandOptions, ScrollCommandResult>;
+        pinch: BoundRuntimeCommand<PinchCommandOptions, PinchCommandResult>;
+    };
+    system: {
+        back: (options?: SystemBackCommandOptions) => Promise<SystemBackCommandResult>;
+        home: (options?: SystemHomeCommandOptions) => Promise<SystemHomeCommandResult>;
+        rotate: BoundRuntimeCommand<SystemRotateCommandOptions, SystemRotateCommandResult>;
+        keyboard: (options?: SystemKeyboardCommandOptions) => Promise<SystemKeyboardCommandResult>;
+        clipboard: BoundRuntimeCommand<SystemClipboardCommandOptions, SystemClipboardCommandResult>;
+        settings: (options?: SystemSettingsCommandOptions) => Promise<SystemSettingsCommandResult>;
+        alert: (options?: SystemAlertCommandOptions) => Promise<SystemAlertCommandResult>;
+        appSwitcher: (options?: SystemAppSwitcherCommandOptions) => Promise<SystemAppSwitcherCommandResult>;
+    };
+    apps: {
+        open: BoundRuntimeCommand<OpenAppCommandOptions, OpenAppCommandResult>;
+        close: (options?: CloseAppCommandOptions) => Promise<CloseAppCommandResult>;
+        list: (options?: ListAppsCommandOptions) => Promise<ListAppsCommandResult>;
+        state: BoundRuntimeCommand<GetAppStateCommandOptions, GetAppStateCommandResult>;
+        push: BoundRuntimeCommand<PushAppCommandOptions, PushAppCommandResult>;
+        triggerEvent: BoundRuntimeCommand<TriggerAppEventCommandOptions, TriggerAppEventCommandResult>;
+    };
+    admin: {
+        devices: (options?: AdminDevicesCommandOptions) => Promise<AdminDevicesCommandResult>;
+        boot: (options?: AdminBootCommandOptions) => Promise<AdminBootCommandResult>;
+        ensureSimulator: BoundRuntimeCommand<AdminEnsureSimulatorCommandOptions, AdminEnsureSimulatorCommandResult>;
+        install: BoundRuntimeCommand<AdminInstallCommandOptions, AdminInstallCommandResult>;
+        reinstall: BoundRuntimeCommand<AdminReinstallCommandOptions, AdminInstallCommandResult>;
+        installFromSource: BoundRuntimeCommand<AdminInstallFromSourceCommandOptions, AdminInstallCommandResult>;
+    };
+    recording: {
+        record: BoundRuntimeCommand<RecordingRecordCommandOptions, RecordingRecordCommandResult>;
+        trace: BoundRuntimeCommand<RecordingTraceCommandOptions, RecordingTraceCommandResult>;
+    };
+    observability: {
+        logs: (options?: DiagnosticsLogsCommandOptions) => Promise<DiagnosticsLogsCommandResult>;
+        network: (options?: DiagnosticsNetworkCommandOptions) => Promise<DiagnosticsNetworkCommandResult>;
+        perf: (options?: DiagnosticsPerfCommandOptions) => Promise<DiagnosticsPerfCommandResult>;
     };
 };
 
@@ -229,9 +718,24 @@ export declare type BoundRuntimeCommand<TOptions = Record<string, unknown>, TRes
 
 export declare type ClickCommandOptions = PressCommandOptions;
 
+export declare type CloseAppCommandOptions = CommandContext & {
+    app?: string;
+};
+
+export declare type CloseAppCommandResult = {
+    kind: 'appClosed';
+    app?: string;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 export declare const commandCatalog: readonly CommandCatalogEntry[];
 
 export declare type CommandCatalogEntry = {
+    /**
+     * CLI command names track daemon compatibility migration. Namespaced entries
+     * track runtime router/API commands that are available independently.
+     */
     command: string;
     category: 'portable-runtime' | 'backend-admin' | 'transport-session' | 'environment' | 'capability-gated';
     status: 'implemented' | 'planned';
@@ -316,6 +820,130 @@ export declare type CommandRouterRequest<TContext = unknown> = {
     command: 'interactions.typeText';
     options: TypeTextCommandOptions;
     context?: TContext;
+} | {
+    command: 'interactions.focus';
+    options: FocusCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.longPress';
+    options: LongPressCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.swipe';
+    options: SwipeCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.scroll';
+    options: ScrollCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.pinch';
+    options: PinchCommandOptions;
+    context?: TContext;
+} | {
+    command: 'system.back';
+    options?: SystemBackCommandOptions;
+    context?: TContext;
+} | {
+    command: 'system.home';
+    options?: SystemHomeCommandOptions;
+    context?: TContext;
+} | {
+    command: 'system.rotate';
+    options: SystemRotateCommandOptions;
+    context?: TContext;
+} | {
+    command: 'system.keyboard';
+    options?: SystemKeyboardCommandOptions;
+    context?: TContext;
+} | {
+    command: 'system.clipboard';
+    options: SystemClipboardCommandOptions;
+    context?: TContext;
+} | {
+    command: 'system.settings';
+    options?: SystemSettingsCommandOptions;
+    context?: TContext;
+} | {
+    command: 'system.alert';
+    options?: SystemAlertCommandOptions;
+    context?: TContext;
+} | {
+    command: 'system.appSwitcher';
+    options?: SystemAppSwitcherCommandOptions;
+    context?: TContext;
+} | {
+    command: 'apps.open';
+    options: OpenAppCommandOptions;
+    context?: TContext;
+} | {
+    command: 'apps.close';
+    options?: CloseAppCommandOptions;
+    context?: TContext;
+} | {
+    command: 'apps.list';
+    options?: ListAppsCommandOptions;
+    context?: TContext;
+} | {
+    command: 'apps.state';
+    options: GetAppStateCommandOptions;
+    context?: TContext;
+} | {
+    command: 'apps.push';
+    options: PushAppCommandOptions;
+    context?: TContext;
+} | {
+    command: 'apps.triggerEvent';
+    options: TriggerAppEventCommandOptions;
+    context?: TContext;
+} | {
+    command: 'admin.devices';
+    options?: AdminDevicesCommandOptions;
+    context?: TContext;
+} | {
+    command: 'admin.boot';
+    options?: AdminBootCommandOptions;
+    context?: TContext;
+} | {
+    command: 'admin.ensureSimulator';
+    options: AdminEnsureSimulatorCommandOptions;
+    context?: TContext;
+} | {
+    command: 'admin.install';
+    options: AdminInstallCommandOptions;
+    context?: TContext;
+} | {
+    command: 'admin.reinstall';
+    options: AdminReinstallCommandOptions;
+    context?: TContext;
+} | {
+    command: 'admin.installFromSource';
+    options: AdminInstallFromSourceCommandOptions;
+    context?: TContext;
+} | {
+    command: 'record';
+    options: RecordingRecordCommandOptions;
+    context?: TContext;
+} | {
+    command: 'trace';
+    options: RecordingTraceCommandOptions;
+    context?: TContext;
+} | {
+    command: 'diagnostics.logs';
+    options?: DiagnosticsLogsCommandOptions;
+    context?: TContext;
+} | {
+    command: 'diagnostics.network';
+    options?: DiagnosticsNetworkCommandOptions;
+    context?: TContext;
+} | {
+    command: 'diagnostics.perf';
+    options?: DiagnosticsPerfCommandOptions;
+    context?: TContext;
+} | {
+    command: 'batch';
+    options: BatchCommandOptions<TContext>;
+    context?: TContext;
 };
 
 export declare type CommandRouterResponse = {
@@ -326,7 +954,7 @@ export declare type CommandRouterResponse = {
     error: NormalizedError;
 };
 
-export declare type CommandRouterResult = ScreenshotCommandResult | DiffScreenshotCommandResult | SnapshotCommandResult | DiffSnapshotCommandResult | FindReadCommandResult | GetCommandResult | IsCommandResult | WaitCommandResult | PressCommandResult | FillCommandResult | TypeTextCommandResult;
+export declare type CommandRouterResult = ScreenshotCommandResult | DiffScreenshotCommandResult | SnapshotCommandResult | DiffSnapshotCommandResult | FindReadCommandResult | GetCommandResult | IsCommandResult | WaitCommandResult | PressCommandResult | FillCommandResult | TypeTextCommandResult | FocusCommandResult | LongPressCommandResult | SwipeCommandResult | ScrollCommandResult | PinchCommandResult | SystemBackCommandResult | SystemHomeCommandResult | SystemRotateCommandResult | SystemKeyboardCommandResult | SystemClipboardCommandResult | SystemSettingsCommandResult | SystemAlertCommandResult | SystemAppSwitcherCommandResult | OpenAppCommandResult | CloseAppCommandResult | ListAppsCommandResult | GetAppStateCommandResult | PushAppCommandResult | TriggerAppEventCommandResult | AdminDevicesCommandResult | AdminBootCommandResult | AdminEnsureSimulatorCommandResult | AdminInstallCommandResult | RecordingRecordCommandResult | RecordingTraceCommandResult | DiagnosticsLogsCommandResult | DiagnosticsNetworkCommandResult | DiagnosticsPerfCommandResult | BatchCommandResult;
 
 export declare const commands: AgentDeviceCommands;
 
@@ -354,6 +982,64 @@ declare type CreateTempFileOptions = {
     ext: string;
 };
 
+export declare type DiagnosticsLogsCommandOptions = DiagnosticsPageOptions & {
+    levels?: readonly string[];
+    search?: string;
+    source?: string;
+};
+
+export declare type DiagnosticsLogsCommandResult = {
+    kind: 'diagnosticsLogs';
+    entries: readonly BackendLogEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted: boolean;
+    notes?: readonly string[];
+};
+
+export declare type DiagnosticsNetworkCommandOptions = DiagnosticsPageOptions & {
+    include?: BackendNetworkIncludeMode;
+};
+
+export declare type DiagnosticsNetworkCommandResult = {
+    kind: 'diagnosticsNetwork';
+    entries: readonly BackendNetworkEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted: boolean;
+    notes?: readonly string[];
+};
+
+declare type DiagnosticsPageOptions = CommandContext & {
+    appId?: string;
+    appBundleId?: string;
+    since?: string;
+    until?: string;
+    cursor?: string;
+    limit?: number;
+};
+
+export declare type DiagnosticsPerfCommandOptions = CommandContext & {
+    appId?: string;
+    appBundleId?: string;
+    since?: string;
+    until?: string;
+    sampleMs?: number;
+    metrics?: readonly string[];
+};
+
+export declare type DiagnosticsPerfCommandResult = {
+    kind: 'diagnosticsPerf';
+    metrics: readonly BackendPerfMetric[];
+    startedAt?: string;
+    endedAt?: string;
+    backend?: string;
+    redacted: boolean;
+    notes?: readonly string[];
+};
+
 declare type DiagnosticsSink = {
     emit(event: {
         level: 'debug' | 'info' | 'warn' | 'error';
@@ -462,6 +1148,27 @@ export declare type FindReadCommandResult = {
     node: SnapshotNode;
 };
 
+export declare type FocusCommandOptions = CommandContext & {
+    target: InteractionTarget;
+};
+
+export declare type FocusCommandResult = ResolvedInteractionTarget & {
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type GestureDirection = 'up' | 'down' | 'left' | 'right';
+
+export declare type GetAppStateCommandOptions = CommandContext & {
+    app: string;
+};
+
+export declare type GetAppStateCommandResult = {
+    kind: 'appState';
+    app: string;
+    state: BackendAppState;
+};
+
 export declare type GetAttrsCommandOptions = CommandContext & SelectorSnapshotOptions & {
     target: ElementTarget;
 };
@@ -509,10 +1216,30 @@ export declare type IsSelectorCommandOptions = CommandContext & SelectorSnapshot
     target: SelectorTarget;
 };
 
+export declare type ListAppsCommandOptions = CommandContext & {
+    filter?: BackendAppListFilter;
+};
+
+export declare type ListAppsCommandResult = {
+    kind: 'appsList';
+    apps: readonly BackendAppInfo[];
+};
+
 export declare type LiveScreenshotInputRef = {
     kind: 'live';
 };
 
+export declare type LongPressCommandOptions = CommandContext & {
+    target: InteractionTarget;
+    durationMs?: number;
+};
+
+export declare type LongPressCommandResult = ResolvedInteractionTarget & {
+    durationMs?: number;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 declare type NormalizedError = {
     code: string;
     message: string;
@@ -522,8 +1249,34 @@ declare type NormalizedError = {
     details?: Record<string, unknown>;
 };
 
+export declare type OpenAppCommandOptions = CommandContext & BackendOpenTarget & {
+    relaunch?: boolean;
+};
+
+export declare type OpenAppCommandResult = {
+    kind: 'appOpened';
+    target: BackendOpenTarget;
+    relaunch: boolean;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 declare type OutputVisibility = 'client-visible' | 'internal';
 
+export declare type PinchCommandOptions = CommandContext & {
+    scale: number;
+    center?: InteractionTarget;
+};
+
+export declare type PinchCommandResult = {
+    kind: 'pinch';
+    scale: number;
+    center?: Point;
+    centerTarget?: ResolvedInteractionTarget;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 declare type Point = {
     x: number;
     y: number;
@@ -549,6 +1302,19 @@ export declare type PressCommandResult = ResolvedInteractionTarget & {
     backendResult?: Record<string, unknown>;
 };
 
+export declare type PushAppCommandOptions = CommandContext & {
+    app: string;
+    input: AppPushInput;
+};
+
+export declare type PushAppCommandResult = {
+    kind: 'appPushed';
+    app: string;
+    inputKind: 'json' | 'file';
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 declare type RawSnapshotNode = {
     index: number;
     type?: string;
@@ -572,6 +1338,39 @@ declare type RawSnapshotNode = {
     hiddenContentBelow?: boolean;
 };
 
+export declare type RecordingRecordCommandOptions = CommandContext & {
+    action: 'start' | 'stop';
+    out?: FileOutputRef;
+    fps?: number;
+    quality?: number;
+    hideTouches?: boolean;
+};
+
+export declare type RecordingRecordCommandResult = {
+    kind: 'recordingStarted' | 'recordingStopped';
+    action: 'start' | 'stop';
+    path?: string;
+    telemetryPath?: string;
+    artifact?: ArtifactDescriptor;
+    backendResult?: Record<string, unknown>;
+    warning?: string;
+    message?: string;
+};
+
+export declare type RecordingTraceCommandOptions = CommandContext & {
+    action: 'start' | 'stop';
+    out?: FileOutputRef;
+};
+
+export declare type RecordingTraceCommandResult = {
+    kind: 'traceStarted' | 'traceStopped';
+    action: 'start' | 'stop';
+    outPath?: string;
+    artifact?: ArtifactDescriptor;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 declare type Rect = {
     x: number;
     y: number;
@@ -608,7 +1407,7 @@ declare type ResolvedInputFile = {
     cleanup?: () => Promise<void>;
 };
 
-declare type ResolvedInteractionTarget = {
+export declare type ResolvedInteractionTarget = {
     kind: 'point';
     point: Point;
 } | {
@@ -777,6 +1576,32 @@ declare type ScreenshotOverlayRef = {
     center: Point;
 };
 
+export declare type ScrollCommandOptions = CommandContext & {
+    target?: ScrollTarget;
+    direction: GestureDirection;
+    amount?: number;
+    pixels?: number;
+};
+
+export declare type ScrollCommandResult = {
+    kind: 'viewport';
+    direction: GestureDirection;
+    amount?: number;
+    pixels?: number;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+} | (ResolvedInteractionTarget & {
+    direction: GestureDirection;
+    amount?: number;
+    pixels?: number;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+});
+
+export declare type ScrollTarget = InteractionTarget | {
+    kind: 'viewport';
+};
+
 export declare function selector(expression: string): SelectorTarget;
 
 export declare type SelectorSnapshotOptions = {
@@ -849,12 +1674,159 @@ declare type SnapshotVisibility = {
 
 declare type SnapshotVisibilityReason = 'offscreen-nodes' | 'scroll-hidden-above' | 'scroll-hidden-below';
 
+export declare type SwipeCommandOptions = CommandContext & SwipeOptions;
+
+export declare type SwipeCommandResult = {
+    kind: 'swipe';
+    from: Point;
+    to: Point;
+    direction?: GestureDirection;
+    distance?: number;
+    durationMs?: number;
+    fromTarget?: ResolvedInteractionTarget | {
+        kind: 'viewport';
+    };
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type SwipeOptions = {
+    from?: Point | InteractionTarget;
+    to?: Point;
+    direction?: GestureDirection;
+    distance?: number;
+    durationMs?: number;
+};
+
+export declare type SystemAlertCommandOptions = CommandContext & {
+    action?: BackendAlertAction;
+    timeoutMs?: number;
+};
+
+export declare type SystemAlertCommandResult = {
+    kind: 'alertStatus';
+    action: 'get';
+    alert: BackendAlertInfo | null;
+} | {
+    kind: 'alertHandled';
+    action: 'accept' | 'dismiss';
+    handled: boolean;
+    alert?: BackendAlertInfo;
+    button?: string;
+    message?: string;
+} | {
+    kind: 'alertWait';
+    action: 'wait';
+    alert: BackendAlertInfo | null;
+    waitedMs?: number;
+    timedOut?: boolean;
+    message?: string;
+};
+
+export declare type SystemAppSwitcherCommandOptions = CommandContext;
+
+export declare type SystemAppSwitcherCommandResult = {
+    kind: 'appSwitcherOpened';
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type SystemBackCommandOptions = CommandContext & {
+    mode?: 'in-app' | 'system';
+};
+
+export declare type SystemBackCommandResult = {
+    kind: 'systemBack';
+    mode: 'in-app' | 'system';
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type SystemClipboardCommandOptions = (CommandContext & {
+    action: 'read';
+}) | (CommandContext & {
+    action: 'write';
+    text: string;
+});
+
+export declare type SystemClipboardCommandResult = {
+    kind: 'clipboardText';
+    action: 'read';
+    text: string;
+} | {
+    kind: 'clipboardUpdated';
+    action: 'write';
+    textLength: number;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type SystemHomeCommandOptions = CommandContext;
+
+export declare type SystemHomeCommandResult = {
+    kind: 'systemHome';
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type SystemKeyboardCommandOptions = CommandContext & {
+    action?: 'status' | 'get' | 'dismiss';
+};
+
+export declare type SystemKeyboardCommandResult = {
+    kind: 'keyboardState';
+    action: 'status' | 'get';
+    state: BackendKeyboardResult;
+    backendResult?: Record<string, unknown>;
+} | {
+    kind: 'keyboardDismissed';
+    action: 'dismiss';
+    state: BackendKeyboardResult;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type SystemRotateCommandOptions = CommandContext & {
+    orientation: BackendDeviceOrientation;
+};
+
+export declare type SystemRotateCommandResult = {
+    kind: 'systemRotated';
+    orientation: BackendDeviceOrientation;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type SystemSettingsCommandOptions = CommandContext & {
+    target?: string;
+};
+
+export declare type SystemSettingsCommandResult = {
+    kind: 'settingsOpened';
+    target?: string;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 declare type TemporaryFile = {
     path: string;
     visibility: 'internal';
     cleanup: () => Promise<void>;
 };
 
+export declare type TriggerAppEventCommandOptions = CommandContext & {
+    name: string;
+    payload?: Record<string, unknown>;
+};
+
+export declare type TriggerAppEventCommandResult = {
+    kind: 'appEventTriggered';
+    name: string;
+    payload?: Record<string, unknown>;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 export declare type TypeTextCommandOptions = CommandContext & {
     text: string;
     delayMs?: number;