agent-device 0.17.1 → 0.17.3

package/dist/src/index.d.ts

@@ -3,9 +3,11 @@ export declare type AgentDeviceClient = {
     devices: {
         list: (options?: AgentDeviceRequestOverrides & AgentDeviceSelectionOptions) => Promise<AgentDeviceDevice[]>;
         boot: (options?: DeviceBootOptions) => Promise<CommandRequestResult>;
+        shutdown: (options?: DeviceShutdownOptions) => Promise<CommandRequestResult>;
     };
     sessions: {
         list: (options?: AgentDeviceRequestOverrides) => Promise<AgentDeviceSession[]>;
+        stateDir: (options?: AgentDeviceRequestOverrides & Pick<AgentDeviceClientConfig, 'stateDir'>) => Promise<string>;
         close: (options?: AgentDeviceRequestOverrides & {
             shutdown?: boolean;
         }) => Promise<SessionCloseResult>;
@@ -70,6 +72,9 @@ export declare type AgentDeviceClient = {
         logs: (options?: LogsOptions) => Promise<CommandRequestResult>;
         network: (options?: NetworkOptions) => Promise<CommandRequestResult>;
     };
+    debug: {
+        symbols: (options: DebugSymbolsOptions) => Promise<DebugSymbolsResult>;
+    };
     recording: {
         record: (options: RecordOptions) => Promise<CommandRequestResult>;
         trace: (options: TraceOptions) => Promise<CommandRequestResult>;
@@ -87,7 +92,7 @@ export declare type AgentDeviceClientConfig = {
     stateDir?: string;
     daemonBaseUrl?: string;
     daemonAuthToken?: string;
-    daemonTransport?: DaemonTransportMode;
+    daemonTransport?: DaemonTransportPreference;
     daemonServerMode?: DaemonServerMode;
     tenant?: string;
     sessionIsolation?: SessionIsolationMode;
@@ -178,10 +183,12 @@ export declare type AgentDeviceSessionDevice = {
     };
 };
 
-export declare type AlertAction = 'get' | 'accept' | 'dismiss' | 'wait';
+declare const ALERT_ACTIONS: readonly ["get", "accept", "dismiss", "wait"];
+
+export declare type AlertAction = (typeof ALERT_ACTIONS)[number];
 
 export declare type AlertCommandOptions = DeviceCommandBaseOptions & {
-    action?: 'get' | 'accept' | 'dismiss' | 'wait';
+    action?: AlertAction;
     timeoutMs?: number;
 };
 
@@ -216,23 +223,29 @@ declare type AndroidSnapshotBackendMetadata = {
     backend: 'android-helper' | 'uiautomator-dump';
     helperVersion?: string;
     helperApiVersion?: string;
-    helperTransport?: 'instrumentation' | 'persistent-session';
+    helperTransport?: AndroidSnapshotHelperTransport;
     helperSessionReused?: boolean;
     fallbackReason?: string;
-    installReason?: 'missing' | 'outdated' | 'forced' | 'current' | 'skipped';
+    installReason?: AndroidSnapshotHelperInstallReason;
     waitForIdleTimeoutMs?: number;
     waitForIdleQuietMs?: number;
     timeoutMs?: number;
     maxDepth?: number;
     maxNodes?: number;
     rootPresent?: boolean;
-    captureMode?: 'interactive-windows' | 'active-window';
+    captureMode?: AndroidSnapshotCaptureMode;
     windowCount?: number;
     nodeCount?: number;
     helperTruncated?: boolean;
     elapsedMs?: number;
 };
 
+declare type AndroidSnapshotCaptureMode = 'interactive-windows' | 'active-window';
+
+declare type AndroidSnapshotHelperInstallReason = 'missing' | 'outdated' | 'forced' | 'current' | 'skipped';
+
+declare type AndroidSnapshotHelperTransport = 'instrumentation' | 'persistent-session';
+
 export declare type AppCloseOptions = AgentDeviceRequestOverrides & {
     app?: string;
     shutdown?: boolean;
@@ -294,8 +307,6 @@ export declare type AppInstallFromSourceResult = {
     identifiers: AgentDeviceIdentifiers;
 };
 
-declare type ApplePlatform = 'ios' | 'macos';
-
 export declare type AppListOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     appsFilter?: AppsFilter;
 };
@@ -303,12 +314,13 @@ export declare type AppListOptions = AgentDeviceRequestOverrides & AgentDeviceSe
 export declare type AppOpenOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     app?: string;
     url?: string;
-    surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
+    surface?: SessionSurface;
     activity?: string;
     launchConsole?: string;
     launchArgs?: string[];
     relaunch?: boolean;
     saveScript?: boolean | string;
+    deviceHub?: boolean;
     noRecord?: boolean;
     runtime?: SessionRuntimeHints;
 };
@@ -327,7 +339,7 @@ export declare type AppOpenResult = {
     identifiers: AgentDeviceIdentifiers;
 };
 
-export declare type AppPushOptions = ClientCommandBaseOptions & {
+export declare type AppPushOptions = DeviceCommandBaseOptions & {
     app: string;
     payload: string | Record<string, unknown>;
 };
@@ -343,14 +355,14 @@ export declare type AppStateCommandResult = DaemonResponseData & {
     package?: string;
     activity?: string;
     source?: 'session';
-    surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
+    surface?: SessionSurface;
 };
 
 export declare type AppSwitcherCommandOptions = DeviceCommandBaseOptions;
 
 export declare type AppSwitcherCommandResult = CommandActionResult<'app-switcher'>;
 
-export declare type AppTriggerEventOptions = ClientCommandBaseOptions & {
+export declare type AppTriggerEventOptions = DeviceCommandBaseOptions & {
     event: string;
     payload?: Record<string, unknown>;
 };
@@ -377,14 +389,18 @@ export declare type ArtifactDescriptor = {
     metadata?: Record<string, unknown>;
 };
 
+declare const BACK_MODES: readonly ["in-app", "system"];
+
 export declare type BackCommandOptions = DeviceCommandBaseOptions & {
-    mode?: 'in-app' | 'system';
+    mode?: BackMode;
 };
 
 export declare type BackCommandResult = CommandActionResult<'back'> & {
-    mode?: 'in-app' | 'system';
+    mode?: BackMode;
 };
 
+declare type BackMode = (typeof BACK_MODES)[number];
+
 export declare type BatchRunOptions = AgentDeviceRequestOverrides & {
     steps: BatchStep[];
     onError?: 'stop';
@@ -398,7 +414,7 @@ export declare type BatchStep = {
     runtime?: unknown;
 };
 
-export declare type CaptureDiffOptions = ClientCommandBaseOptions & Pick<CaptureSnapshotOptions, 'interactiveOnly' | 'compact' | 'depth' | 'scope' | 'raw'> & {
+export declare type CaptureDiffOptions = DeviceCommandBaseOptions & Pick<CaptureSnapshotOptions, 'interactiveOnly' | 'depth' | 'scope' | 'raw'> & {
     kind: 'snapshot';
     out?: string;
 };
@@ -409,7 +425,7 @@ export declare type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
     fullscreen?: boolean;
     maxSize?: number;
     stabilize?: boolean;
-    surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
+    surface?: SessionSurface;
 };
 
 export declare type CaptureScreenshotResult = {
@@ -420,7 +436,6 @@ export declare type CaptureScreenshotResult = {
 
 export declare type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     interactiveOnly?: boolean;
-    compact?: boolean;
     depth?: number;
     scope?: string;
     raw?: boolean;
@@ -434,19 +449,19 @@ export declare type CaptureSnapshotResult = {
     appName?: string;
     appBundleId?: string;
     visibility?: SnapshotVisibility;
-    androidSnapshot?: AndroidSnapshotBackendMetadata;
-    warnings?: string[];
     unchanged?: SnapshotUnchanged;
     identifiers: AgentDeviceIdentifiers;
-};
+} & PublicSnapshotCaptureAnnotations;
 
 export declare function centerOfRect(rect: Rect): Point;
 
-export declare type ClickOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & {
-    button?: 'primary' | 'secondary' | 'middle';
-};
+declare const CLICK_BUTTONS: readonly ["primary", "secondary", "middle"];
+
+declare type ClickButton = (typeof CLICK_BUTTONS)[number];
 
-declare type ClientCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
+export declare type ClickOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & {
+    button?: ClickButton;
+};
 
 export declare type ClipboardCommandOptions = (DeviceCommandBaseOptions & {
     action: 'read';
@@ -486,6 +501,12 @@ export declare type CreateTempFileOptions = {
     ext: string;
 };
 
+declare const DAEMON_LOCK_POLICIES: readonly ["reject", "strip"];
+
+declare const DAEMON_SERVER_MODES: readonly ["socket", "http", "dual"];
+
+declare const DAEMON_TRANSPORT_PREFERENCES: readonly ["auto", "socket", "http"];
+
 declare type DaemonArtifact = {
     field: string;
     artifactId?: string;
@@ -523,7 +544,7 @@ declare type DaemonInstallSource = {
     artifactName: string;
 }));
 
-declare type DaemonLockPolicy = 'reject' | 'strip';
+declare type DaemonLockPolicy = (typeof DAEMON_LOCK_POLICIES)[number];
 
 declare type DaemonRequest = {
     token?: string;
@@ -545,7 +566,7 @@ declare type DaemonRequestMeta = {
     leaseId?: string;
     leaseTtlMs?: number;
     leaseBackend?: LeaseBackend;
-    sessionIsolation?: 'none' | 'tenant';
+    sessionIsolation?: SessionIsolationMode;
     uploadedArtifactId?: string;
     clientArtifactPaths?: Record<string, string>;
     installSource?: DaemonInstallSource;
@@ -553,7 +574,7 @@ declare type DaemonRequestMeta = {
     materializedPathRetentionMs?: number;
     materializationId?: string;
     lockPolicy?: DaemonLockPolicy;
-    lockPlatform?: 'ios' | 'macos' | 'android' | 'linux' | 'apple';
+    lockPlatform?: PlatformSelector;
     requestProgress?: 'replay-test';
 };
 
@@ -569,19 +590,81 @@ declare type DaemonResponseData = Record<string, unknown> & {
     artifacts?: DaemonArtifact[];
 };
 
-declare type DaemonServerMode = 'socket' | 'http' | 'dual';
+declare type DaemonServerMode = (typeof DAEMON_SERVER_MODES)[number];
+
+declare type DaemonTransportPreference = (typeof DAEMON_TRANSPORT_PREFERENCES)[number];
 
-declare type DaemonTransportMode = 'auto' | 'socket' | 'http';
+declare type DebugSymbolsCrashFrame = {
+    index: number;
+    image: string;
+    address: string;
+    symbol?: string;
+};
 
-export declare type DeviceBootOptions = ClientCommandBaseOptions & {
+declare type DebugSymbolsCrashSummary = {
+    format: 'ips' | 'text';
+    appName?: string;
+    bundleId?: string;
+    version?: string;
+    incident?: string;
+    timestamp?: string;
+    exceptionType?: string;
+    exceptionCodes?: string;
+    terminationReason?: string;
+    crashedThread?: number;
+    topFrames: DebugSymbolsCrashFrame[];
+    findings: string[];
+};
+
+declare type DebugSymbolsImage = {
+    name: string;
+    uuid: string;
+    arch?: string;
+    dsymPath: string;
+    binaryPath: string;
+};
+
+declare type DebugSymbolsOptions = {
+    action?: 'symbols';
+    artifact: string;
+    dsym?: string;
+    searchPath?: string;
+    out?: string;
+    cwd?: string;
+};
+
+declare type DebugSymbolsResult = {
+    kind: 'debugSymbols';
+    platform: 'apple';
+    artifactPath: string;
+    outPath: string;
+    crash: DebugSymbolsCrashSummary;
+    matchedImages: DebugSymbolsImage[];
+    symbolicatedFrames: number;
+    skippedImages: number;
+    warnings?: string[];
+    message: string;
+};
+
+declare const DEVICE_KINDS: readonly ["simulator", "emulator", "device"];
+
+declare const DEVICE_ROTATIONS: readonly ["portrait", "portrait-upside-down", "landscape-left", "landscape-right"];
+
+declare const DEVICE_TARGETS: readonly ["mobile", "tv", "desktop"];
+
+export declare type DeviceBootOptions = DeviceCommandBaseOptions & {
     headless?: boolean;
 };
 
 declare type DeviceCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
 
-declare type DeviceKind = 'simulator' | 'emulator' | 'device';
+declare type DeviceKind = (typeof DEVICE_KINDS)[number];
 
-declare type DeviceTarget = 'mobile' | 'tv' | 'desktop';
+declare type DeviceRotation = (typeof DEVICE_ROTATIONS)[number];
+
+export declare type DeviceShutdownOptions = DeviceCommandBaseOptions;
+
+declare type DeviceTarget = (typeof DEVICE_TARGETS)[number];
 
 export declare type ElementTarget = RefTarget | SelectorTarget;
 
@@ -602,19 +685,21 @@ export declare type FileOutputRef = {
     fileName?: string;
 };
 
-export declare type FillOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
+export declare type FillOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
     text: string;
     delayMs?: number;
 };
 
-declare type FindBaseOptions = ClientCommandBaseOptions & FindSnapshotCommandOptions & {
+declare const FIND_LOCATORS: readonly ["any", "text", "label", "value", "role", "id"];
+
+declare type FindBaseOptions = DeviceCommandBaseOptions & FindSnapshotCommandOptions & {
     locator?: FindLocator;
     query: string;
     first?: boolean;
     last?: boolean;
 };
 
-export declare type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
+export declare type FindLocator = (typeof FIND_LOCATORS)[number];
 
 export declare type FindOptions = (FindBaseOptions & {
     action?: 'click' | 'focus' | 'exists' | 'getText' | 'getAttrs';
@@ -628,21 +713,21 @@ export declare type FindOptions = (FindBaseOptions & {
 
 declare type FindSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'raw'>;
 
-declare type FlingOptions = ClientCommandBaseOptions & {
-    direction: 'up' | 'down' | 'left' | 'right';
+declare type FlingOptions = DeviceCommandBaseOptions & {
+    direction: ScrollDirection;
     x: number;
     y: number;
     distance?: number;
     durationMs?: number;
 };
 
-declare type FocusOptions_2 = ClientCommandBaseOptions & {
+declare type FocusOptions_2 = DeviceCommandBaseOptions & {
     x: number;
     y: number;
 };
 export { FocusOptions_2 as FocusOptions }
 
-export declare type GetOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & {
+export declare type GetOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & {
     format: 'text' | 'attrs';
 };
 
@@ -656,13 +741,13 @@ export declare function isAgentDeviceError(err: unknown): err is AppError;
 
 export declare type IsOptions = IsTextPredicateOptions | IsStatePredicateOptions;
 
-declare type IsStatePredicateOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & {
+declare type IsStatePredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & {
     predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected';
     selector: string;
     value?: never;
 };
 
-declare type IsTextPredicateOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & {
+declare type IsTextPredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & {
     predicate: 'text';
     selector: string;
     value: string;
@@ -699,13 +784,15 @@ declare type Lease = {
     expiresAt?: number;
 };
 
+declare const LEASE_BACKENDS: readonly ["ios-simulator", "ios-instance", "android-instance"];
+
 declare type LeaseAllocateOptions = LeaseOptions & {
     tenant: string;
     runId: string;
     leaseBackend?: LeaseBackend;
 };
 
-declare type LeaseBackend = 'ios-simulator' | 'ios-instance' | 'android-instance';
+declare type LeaseBackend = (typeof LEASE_BACKENDS)[number];
 
 declare type LeaseOptions = AgentDeviceRequestOverrides & {
     ttlMs?: number;
@@ -723,13 +810,17 @@ export declare type LocalArtifactAdapterOptions = {
     rootDir?: string;
 };
 
+declare const LOG_ACTION_VALUES: readonly ["path", "start", "stop", "doctor", "mark", "clear"];
+
+declare type LogAction = (typeof LOG_ACTION_VALUES)[number];
+
 export declare type LogsOptions = AgentDeviceRequestOverrides & {
-    action?: 'path' | 'start' | 'stop' | 'doctor' | 'mark' | 'clear';
+    action?: LogAction;
     message?: string;
     restart?: boolean;
 };
 
-export declare type LongPressOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
+export declare type LongPressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
     durationMs?: number;
 };
 
@@ -803,10 +894,14 @@ export declare type MetroReloadResult = ReloadMetroResult;
 /** Re-export of {@link SessionRuntimeHints} under the Metro-specific alias used by public API consumers. */
 declare type MetroRuntimeHints = SessionRuntimeHints;
 
+declare const NETWORK_INCLUDE_MODES: readonly ["summary", "headers", "body", "all"];
+
+declare type NetworkIncludeMode = (typeof NETWORK_INCLUDE_MODES)[number];
+
 export declare type NetworkOptions = AgentDeviceRequestOverrides & {
     action?: 'dump' | 'log';
     limit?: number;
-    include?: 'summary' | 'headers' | 'body' | 'all';
+    include?: NetworkIncludeMode;
 };
 
 export declare function normalizeAgentDeviceError(err: unknown, context?: {
@@ -825,7 +920,7 @@ export declare type NormalizedError = {
 
 export declare type OutputVisibility = 'client-visible' | 'internal';
 
-declare type PanOptions = ClientCommandBaseOptions & {
+declare type PanOptions = DeviceCommandBaseOptions & {
     x: number;
     y: number;
     dx: number;
@@ -833,30 +928,47 @@ declare type PanOptions = ClientCommandBaseOptions & {
     durationMs?: number;
 };
 
-declare const PERF_ACTION_VALUES: readonly ["sample"];
+declare const PERF_ACTION_VALUES: readonly ["sample", "snapshot", "start", "stop", "report"];
 
-declare const PERF_AREA_VALUES: readonly ["metrics", "frames"];
+declare const PERF_AREA_VALUES: readonly ["metrics", "frames", "memory", "cpu", "trace"];
+
+declare const PERF_KIND_VALUES: readonly ["xctrace", "simpleperf", "perfetto", "android-hprof", "memgraph"];
+
+declare const PERF_SUBJECT_VALUES: readonly ["profile"];
 
 declare type PerfAction = (typeof PERF_ACTION_VALUES)[number];
 
 declare type PerfArea = (typeof PERF_AREA_VALUES)[number];
 
-export declare type PerfOptions = ClientCommandBaseOptions & {
+declare type PerfKind = (typeof PERF_KIND_VALUES)[number];
+
+export declare type PerfOptions = DeviceCommandBaseOptions & {
     area?: PerfArea;
+    subject?: PerfSubject;
     action?: PerfAction;
+    kind?: PerfKind;
+    template?: string;
+    out?: string;
+    tracePath?: string;
 };
 
+declare type PerfSubject = (typeof PERF_SUBJECT_VALUES)[number];
+
 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';
 
-export declare type PinchOptions = ClientCommandBaseOptions & {
+export declare type PinchOptions = DeviceCommandBaseOptions & {
     scale: number;
     x?: number;
     y?: number;
 };
 
-declare type Platform = ApplePlatform | 'android' | 'linux';
+declare type Platform = (typeof PLATFORMS)[number];
+
+declare const PLATFORM_SELECTORS: readonly ["ios", "macos", "android", "linux", "apple"];
 
-declare type PlatformSelector = Platform | 'apple';
+declare const PLATFORMS: readonly ["ios", "macos", "android", "linux"];
+
+declare type PlatformSelector = (typeof PLATFORM_SELECTORS)[number];
 
 export declare type Point = {
     x: number;
@@ -871,7 +983,7 @@ declare type PointTarget = {
     label?: never;
 };
 
-declare type PrepareCommandOptions = ClientCommandBaseOptions & {
+declare type PrepareCommandOptions = DeviceCommandBaseOptions & {
     action: 'ios-runner';
     timeoutMs?: number;
 };
@@ -892,7 +1004,11 @@ declare type PrepareMetroRuntimeResult = {
     bridge: MetroBridgeResult | null;
 };
 
-export declare type PressOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions;
+export declare type PressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions;
+
+declare type PublicSnapshotCaptureAnnotations = Pick<SnapshotCaptureAnnotations, 'androidSnapshot' | 'warnings'> & {
+    snapshotQuality?: SnapshotQualityVerdict;
+};
 
 declare type RawSnapshotNode = {
     index: number;
@@ -921,7 +1037,7 @@ declare type RawSnapshotNode = {
     presentationHints?: string[];
 };
 
-declare type ReactNativeCommandOptions = ClientCommandBaseOptions & {
+declare type ReactNativeCommandOptions = DeviceCommandBaseOptions & {
     action: 'dismiss-overlay';
 };
 
@@ -1019,14 +1135,14 @@ export declare type ResolveInputOptions = {
 };
 
 export declare type RotateCommandOptions = DeviceCommandBaseOptions & {
-    orientation: 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
+    orientation: DeviceRotation;
 };
 
 export declare type RotateCommandResult = CommandActionResult<'rotate'> & {
     orientation?: RotateCommandOptions['orientation'];
 };
 
-declare type RotateGestureOptions = ClientCommandBaseOptions & {
+declare type RotateGestureOptions = DeviceCommandBaseOptions & {
     degrees: number;
     x?: number;
     y?: number;
@@ -1041,8 +1157,16 @@ export declare type ScreenshotOverlayRef = {
     center: Point;
 };
 
-declare type ScrollOptions_2 = ClientCommandBaseOptions & {
-    direction: 'up' | 'down' | 'left' | 'right' | 'top' | 'bottom';
+declare const SCROLL_DIRECTIONS: readonly ["up", "down", "left", "right"];
+
+declare const SCROLL_INPUT_DIRECTIONS: readonly ["up", "down", "left", "right", "top", "bottom"];
+
+declare type ScrollDirection = (typeof SCROLL_DIRECTIONS)[number];
+
+declare type ScrollInputDirection = (typeof SCROLL_INPUT_DIRECTIONS)[number];
+
+declare type ScrollOptions_2 = DeviceCommandBaseOptions & {
+    direction: ScrollInputDirection;
     amount?: number;
     pixels?: number;
 };
@@ -1058,13 +1182,17 @@ declare type SelectorTarget = {
     label?: never;
 };
 
+declare const SESSION_ISOLATION_MODES: readonly ["none", "tenant"];
+
+declare const SESSION_SURFACES: readonly ["app", "frontmost-app", "desktop", "menubar"];
+
 export declare type SessionCloseResult = {
     session: string;
     shutdown?: Record<string, unknown>;
     identifiers: AgentDeviceIdentifiers;
 };
 
-declare type SessionIsolationMode = 'none' | 'tenant';
+declare type SessionIsolationMode = (typeof SESSION_ISOLATION_MODES)[number];
 
 declare type SessionRuntimeHints = {
     platform?: 'ios' | 'android';
@@ -1074,41 +1202,76 @@ declare type SessionRuntimeHints = {
     launchUrl?: string;
 };
 
-export declare type SettingsUpdateOptions = (ClientCommandBaseOptions & {
+declare type SessionSurface = (typeof SESSION_SURFACES)[number];
+
+export declare type SettingsUpdateOptions = (DeviceCommandBaseOptions & {
     setting: 'clear-app-state';
     state: 'clear';
     app?: string;
-}) | (ClientCommandBaseOptions & {
+}) | (DeviceCommandBaseOptions & {
     setting: 'wifi' | 'airplane' | 'location';
     state: 'on' | 'off';
-}) | (ClientCommandBaseOptions & {
+}) | (DeviceCommandBaseOptions & {
     setting: 'location';
     state: 'set';
     latitude: number;
     longitude: number;
-}) | (ClientCommandBaseOptions & {
+}) | (DeviceCommandBaseOptions & {
     setting: 'animations';
     state: 'on' | 'off';
-}) | (ClientCommandBaseOptions & {
+}) | (DeviceCommandBaseOptions & {
     setting: 'appearance';
     state: 'light' | 'dark' | 'toggle';
-}) | (ClientCommandBaseOptions & {
+}) | (DeviceCommandBaseOptions & {
     setting: 'faceid' | 'touchid';
     state: 'match' | 'nonmatch' | 'enroll' | 'unenroll';
-}) | (ClientCommandBaseOptions & {
+}) | (DeviceCommandBaseOptions & {
     setting: 'fingerprint';
     state: 'match' | 'nonmatch';
-}) | (ClientCommandBaseOptions & {
+}) | (DeviceCommandBaseOptions & {
     setting: 'permission';
     state: 'grant' | 'deny' | 'reset';
     permission: PermissionTarget;
     mode?: 'full' | 'limited';
 });
 
+declare type SnapshotCaptureAnalysis = {
+    rawNodeCount: number;
+    maxDepth: number;
+};
+
+declare type SnapshotCaptureAnnotations = {
+    analysis?: SnapshotCaptureAnalysis;
+    androidSnapshot?: AndroidSnapshotBackendMetadata;
+    freshness?: SnapshotCaptureFreshness;
+    quality?: SnapshotQualityVerdict;
+    warnings?: string[];
+};
+
+declare type SnapshotCaptureFreshness = {
+    action: string;
+    retryCount: number;
+    staleAfterRetries: boolean;
+    reason?: 'empty-interactive' | 'sharp-drop' | 'stuck-route';
+};
+
 export declare type SnapshotNode = RawSnapshotNode & {
     ref: string;
 };
 
+/**
+ * Structured quality verdict computed once by the iOS runner's snapshot capture plan.
+ * The daemon renders it; it never re-derives degradation from node shapes.
+ */
+declare type SnapshotQualityVerdict = {
+    state: 'healthy' | 'recovered' | 'sparse';
+    backend: 'tree' | 'queries' | 'private-ax';
+    reason?: string;
+    reasonCode?: 'ax-rejected' | 'sparse-tree' | 'budget' | 'no-nodes' | 'capture-failed';
+    effectiveDepth?: number;
+    collapsedLeafIndexes?: number[];
+};
+
 declare type SnapshotUnchanged = {
     ageMs: number;
     nodeCount: number;
@@ -1133,12 +1296,16 @@ export declare type StartupPerfSample = {
     appBundleId?: string;
 };
 
-declare type SwipeGestureOptions = ClientCommandBaseOptions & {
-    preset: 'left' | 'right' | 'left-edge' | 'right-edge';
+declare const SWIPE_PATTERNS: readonly ["one-way", "ping-pong"];
+
+declare const SWIPE_PRESETS: readonly ["left", "right", "left-edge", "right-edge"];
+
+declare type SwipeGestureOptions = DeviceCommandBaseOptions & {
+    preset: SwipePreset;
     durationMs?: number;
 };
 
-export declare type SwipeOptions = ClientCommandBaseOptions & {
+export declare type SwipeOptions = DeviceCommandBaseOptions & {
     from: {
         x: number;
         y: number;
@@ -1150,9 +1317,13 @@ export declare type SwipeOptions = ClientCommandBaseOptions & {
     durationMs?: number;
     count?: number;
     pauseMs?: number;
-    pattern?: 'one-way' | 'ping-pong';
+    pattern?: SwipePattern;
 };
 
+declare type SwipePattern = (typeof SWIPE_PATTERNS)[number];
+
+declare type SwipePreset = (typeof SWIPE_PRESETS)[number];
+
 export declare type TemporaryFile = {
     path: string;
     visibility: 'internal';
@@ -1164,7 +1335,9 @@ export declare type TraceOptions = AgentDeviceRequestOverrides & {
     path?: string;
 };
 
-declare type TransformGestureOptions = ClientCommandBaseOptions & {
+declare type TransformGestureOptions = DeviceCommandBaseOptions & TransformGestureParams;
+
+declare type TransformGestureParams = {
     x: number;
     y: number;
     dx: number;
@@ -1174,7 +1347,7 @@ declare type TransformGestureOptions = ClientCommandBaseOptions & {
     durationMs?: number;
 };
 
-export declare type TypeTextOptions = ClientCommandBaseOptions & {
+export declare type TypeTextOptions = DeviceCommandBaseOptions & {
     text: string;
     delayMs?: number;
 };
@@ -1193,19 +1366,19 @@ declare type WaitCommandTarget = {
     ref?: never;
     selector?: never;
     timeoutMs?: never;
-} | (WaitSnapshotOptions & {
+} | (SelectorSnapshotCommandOptions & {
     text: string;
     durationMs?: never;
     ref?: never;
     selector?: never;
     timeoutMs?: number;
-}) | (WaitSnapshotOptions & {
+}) | (SelectorSnapshotCommandOptions & {
     ref: string;
     durationMs?: never;
     text?: never;
     selector?: never;
     timeoutMs?: number;
-}) | (WaitSnapshotOptions & {
+}) | (SelectorSnapshotCommandOptions & {
     selector: string;
     durationMs?: never;
     text?: never;
@@ -1213,6 +1386,4 @@ declare type WaitCommandTarget = {
     timeoutMs?: number;
 });
 
-declare type WaitSnapshotOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
-
 export { }