agent-device 0.12.4 → 0.12.6

package/dist/src/index.d.ts

@@ -1,3 +1,113 @@
+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;
+
+export declare type AgentDevice = AgentDeviceRuntime & BoundAgentDeviceCommands;
+
+export declare type AgentDeviceBackend = {
+    platform: AgentDeviceBackendPlatform;
+    capabilities?: BackendCapabilitySet;
+    escapeHatches?: BackendEscapeHatches;
+    captureSnapshot?(context: BackendCommandContext, options?: BackendSnapshotOptions): Promise<BackendSnapshotResult>;
+    captureScreenshot?(context: BackendCommandContext, outPath: string, options?: BackendScreenshotOptions): Promise<BackendScreenshotResult | void>;
+    readText?(context: BackendCommandContext, node: SnapshotNode): Promise<BackendReadTextResult>;
+    findText?(context: BackendCommandContext, text: string): Promise<BackendFindTextResult>;
+    tap?(context: BackendCommandContext, point: Point, options?: BackendTapOptions): Promise<BackendActionResult>;
+    fill?(context: BackendCommandContext, point: Point, text: string, options?: BackendFillOptions): Promise<BackendActionResult>;
+    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>;
+    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>;
+    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';
+
 export declare type AgentDeviceClient = {
     command: AgentDeviceCommandClient;
     devices: {
@@ -108,6 +218,78 @@ export declare type AgentDeviceCommandClient = {
     clipboard: (options: ClipboardCommandOptions) => Promise<ClipboardCommandResult>;
 };
 
+declare type AgentDeviceCommands = {
+    capture: {
+        screenshot: RuntimeCommand<ScreenshotCommandOptions, ScreenshotCommandResult>;
+        diffScreenshot: RuntimeCommand<DiffScreenshotCommandOptions, DiffScreenshotCommandResult>;
+        snapshot: RuntimeCommand<SnapshotCommandOptions, SnapshotCommandResult>;
+        diffSnapshot: RuntimeCommand<DiffSnapshotCommandOptions, DiffSnapshotCommandResult>;
+    };
+    selectors: {
+        find: RuntimeCommand<FindReadCommandOptions, FindReadCommandResult>;
+        get: RuntimeCommand<GetCommandOptions, GetCommandResult>;
+        getText: RuntimeCommand<GetTextCommandOptions, Extract<GetCommandResult, {
+            kind: 'text';
+        }>>;
+        getAttrs: RuntimeCommand<GetAttrsCommandOptions, Extract<GetCommandResult, {
+            kind: 'attrs';
+        }>>;
+        is: RuntimeCommand<IsCommandOptions, IsCommandResult>;
+        isVisible: RuntimeCommand<IsSelectorCommandOptions, IsCommandResult>;
+        isHidden: RuntimeCommand<IsSelectorCommandOptions, IsCommandResult>;
+        wait: RuntimeCommand<WaitCommandOptions_2, WaitCommandResult_2>;
+        waitForText: RuntimeCommand<WaitForTextCommandOptions, Extract<WaitCommandResult_2, {
+            kind: 'text';
+        }>>;
+    };
+    interactions: {
+        click: RuntimeCommand<ClickCommandOptions, PressCommandResult>;
+        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>;
+    };
+};
+
 export declare type AgentDeviceDaemonTransport = (req: Omit<DaemonRequest, 'token'>) => Promise<DaemonResponse>;
 
 export declare type AgentDeviceDevice = {
@@ -139,6 +321,26 @@ export declare type AgentDeviceIdentifiers = {
 
 export declare type AgentDeviceRequestOverrides = Pick<AgentDeviceClientConfig, 'session' | 'lockPolicy' | 'lockPlatform' | 'requestId' | 'daemonBaseUrl' | 'daemonAuthToken' | 'daemonTransport' | 'daemonServerMode' | 'tenant' | 'sessionIsolation' | 'runId' | 'leaseId' | 'leaseBackend' | 'cwd' | 'debug'>;
 
+export declare type AgentDeviceRuntime = {
+    backend: AgentDeviceBackend;
+    artifacts: ArtifactAdapter;
+    sessions: CommandSessionStore;
+    policy: CommandPolicy;
+    diagnostics?: DiagnosticsSink;
+    clock?: CommandClock;
+    signal?: AbortSignal;
+};
+
+export declare type AgentDeviceRuntimeConfig = {
+    backend: AgentDeviceBackend;
+    artifacts: ArtifactAdapter;
+    sessions?: CommandSessionStore;
+    policy?: CommandPolicy;
+    diagnostics?: DiagnosticsSink;
+    clock?: CommandClock;
+    signal?: AbortSignal;
+};
+
 export declare type AgentDeviceSelectionOptions = {
     platform?: PlatformSelector;
     target?: DeviceTarget;
@@ -212,7 +414,7 @@ export declare class AppError extends Error {
     constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown);
 }
 
-declare type AppErrorCode = 'INVALID_ARGS' | 'DEVICE_NOT_FOUND' | 'TOOL_MISSING' | 'APP_NOT_INSTALLED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_OPERATION' | 'COMMAND_FAILED' | 'SESSION_NOT_FOUND' | 'UNAUTHORIZED' | 'UNKNOWN';
+export declare type AppErrorCode = 'INVALID_ARGS' | 'DEVICE_NOT_FOUND' | 'TOOL_MISSING' | 'APP_NOT_INSTALLED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_OPERATION' | 'NOT_IMPLEMENTED' | 'COMMAND_FAILED' | 'SESSION_NOT_FOUND' | 'UNAUTHORIZED' | 'UNKNOWN';
 
 declare type AppErrorDetails = Record<string, unknown> & {
     hint?: string;
@@ -267,6 +469,11 @@ export declare type AppOpenResult = {
     identifiers: AgentDeviceIdentifiers;
 };
 
+export declare type AppPushInput = {
+    kind: 'json';
+    payload: Record<string, unknown>;
+} | FileInputRef;
+
 export declare type AppPushOptions = ClientCommandBaseOptions & {
     app: string;
     payload: string | Record<string, unknown>;
@@ -293,6 +500,30 @@ export declare type AppTriggerEventOptions = ClientCommandBaseOptions & {
     payload?: Record<string, unknown>;
 };
 
+export declare type ArtifactAdapter = {
+    resolveInput(ref: FileInputRef, options: ResolveInputOptions): Promise<ResolvedInputFile>;
+    reserveOutput(ref: FileOutputRef | undefined, options: ReserveOutputOptions): Promise<ReservedOutputFile>;
+    createTempFile(options: CreateTempFileOptions): Promise<TemporaryFile>;
+};
+
+export declare type ArtifactDescriptor = {
+    kind: 'localPath';
+    field: string;
+    path: string;
+    fileName?: string;
+    metadata?: Record<string, unknown>;
+} | {
+    kind: 'artifact';
+    field: string;
+    artifactId: string;
+    fileName?: string;
+    url?: string;
+    clientPath?: string;
+    metadata?: Record<string, unknown>;
+};
+
+export declare function assertBackendCapabilityAllowed(runtime: Pick<AgentDeviceRuntime, 'backend' | 'policy'>, capability: BackendCapabilityName): void;
+
 export declare type BackCommandOptions = DeviceCommandBaseOptions & {
     mode?: 'in-app' | 'system';
 };
@@ -301,235 +532,1243 @@ export declare type BackCommandResult = CommandActionResult<'back'> & {
     mode?: 'in-app' | 'system';
 };
 
-export declare type BatchRunOptions = AgentDeviceRequestOverrides & {
-    steps: BatchStep[];
-    onError?: 'stop';
-    maxSteps?: number;
-    out?: string;
-};
+declare const BACKEND_CAPABILITY_NAMES: readonly ["android.shell", "ios.runnerCommand", "macos.desktopScreenshot"];
 
-export declare type BatchStep = {
-    command: string;
-    positionals?: string[];
-    flags?: Record<string, unknown>;
-};
+export declare type BackendActionResult = Record<string, unknown> | void;
 
-export declare type CaptureDiffOptions = ClientCommandBaseOptions & Pick<CaptureSnapshotOptions, 'interactiveOnly' | 'compact' | 'depth' | 'scope' | 'raw'> & {
-    kind: 'snapshot';
-    out?: string;
-};
+export declare type BackendAlertAction = 'get' | 'accept' | 'dismiss' | 'wait';
 
-export declare type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
-    path?: string;
-    overlayRefs?: boolean;
-    fullscreen?: boolean;
+export declare type BackendAlertInfo = {
+    title?: string;
+    message?: string;
+    buttons?: string[];
 };
 
-export declare type CaptureScreenshotResult = {
-    path: string;
-    overlayRefs?: ScreenshotOverlayRef[];
-    identifiers: AgentDeviceIdentifiers;
+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 CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-    interactiveOnly?: boolean;
-    compact?: boolean;
-    depth?: number;
-    scope?: string;
-    raw?: boolean;
+export declare type BackendAppEvent = {
+    name: string;
+    payload?: Record<string, unknown>;
 };
 
-export declare type CaptureSnapshotResult = {
-    nodes: SnapshotNode[];
-    truncated: boolean;
-    appName?: string;
-    appBundleId?: string;
-    visibility?: SnapshotVisibility;
-    warnings?: string[];
-    identifiers: AgentDeviceIdentifiers;
+export declare type BackendAppInfo = {
+    id: string;
+    name?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
 };
 
-export declare function centerOfRect(rect: Rect): Point;
+export declare type BackendAppListFilter = 'all' | 'user-installed';
 
-export declare type ClickOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & {
-    button?: 'primary' | 'secondary' | 'middle';
+export declare type BackendAppState = {
+    appId?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
+    state?: 'unknown' | 'notRunning' | 'running' | 'foreground' | 'background';
+    details?: Record<string, unknown>;
 };
 
-declare type ClientCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
-
-export declare type ClipboardCommandOptions = (DeviceCommandBaseOptions & {
-    action: 'read';
-}) | (DeviceCommandBaseOptions & {
-    action: 'write';
-    text: string;
-});
-
-export declare type ClipboardCommandResult = (DaemonResponseData & {
-    action: 'read';
-    text: string;
-}) | (DaemonResponseData & {
-    action: 'write';
-    textLength: number;
-});
-
-declare type CommandActionResult<T extends string> = DaemonResponseData & {
-    action?: T;
+export declare type BackendBackOptions = {
+    mode?: 'in-app' | 'system';
 };
 
-export declare type CommandRequestResult = DaemonResponseData;
-
-export declare function createAgentDeviceClient(config?: AgentDeviceClientConfig, deps?: {
-    transport?: AgentDeviceDaemonTransport;
-}): AgentDeviceClient;
-
-declare type DaemonArtifact = {
-    field: string;
-    artifactId?: string;
-    fileName?: string;
-    localPath?: string;
-    path?: string;
-};
+export declare type BackendCapabilityName = (typeof BACKEND_CAPABILITY_NAMES)[number];
 
-declare type DaemonError = {
-    code: string;
-    message: string;
-    hint?: string;
-    diagnosticId?: string;
-    logPath?: string;
-    details?: Record<string, unknown>;
-};
+export declare type BackendCapabilitySet = readonly BackendCapabilityName[];
 
-declare type DaemonInstallSource = {
-    kind: 'url';
-    url: string;
-    headers?: Record<string, string>;
-} | {
-    kind: 'path';
-    path: string;
+export declare type BackendClipboardTextResult = {
+    text: string;
 };
 
-declare type DaemonLockPolicy = 'reject' | 'strip';
-
-declare type DaemonRequest = {
-    token?: string;
+export declare type BackendCommandContext = {
     session?: string;
-    command: string;
-    positionals: string[];
-    flags?: Record<string, unknown>;
-    runtime?: SessionRuntimeHints;
-    meta?: DaemonRequestMeta;
-};
-
-declare type DaemonRequestMeta = {
     requestId?: string;
-    debug?: boolean;
-    cwd?: string;
-    tenantId?: string;
-    runId?: string;
-    leaseId?: string;
-    leaseTtlMs?: number;
-    leaseBackend?: LeaseBackend;
-    sessionIsolation?: 'none' | 'tenant';
-    uploadedArtifactId?: string;
-    clientArtifactPaths?: Record<string, string>;
-    installSource?: DaemonInstallSource;
-    retainMaterializedPaths?: boolean;
-    materializedPathRetentionMs?: number;
-    materializationId?: string;
-    lockPolicy?: DaemonLockPolicy;
-    lockPlatform?: 'ios' | 'macos' | 'android' | 'linux' | 'apple';
+    appId?: string;
+    appBundleId?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
 };
 
-declare type DaemonResponse = {
-    ok: true;
-    data?: DaemonResponseData;
-} | {
-    ok: false;
-    error: DaemonError;
+export declare type BackendDeviceFilter = {
+    platform?: AgentDeviceBackendPlatform | 'apple';
+    target?: 'mobile' | 'tv' | 'desktop';
+    kind?: 'simulator' | 'emulator' | 'device' | 'desktop';
 };
 
-declare type DaemonResponseData = Record<string, unknown> & {
-    artifacts?: DaemonArtifact[];
+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>;
 };
 
-declare type DaemonServerMode = 'socket' | 'http' | 'dual';
-
-declare type DaemonTransportMode = 'auto' | 'socket' | 'http';
+export declare type BackendDeviceOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
 
-export declare type DeviceBootOptions = ClientCommandBaseOptions & {
+export declare type BackendDeviceTarget = {
+    id?: string;
+    name?: string;
+    platform?: AgentDeviceBackendPlatform;
+    target?: 'mobile' | 'tv' | 'desktop';
     headless?: boolean;
 };
 
-declare type DeviceCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
+export declare type BackendDiagnosticsPageOptions = BackendDiagnosticsTimeWindow & {
+    cursor?: string;
+    limit?: number;
+};
 
-declare type DeviceKind = 'simulator' | 'emulator' | 'device';
+export declare type BackendDiagnosticsTimeWindow = {
+    since?: string;
+    until?: string;
+};
 
-declare type DeviceTarget = 'mobile' | 'tv' | 'desktop';
+export declare type BackendDumpNetworkOptions = BackendDiagnosticsPageOptions & {
+    include?: BackendNetworkIncludeMode;
+};
 
-export declare type ElementTarget = RefTarget | SelectorTarget;
+export declare type BackendDumpNetworkResult = {
+    entries: readonly BackendNetworkEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
 
-export declare type EnsureSimulatorOptions = AgentDeviceRequestOverrides & {
+export declare type BackendEnsureSimulatorOptions = {
     device: string;
     runtime?: string;
     boot?: boolean;
     reuseExisting?: boolean;
-    iosSimulatorDeviceSet?: string;
 };
 
-export declare type EnsureSimulatorResult = {
+export declare type BackendEnsureSimulatorResult = {
     udid: string;
     device: string;
     runtime: string;
     created: boolean;
     booted: boolean;
-    iosSimulatorDeviceSet?: string | null;
-    identifiers: AgentDeviceIdentifiers;
+    simulatorSetPath?: string | null;
 };
 
-export declare type FillOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
-    text: string;
-    delayMs?: number;
+export declare type BackendEscapeHatches = {
+    androidShell?(context: BackendCommandContext, args: readonly string[]): Promise<BackendShellResult>;
+    iosRunnerCommand?(context: BackendCommandContext, command: BackendRunnerCommand): Promise<BackendActionResult>;
+    macosDesktopScreenshot?(context: BackendCommandContext, outPath: string, options?: BackendScreenshotOptions): Promise<BackendScreenshotResult | void>;
 };
 
-declare type FindBaseOptions = ClientCommandBaseOptions & FindSnapshotCommandOptions & {
-    locator?: FindLocator;
-    query: string;
-    first?: boolean;
-    last?: boolean;
+export declare type BackendFillOptions = {
+    delayMs?: number;
 };
 
-export declare type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
-
-export declare type FindOptions = (FindBaseOptions & {
-    action?: 'click' | 'focus' | 'exists' | 'getText' | 'getAttrs';
-}) | (FindBaseOptions & {
-    action: 'wait';
-    timeoutMs?: number;
-}) | (FindBaseOptions & {
-    action: 'fill' | 'type';
-    value: string;
-});
-
-declare type FindSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'raw'>;
-
-declare type FocusOptions_2 = ClientCommandBaseOptions & {
-    x: number;
-    y: number;
+export declare type BackendFindTextResult = {
+    found: boolean;
 };
-export { FocusOptions_2 as FocusOptions }
 
-export declare type GetOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & {
-    format: 'text' | 'attrs';
+export declare type BackendInstallResult = Record<string, unknown> & {
+    appId?: string;
+    appName?: string;
+    bundleId?: string;
+    packageName?: string;
+    launchTarget?: string;
+    installablePath?: string;
+    archivePath?: string;
 };
 
-export declare type HomeCommandOptions = DeviceCommandBaseOptions;
+export declare type BackendInstallSource = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'uploadedArtifact';
+    id: string;
+} | {
+    kind: 'url';
+    url: string;
+};
+
+export declare type BackendInstallTarget = {
+    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[];
+    payload?: Record<string, unknown>;
+};
+
+export declare type BackendScreenshotOptions = {
+    fullscreen?: boolean;
+    overlayRefs?: boolean;
+    surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
+};
+
+export declare type BackendScreenshotResult = {
+    path?: string;
+    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;
+    stderr: string;
+};
+
+export declare type BackendSnapshotAnalysis = {
+    rawNodeCount?: number;
+    maxDepth?: number;
+};
+
+export declare type BackendSnapshotFreshness = {
+    action: string;
+    retryCount: number;
+    staleAfterRetries: boolean;
+    reason?: 'empty-interactive' | 'sharp-drop' | 'stuck-route';
+};
+
+export declare type BackendSnapshotOptions = SnapshotOptions & {
+    outPath?: string;
+};
+
+export declare type BackendSnapshotResult = {
+    nodes?: SnapshotNode[];
+    truncated?: boolean;
+    backend?: string;
+    snapshot?: SnapshotState;
+    analysis?: BackendSnapshotAnalysis;
+    freshness?: BackendSnapshotFreshness;
+    warnings?: string[];
+    appName?: string;
+    appBundleId?: string;
+};
+
+export declare type BackendSwipeOptions = {
+    durationMs?: number;
+};
+
+export declare type BackendTapOptions = {
+    button?: 'primary' | 'secondary' | 'middle';
+    count?: number;
+    intervalMs?: number;
+    holdMs?: number;
+    jitterPx?: number;
+    doubleTap?: boolean;
+};
+
+export declare type BackendTraceOptions = {
+    outPath?: string;
+};
+
+export 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 type BatchRunOptions = AgentDeviceRequestOverrides & {
+    steps: BatchStep[];
+    onError?: 'stop';
+    maxSteps?: number;
+    out?: string;
+};
+
+export declare type BatchStep = {
+    command: string;
+    positionals?: string[];
+    flags?: Record<string, unknown>;
+};
+
+export declare type BoundAgentDeviceCommands = {
+    capture: {
+        screenshot: BoundRuntimeCommand<ScreenshotCommandOptions, ScreenshotCommandResult>;
+        diffScreenshot: BoundRuntimeCommand<DiffScreenshotCommandOptions, DiffScreenshotCommandResult>;
+        snapshot: BoundRuntimeCommand<SnapshotCommandOptions, SnapshotCommandResult>;
+        diffSnapshot: BoundRuntimeCommand<DiffSnapshotCommandOptions, DiffSnapshotCommandResult>;
+    };
+    selectors: {
+        find: BoundRuntimeCommand<FindReadCommandOptions, FindReadCommandResult>;
+        get: BoundRuntimeCommand<GetCommandOptions, GetCommandResult>;
+        getText: (target: ElementTarget_2, options?: Omit<GetTextCommandOptions, 'target'>) => Promise<Extract<GetCommandResult, {
+            kind: 'text';
+        }>>;
+        getAttrs: (target: ElementTarget_2, options?: Omit<GetAttrsCommandOptions, 'target'>) => Promise<Extract<GetCommandResult, {
+            kind: 'attrs';
+        }>>;
+        is: BoundRuntimeCommand<IsCommandOptions, IsCommandResult>;
+        isVisible: (target: SelectorTarget, options?: Omit<IsSelectorCommandOptions, 'target'>) => Promise<IsCommandResult>;
+        isHidden: (target: SelectorTarget, options?: Omit<IsSelectorCommandOptions, 'target'>) => Promise<IsCommandResult>;
+        wait: BoundRuntimeCommand<WaitCommandOptions_2, WaitCommandResult_2>;
+        waitForText: (text: string, options?: Omit<WaitForTextCommandOptions, 'text'>) => Promise<Extract<WaitCommandResult_2, {
+            kind: 'text';
+        }>>;
+    };
+    interactions: {
+        click: (target: InteractionTarget_2, options?: Omit<ClickCommandOptions, 'target'>) => Promise<PressCommandResult>;
+        press: (target: InteractionTarget_2, options?: Omit<PressCommandOptions, 'target'>) => Promise<PressCommandResult>;
+        fill: (target: InteractionTarget_2, text: string, options?: Omit<FillCommandOptions, 'target' | 'text'>) => Promise<FillCommandResult>;
+        typeText: (text: string, options?: Omit<TypeTextCommandOptions, 'text'>) => Promise<TypeTextCommandResult>;
+        focus: (target: InteractionTarget_2, options?: Omit<FocusCommandOptions, 'target'>) => Promise<FocusCommandResult>;
+        longPress: (target: InteractionTarget_2, 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>;
+    };
+};
+
+export declare type BoundRuntimeCommand<TOptions = Record<string, unknown>, TResult = CommandResult> = (options: TOptions) => Promise<TResult>;
+
+export declare type CaptureDiffOptions = ClientCommandBaseOptions & Pick<CaptureSnapshotOptions, 'interactiveOnly' | 'compact' | 'depth' | 'scope' | 'raw'> & {
+    kind: 'snapshot';
+    out?: string;
+};
+
+export declare type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
+    path?: string;
+    overlayRefs?: boolean;
+    fullscreen?: boolean;
+    surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
+};
+
+export declare type CaptureScreenshotResult = {
+    path: string;
+    overlayRefs?: ScreenshotOverlayRef[];
+    identifiers: AgentDeviceIdentifiers;
+};
+
+export declare type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+    interactiveOnly?: boolean;
+    compact?: boolean;
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+};
+
+export declare type CaptureSnapshotResult = {
+    nodes: SnapshotNode[];
+    truncated: boolean;
+    appName?: string;
+    appBundleId?: string;
+    visibility?: SnapshotVisibility;
+    warnings?: string[];
+    identifiers: AgentDeviceIdentifiers;
+};
+
+export declare function centerOfRect(rect: Rect): Point;
+
+declare type ClickCommandOptions = PressCommandOptions;
+
+export declare type ClickOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & {
+    button?: 'primary' | 'secondary' | 'middle';
+};
+
+declare type ClientCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
+
+export declare type ClipboardCommandOptions = (DeviceCommandBaseOptions & {
+    action: 'read';
+}) | (DeviceCommandBaseOptions & {
+    action: 'write';
+    text: string;
+});
+
+export declare type ClipboardCommandResult = (DaemonResponseData & {
+    action: 'read';
+    text: string;
+}) | (DaemonResponseData & {
+    action: 'write';
+    textLength: number;
+});
+
+export declare type CloseAppCommandOptions = CommandContext & {
+    app?: string;
+};
+
+export declare type CloseAppCommandResult = {
+    kind: 'appClosed';
+    app?: string;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type CommandActionResult<T extends string> = DaemonResponseData & {
+    action?: T;
+};
+
+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';
+};
+
+export declare type CommandClock = {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+};
+
+export declare type CommandContext = {
+    session?: string;
+    requestId?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+};
+
+export declare type CommandPolicy = {
+    allowLocalInputPaths: boolean;
+    allowLocalOutputPaths: boolean;
+    maxImagePixels: number;
+    allowNamedBackendCapabilities: readonly BackendCapabilityName[];
+};
+
+export declare type CommandRequestResult = DaemonResponseData;
+
+export declare type CommandResult = Record<string, unknown>;
+
+export declare type CommandRouter<TContext = unknown> = {
+    dispatch(request: CommandRouterRequest<TContext>): Promise<CommandRouterResponse>;
+};
+
+export declare type CommandRouterConfig<TContext = unknown> = {
+    createRuntime(request: CommandRouterRequest<TContext>): AgentDeviceRuntime | Promise<AgentDeviceRuntime>;
+    beforeDispatch?(request: CommandRouterRequest<TContext>): void | Promise<void>;
+    formatError?(error: unknown, request: CommandRouterRequest<TContext>): NormalizedError;
+};
+
+export declare type CommandRouterRequest<TContext = unknown> = {
+    command: 'capture.screenshot';
+    options: ScreenshotCommandOptions;
+    context?: TContext;
+} | {
+    command: 'capture.diffScreenshot';
+    options: DiffScreenshotCommandOptions;
+    context?: TContext;
+} | {
+    command: 'capture.snapshot';
+    options: SnapshotCommandOptions;
+    context?: TContext;
+} | {
+    command: 'capture.diffSnapshot';
+    options: DiffSnapshotCommandOptions;
+    context?: TContext;
+} | {
+    command: 'selectors.find';
+    options: FindReadCommandOptions;
+    context?: TContext;
+} | {
+    command: 'selectors.get';
+    options: GetCommandOptions;
+    context?: TContext;
+} | {
+    command: 'selectors.is';
+    options: IsCommandOptions;
+    context?: TContext;
+} | {
+    command: 'selectors.wait';
+    options: WaitCommandOptions_2;
+    context?: TContext;
+} | {
+    command: 'interactions.click';
+    options: ClickCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.press';
+    options: PressCommandOptions;
+    context?: TContext;
+} | {
+    command: 'interactions.fill';
+    options: FillCommandOptions;
+    context?: TContext;
+} | {
+    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 = {
+    ok: true;
+    data: CommandRouterResult;
+} | {
+    ok: false;
+    error: NormalizedError;
+};
+
+export declare type CommandRouterResult = ScreenshotCommandResult | DiffScreenshotCommandResult | SnapshotCommandResult | DiffSnapshotCommandResult | FindReadCommandResult | GetCommandResult | IsCommandResult | WaitCommandResult_2 | 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;
+
+export declare type CommandSessionRecord = {
+    name: string;
+    appId?: string;
+    appBundleId?: string;
+    appName?: string;
+    backendSessionId?: string;
+    snapshot?: SnapshotState;
+    metadata?: Record<string, unknown>;
+};
+
+export declare type CommandSessionStore = {
+    get(name: string): CommandSessionRecord | undefined | Promise<CommandSessionRecord | undefined>;
+    set(record: CommandSessionRecord): void | Promise<void>;
+    delete?(name: string): void | Promise<void>;
+    list?(): readonly CommandSessionRecord[] | Promise<readonly CommandSessionRecord[]>;
+};
+
+export declare function createAgentDevice(config: AgentDeviceRuntimeConfig): AgentDevice;
+
+export declare function createAgentDeviceClient(config?: AgentDeviceClientConfig, deps?: {
+    transport?: AgentDeviceDaemonTransport;
+}): AgentDeviceClient;
+
+export declare function createCommandRouter<TContext = unknown>(config: CommandRouterConfig<TContext>): CommandRouter<TContext>;
+
+export declare function createLocalArtifactAdapter(options?: LocalArtifactAdapterOptions): ArtifactAdapter;
+
+export declare function createMemorySessionStore(records?: readonly CommandSessionRecord[]): CommandSessionStore;
+
+export declare type CreateTempFileOptions = {
+    prefix: string;
+    ext: string;
+};
+
+declare type DaemonArtifact = {
+    field: string;
+    artifactId?: string;
+    fileName?: string;
+    localPath?: string;
+    path?: string;
+};
+
+declare type DaemonError = {
+    code: string;
+    message: string;
+    hint?: string;
+    diagnosticId?: string;
+    logPath?: string;
+    details?: Record<string, unknown>;
+};
+
+declare type DaemonInstallSource = {
+    kind: 'url';
+    url: string;
+    headers?: Record<string, string>;
+} | {
+    kind: 'path';
+    path: string;
+};
+
+declare type DaemonLockPolicy = 'reject' | 'strip';
+
+declare type DaemonRequest = {
+    token?: string;
+    session?: string;
+    command: string;
+    positionals: string[];
+    flags?: Record<string, unknown>;
+    runtime?: SessionRuntimeHints;
+    meta?: DaemonRequestMeta;
+};
+
+declare type DaemonRequestMeta = {
+    requestId?: string;
+    debug?: boolean;
+    cwd?: string;
+    tenantId?: string;
+    runId?: string;
+    leaseId?: string;
+    leaseTtlMs?: number;
+    leaseBackend?: LeaseBackend;
+    sessionIsolation?: 'none' | 'tenant';
+    uploadedArtifactId?: string;
+    clientArtifactPaths?: Record<string, string>;
+    installSource?: DaemonInstallSource;
+    retainMaterializedPaths?: boolean;
+    materializedPathRetentionMs?: number;
+    materializationId?: string;
+    lockPolicy?: DaemonLockPolicy;
+    lockPlatform?: 'ios' | 'macos' | 'android' | 'linux' | 'apple';
+};
+
+declare type DaemonResponse = {
+    ok: true;
+    data?: DaemonResponseData;
+} | {
+    ok: false;
+    error: DaemonError;
+};
+
+declare type DaemonResponseData = Record<string, unknown> & {
+    artifacts?: DaemonArtifact[];
+};
+
+declare type DaemonServerMode = 'socket' | 'http' | 'dual';
+
+declare type DaemonTransportMode = 'auto' | 'socket' | 'http';
+
+export declare type DeviceBootOptions = ClientCommandBaseOptions & {
+    headless?: boolean;
+};
+
+declare type DeviceCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
+
+declare type DeviceKind = 'simulator' | 'emulator' | 'device';
+
+declare type DeviceTarget = 'mobile' | 'tv' | 'desktop';
+
+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[];
+};
+
+export declare type DiagnosticsSink = {
+    emit(event: {
+        level: 'debug' | 'info' | 'warn' | 'error';
+        message: string;
+        data?: unknown;
+    }): void;
+};
+
+declare type DiffScreenshotCommandOptions = CommandContext & {
+    baseline: FileInputRef;
+    current?: FileInputRef | LiveScreenshotInputRef;
+    out?: FileOutputRef;
+    currentOverlayOut?: FileOutputRef;
+    threshold?: number;
+    overlayRefs?: boolean;
+    surface?: BackendScreenshotOptions['surface'];
+};
+
+declare type DiffScreenshotCommandResult = ScreenshotDiffResult & {
+    artifacts?: ArtifactDescriptor[];
+};
+
+declare type DiffSnapshotCommandOptions = SnapshotCommandOptions;
+
+declare type DiffSnapshotCommandResult = {
+    mode: 'snapshot';
+    baselineInitialized: boolean;
+    summary: SnapshotDiffSummary;
+    lines: SnapshotDiffLine[];
+    warnings?: string[];
+};
+
+export declare type ElementTarget = RefTarget_2 | SelectorTarget_2;
+
+declare type ElementTarget_2 = SelectorTarget | RefTarget;
+
+export declare type EnsureSimulatorOptions = AgentDeviceRequestOverrides & {
+    device: string;
+    runtime?: string;
+    boot?: boolean;
+    reuseExisting?: boolean;
+    iosSimulatorDeviceSet?: string;
+};
+
+export declare type EnsureSimulatorResult = {
+    udid: string;
+    device: string;
+    runtime: string;
+    created: boolean;
+    booted: boolean;
+    iosSimulatorDeviceSet?: string | null;
+    identifiers: AgentDeviceIdentifiers;
+};
+
+export declare type FileInputRef = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'uploadedArtifact';
+    id: string;
+};
+
+export declare type FileOutputRef = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'downloadableArtifact';
+    clientPath?: string;
+    fileName?: string;
+};
+
+declare type FillCommandOptions = CommandContext & {
+    target: InteractionTarget_2;
+    text: string;
+    delayMs?: number;
+};
+
+declare type FillCommandResult = ResolvedInteractionTarget & {
+    text: string;
+    warning?: string;
+    backendResult?: Record<string, unknown>;
+};
+
+export declare type FillOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
+    text: string;
+    delayMs?: number;
+};
+
+declare type FindAction = {
+    kind: 'click';
+} | {
+    kind: 'focus';
+} | {
+    kind: 'fill';
+    value: string;
+} | {
+    kind: 'type';
+    value: string;
+} | {
+    kind: 'get_text';
+} | {
+    kind: 'get_attrs';
+} | {
+    kind: 'exists';
+} | {
+    kind: 'wait';
+    timeoutMs?: number;
+};
+
+declare type FindBaseOptions = ClientCommandBaseOptions & FindSnapshotCommandOptions & {
+    locator?: FindLocator;
+    query: string;
+    first?: boolean;
+    last?: boolean;
+};
+
+export declare type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
+
+declare type FindLocator_2 = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
+
+export declare type FindOptions = (FindBaseOptions & {
+    action?: 'click' | 'focus' | 'exists' | 'getText' | 'getAttrs';
+}) | (FindBaseOptions & {
+    action: 'wait';
+    timeoutMs?: number;
+}) | (FindBaseOptions & {
+    action: 'fill' | 'type';
+    value: string;
+});
+
+declare type FindReadCommandOptions = CommandContext & {
+    locator?: FindLocator_2;
+    query: string;
+    action: Extract<FindAction['kind'], 'exists' | 'wait' | 'get_text' | 'get_attrs'>;
+    timeoutMs?: number;
+} & SelectorSnapshotOptions;
+
+declare type FindReadCommandResult = {
+    kind: 'found';
+    found: true;
+    waitedMs?: number;
+} | {
+    kind: 'text';
+    ref: string;
+    text: string;
+    node: SnapshotNode;
+} | {
+    kind: 'attrs';
+    ref: string;
+    node: SnapshotNode;
+};
+
+declare type FindSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'raw'>;
+
+declare type FocusCommandOptions = CommandContext & {
+    target: InteractionTarget_2;
+};
+
+declare type FocusCommandResult = ResolvedInteractionTarget & {
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type FocusOptions_2 = ClientCommandBaseOptions & {
+    x: number;
+    y: number;
+};
+export { FocusOptions_2 as FocusOptions }
+
+declare type GestureDirection = 'up' | 'down' | 'left' | 'right';
+
+export declare type GetAppStateCommandOptions = CommandContext & {
+    app: string;
+};
+
+export declare type GetAppStateCommandResult = {
+    kind: 'appState';
+    app: string;
+    state: BackendAppState;
+};
+
+declare type GetAttrsCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    target: ElementTarget_2;
+};
+
+declare type GetCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    property: 'text' | 'attrs';
+    target: ElementTarget_2;
+};
+
+declare type GetCommandResult = {
+    kind: 'text';
+    target: ResolvedTarget;
+    text: string;
+    node: SnapshotNode;
+    selectorChain?: string[];
+} | {
+    kind: 'attrs';
+    target: ResolvedTarget;
+    node: SnapshotNode;
+    selectorChain?: string[];
+};
+
+export declare type GetOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & {
+    format: 'text' | 'attrs';
+};
+
+declare type GetTextCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    target: ElementTarget_2;
+};
+
+export declare type HomeCommandOptions = DeviceCommandBaseOptions;
 
 export declare type HomeCommandResult = CommandActionResult<'home'>;
 
-export declare type InteractionTarget = PointTarget | RefTarget | SelectorTarget;
+export declare type InteractionTarget = PointTarget_2 | RefTarget_2 | SelectorTarget_2;
+
+declare type InteractionTarget_2 = ElementTarget_2 | PointTarget;
+
+export declare function isAgentDeviceError(err: unknown): err is AppError;
+
+declare type IsCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected' | 'text';
+    selector: string;
+    expectedText?: string;
+};
+
+declare type IsCommandResult = {
+    predicate: IsCommandOptions['predicate'];
+    pass: true;
+    selector: string;
+    matches?: number;
+    text?: string;
+    selectorChain?: string[];
+};
 
 export declare type IsOptions = IsTextPredicateOptions | IsStatePredicateOptions;
 
+declare type IsSelectorCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    target: SelectorTarget;
+};
+
 declare type IsStatePredicateOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & {
     predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected';
     selector: string;
@@ -585,12 +1824,44 @@ declare type LeaseScopedOptions = LeaseOptions & {
     leaseId: string;
 };
 
+export declare type ListAppsCommandOptions = CommandContext & {
+    filter?: BackendAppListFilter;
+};
+
+export declare type ListAppsCommandResult = {
+    kind: 'appsList';
+    apps: readonly BackendAppInfo[];
+};
+
+declare type LiveScreenshotInputRef = {
+    kind: 'live';
+};
+
+export declare type LocalArtifactAdapterOptions = {
+    cwd?: string;
+    tempDir?: string;
+    rootDir?: string;
+};
+
+export declare function localCommandPolicy(overrides?: Partial<CommandPolicy>): CommandPolicy;
+
 export declare type LogsOptions = AgentDeviceRequestOverrides & {
     action?: 'path' | 'start' | 'stop' | 'doctor' | 'mark' | 'clear';
     message?: string;
     restart?: boolean;
 };
 
+declare type LongPressCommandOptions = CommandContext & {
+    target: InteractionTarget_2;
+    durationMs?: number;
+};
+
+declare type LongPressCommandResult = ResolvedInteractionTarget & {
+    durationMs?: number;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 export declare type LongPressOptions = ClientCommandBaseOptions & {
     x: number;
     y: number;
@@ -666,10 +1937,52 @@ export declare type NetworkOptions = AgentDeviceRequestOverrides & {
     include?: 'summary' | 'headers' | 'body' | 'all';
 };
 
+export declare function normalizeAgentDeviceError(err: unknown, context?: {
+    diagnosticId?: string;
+    logPath?: string;
+}): NormalizedError;
+
+export declare type NormalizedError = {
+    code: string;
+    message: string;
+    hint?: string;
+    diagnosticId?: string;
+    logPath?: string;
+    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;
+};
+
+export declare type OutputVisibility = 'client-visible' | 'internal';
+
 export declare type PerfOptions = ClientCommandBaseOptions;
 
 export declare type PermissionTarget = 'camera' | 'microphone' | 'photos' | 'contacts' | 'contacts-limited' | 'notifications' | 'calendar' | 'location' | 'location-always' | 'media-library' | 'motion' | 'reminders' | 'siri' | 'accessibility' | 'screen-recording' | 'input-monitoring';
 
+declare type PinchCommandOptions = CommandContext & {
+    scale: number;
+    center?: InteractionTarget_2;
+};
+
+declare type PinchCommandResult = {
+    kind: 'pinch';
+    scale: number;
+    center?: Point;
+    centerTarget?: ResolvedInteractionTarget;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 export declare type PinchOptions = ClientCommandBaseOptions & {
     scale: number;
     x?: number;
@@ -686,6 +1999,12 @@ export declare type Point = {
 };
 
 declare type PointTarget = {
+    kind: 'point';
+    x: number;
+    y: number;
+};
+
+declare type PointTarget_2 = {
     x: number;
     y: number;
     ref?: never;
@@ -709,8 +2028,35 @@ declare type PrepareMetroRuntimeResult = {
     bridge: MetroBridgeResult | null;
 };
 
+declare type PressCommandOptions = CommandContext & {
+    target: InteractionTarget_2;
+    button?: 'primary' | 'secondary' | 'middle';
+    count?: number;
+    intervalMs?: number;
+    holdMs?: number;
+    jitterPx?: number;
+    doubleTap?: boolean;
+};
+
+declare type PressCommandResult = ResolvedInteractionTarget & {
+    backendResult?: Record<string, unknown>;
+};
+
 export declare type PressOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions;
 
+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;
@@ -734,10 +2080,46 @@ declare type RawSnapshotNode = {
     hiddenContentBelow?: boolean;
 };
 
+declare type RecordingQuality = 5 | 6 | 7 | 8 | 9 | 10;
+
+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;
+};
+
 export declare type RecordOptions = AgentDeviceRequestOverrides & {
     action: 'start' | 'stop';
     path?: string;
     fps?: number;
+    quality?: RecordingQuality;
     hideTouches?: boolean;
 };
 
@@ -748,7 +2130,17 @@ export declare type Rect = {
     height: number;
 };
 
+export declare function ref(refInput: string, options?: {
+    fallbackLabel?: string;
+}): RefTarget;
+
 declare type RefTarget = {
+    kind: 'ref';
+    ref: string;
+    fallbackLabel?: string;
+};
+
+declare type RefTarget_2 = {
     ref: string;
     label?: string;
     x?: never;
@@ -779,8 +2171,65 @@ export declare type ReplayTestOptions = AgentDeviceRequestOverrides & AgentDevic
     reportJunit?: string;
 };
 
+export declare type ReservedOutputFile = {
+    path: string;
+    visibility: OutputVisibility;
+    publish: () => Promise<ArtifactDescriptor | undefined>;
+    cleanup?: () => Promise<void>;
+};
+
+export declare type ReserveOutputOptions = {
+    field: string;
+    ext: string;
+    requestedClientPath?: string;
+    visibility?: OutputVisibility;
+};
+
+export declare type ResolvedInputFile = {
+    path: string;
+    cleanup?: () => Promise<void>;
+};
+
+declare type ResolvedInteractionTarget = {
+    kind: 'point';
+    point: Point;
+} | {
+    kind: 'ref';
+    point: Point;
+    target: Extract<ResolvedTarget, {
+        kind: 'ref';
+    }>;
+    node: SnapshotNode;
+    selectorChain: string[];
+    refLabel?: string;
+} | {
+    kind: 'selector';
+    point: Point;
+    target: Extract<ResolvedTarget, {
+        kind: 'selector';
+    }>;
+    node: SnapshotNode;
+    selectorChain: string[];
+    refLabel?: string;
+};
+
 declare type ResolvedMetroKind = Exclude<MetroPrepareKind, 'auto'>;
 
+declare type ResolvedTarget = {
+    kind: 'selector';
+    selector: string;
+} | {
+    kind: 'ref';
+    ref: string;
+};
+
+export declare type ResolveInputOptions = {
+    usage: string;
+    field?: string;
+};
+
+export declare function restrictedCommandPolicy(overrides?: Partial<CommandPolicy>): CommandPolicy;
+
 export declare type RotateCommandOptions = DeviceCommandBaseOptions & {
     orientation: 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
 };
@@ -789,6 +2238,131 @@ export declare type RotateCommandResult = CommandActionResult<'rotate'> & {
     orientation?: RotateCommandOptions['orientation'];
 };
 
+export declare type RuntimeCommand<TOptions = Record<string, unknown>, TResult = CommandResult> = (runtime: AgentDeviceRuntime, options: TOptions) => Promise<TResult>;
+
+declare type ScreenshotCommandOptions = CommandContext & {
+    out?: FileOutputRef;
+    fullscreen?: boolean;
+    overlayRefs?: boolean;
+    appId?: string;
+    appBundleId?: string;
+    surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
+};
+
+declare type ScreenshotCommandResult = {
+    path: string;
+    artifacts?: ArtifactDescriptor[];
+    message?: string;
+};
+
+declare type ScreenshotDiffRegion = {
+    index: number;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    normalizedRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    differentPixels: number;
+    shareOfDiffPercentage: number;
+    densityPercentage: number;
+    shape: 'compact' | 'horizontal-band' | 'vertical-band' | 'large-area';
+    size: 'small' | 'medium' | 'large';
+    location: string;
+    averageBaselineColorHex: string;
+    averageCurrentColorHex: string;
+    baselineLuminance: number;
+    currentLuminance: number;
+    dominantChange: 'brighter' | 'darker' | 'color-shift' | 'mixed';
+    currentOverlayMatches?: ScreenshotDiffRegionOverlayMatch[];
+};
+
+declare type ScreenshotDiffRegionOverlayMatch = {
+    ref: string;
+    label?: string;
+    regionCoveragePercentage: number;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+};
+
+declare type ScreenshotDiffResult = {
+    diffPath?: string;
+    totalPixels: number;
+    differentPixels: number;
+    mismatchPercentage: number;
+    match: boolean;
+    dimensionMismatch?: ScreenshotDimensionMismatch;
+    regions?: ScreenshotDiffRegion[];
+    currentOverlayPath?: string;
+    currentOverlayRefCount?: number;
+    ocr?: ScreenshotOcrSummary;
+    nonTextDeltas?: ScreenshotNonTextDelta[];
+};
+
+declare type ScreenshotDimensionMismatch = {
+    expected: {
+        width: number;
+        height: number;
+    };
+    actual: {
+        width: number;
+        height: number;
+    };
+};
+
+declare type ScreenshotNonTextDelta = {
+    index: number;
+    regionIndex?: number;
+    slot: 'leading' | 'trailing' | 'background' | 'separator' | 'unknown';
+    likelyKind: 'icon' | 'toggle' | 'chevron' | 'separator' | 'visual';
+    rect: Rect;
+    nearestText?: string;
+};
+
+declare type ScreenshotOcrMovementCluster = {
+    texts: string[];
+    xRange: {
+        min: number;
+        max: number;
+    };
+    yRange: {
+        min: number;
+        max: number;
+    };
+};
+
+declare type ScreenshotOcrSummary = {
+    provider: 'tesseract';
+    baselineBlocks: number;
+    currentBlocks: number;
+    matches: ScreenshotOcrTextMatch[];
+    movementClusters?: ScreenshotOcrMovementCluster[];
+};
+
+declare type ScreenshotOcrTextMatch = {
+    text: string;
+    baselineRect: Rect;
+    currentRect: Rect;
+    delta: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    confidence: number;
+    possibleTextMetricMismatch: boolean;
+};
+
 export declare type ScreenshotOverlayRef = {
     ref: string;
     label?: string;
@@ -797,6 +2371,28 @@ export declare type ScreenshotOverlayRef = {
     center: Point;
 };
 
+declare type ScrollCommandOptions = CommandContext & {
+    target?: ScrollTarget;
+    direction: GestureDirection;
+    amount?: number;
+    pixels?: number;
+};
+
+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;
+});
+
 declare type ScrollOptions_2 = ClientCommandBaseOptions & {
     direction: 'up' | 'down' | 'left' | 'right';
     amount?: number;
@@ -804,9 +2400,26 @@ declare type ScrollOptions_2 = ClientCommandBaseOptions & {
 };
 export { ScrollOptions_2 as ScrollOptions }
 
+declare type ScrollTarget = InteractionTarget_2 | {
+    kind: 'viewport';
+};
+
+export declare function selector(expression: string): SelectorTarget;
+
 declare type SelectorSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
 
+export declare type SelectorSnapshotOptions = {
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+};
+
 declare type SelectorTarget = {
+    kind: 'selector';
+    selector: string;
+};
+
+declare type SelectorTarget_2 = {
     selector: string;
     x?: never;
     y?: never;
@@ -849,10 +2462,56 @@ export declare type SettingsUpdateOptions = (ClientCommandBaseOptions & {
     mode?: 'full' | 'limited';
 });
 
+declare type SnapshotBackend = 'xctest' | 'android' | 'macos-helper' | 'linux-atspi';
+
+declare type SnapshotCommandOptions = CommandContext & {
+    interactiveOnly?: boolean;
+    compact?: boolean;
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+};
+
+declare type SnapshotCommandResult = {
+    nodes: SnapshotNode[];
+    truncated: boolean;
+    appName?: string;
+    appBundleId?: string;
+    visibility?: SnapshotVisibility;
+    warnings?: string[];
+};
+
+declare type SnapshotDiffLine = {
+    kind: 'added' | 'removed' | 'unchanged';
+    text: string;
+};
+
+declare type SnapshotDiffSummary = {
+    additions: number;
+    removals: number;
+    unchanged: number;
+};
+
 export declare type SnapshotNode = RawSnapshotNode & {
     ref: string;
 };
 
+declare type SnapshotOptions = {
+    interactiveOnly?: boolean;
+    compact?: boolean;
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+};
+
+declare type SnapshotState = {
+    nodes: SnapshotNode[];
+    createdAt: number;
+    truncated?: boolean;
+    backend?: SnapshotBackend;
+    comparisonSafe?: boolean;
+};
+
 export declare type SnapshotVisibility = {
     partial: boolean;
     visibleNodeCount: number;
@@ -870,6 +2529,22 @@ export declare type StartupPerfSample = {
     appBundleId?: string;
 };
 
+declare type SwipeCommandOptions = CommandContext & SwipeOptions_2;
+
+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 = ClientCommandBaseOptions & {
     from: {
         x: number;
@@ -885,11 +2560,161 @@ export declare type SwipeOptions = ClientCommandBaseOptions & {
     pattern?: 'one-way' | 'ping-pong';
 };
 
+declare type SwipeOptions_2 = {
+    from?: Point | InteractionTarget_2;
+    to?: Point;
+    direction?: GestureDirection;
+    distance?: number;
+    durationMs?: number;
+};
+
+declare type SystemAlertCommandOptions = CommandContext & {
+    action?: BackendAlertAction;
+    timeoutMs?: number;
+};
+
+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;
+};
+
+declare type SystemAppSwitcherCommandOptions = CommandContext;
+
+declare type SystemAppSwitcherCommandResult = {
+    kind: 'appSwitcherOpened';
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type SystemBackCommandOptions = CommandContext & {
+    mode?: 'in-app' | 'system';
+};
+
+declare type SystemBackCommandResult = {
+    kind: 'systemBack';
+    mode: 'in-app' | 'system';
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type SystemClipboardCommandOptions = (CommandContext & {
+    action: 'read';
+}) | (CommandContext & {
+    action: 'write';
+    text: string;
+});
+
+declare type SystemClipboardCommandResult = {
+    kind: 'clipboardText';
+    action: 'read';
+    text: string;
+} | {
+    kind: 'clipboardUpdated';
+    action: 'write';
+    textLength: number;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type SystemHomeCommandOptions = CommandContext;
+
+declare type SystemHomeCommandResult = {
+    kind: 'systemHome';
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type SystemKeyboardCommandOptions = CommandContext & {
+    action?: 'status' | 'get' | 'dismiss';
+};
+
+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;
+};
+
+declare type SystemRotateCommandOptions = CommandContext & {
+    orientation: BackendDeviceOrientation;
+};
+
+declare type SystemRotateCommandResult = {
+    kind: 'systemRotated';
+    orientation: BackendDeviceOrientation;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type SystemSettingsCommandOptions = CommandContext & {
+    target?: string;
+};
+
+declare type SystemSettingsCommandResult = {
+    kind: 'settingsOpened';
+    target?: string;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+export declare type TemporaryFile = {
+    path: string;
+    visibility: 'internal';
+    cleanup: () => Promise<void>;
+};
+
 export declare type TraceOptions = AgentDeviceRequestOverrides & {
     action: 'start' | 'stop';
     path?: string;
 };
 
+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;
+};
+
+export declare type TypeTextCommandResult = {
+    kind: 'text';
+    text: string;
+    delayMs: number;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
 export declare type TypeTextOptions = ClientCommandBaseOptions & {
     text: string;
     delayMs?: number;
@@ -897,12 +2722,44 @@ export declare type TypeTextOptions = ClientCommandBaseOptions & {
 
 export declare type WaitCommandOptions = DeviceCommandBaseOptions & WaitCommandTarget;
 
+declare type WaitCommandOptions_2 = CommandContext & SelectorSnapshotOptions & {
+    target: {
+        kind: 'sleep';
+        durationMs: number;
+    } | {
+        kind: 'text';
+        text: string;
+        timeoutMs?: number | null;
+    } | {
+        kind: 'ref';
+        ref: string;
+        timeoutMs?: number | null;
+    } | {
+        kind: 'selector';
+        selector: string;
+        timeoutMs?: number | null;
+    };
+};
+
 export declare type WaitCommandResult = DaemonResponseData & {
     waitedMs?: number;
     text?: string;
     selector?: string;
 };
 
+declare type WaitCommandResult_2 = {
+    kind: 'sleep';
+    waitedMs: number;
+} | {
+    kind: 'text';
+    waitedMs: number;
+    text: string;
+} | {
+    kind: 'selector';
+    waitedMs: number;
+    selector: string;
+};
+
 declare type WaitCommandTarget = {
     durationMs: number;
     text?: never;
@@ -929,6 +2786,11 @@ declare type WaitCommandTarget = {
     timeoutMs?: number;
 });
 
+declare type WaitForTextCommandOptions = CommandContext & SelectorSnapshotOptions & {
+    text: string;
+    timeoutMs?: number | null;
+};
+
 declare type WaitSnapshotOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
 
 export { }