agent-device 0.18.0 → 0.18.1

package/dist/src/index.d.ts

@@ -1,9 +1,9 @@
-export declare type AgentDeviceClient = {
+declare type AgentDeviceClient = {
     command: AgentDeviceCommandClient;
     devices: {
         list: (options?: AgentDeviceRequestOverrides & AgentDeviceSelectionOptions) => Promise<AgentDeviceDevice[]>;
-        boot: (options?: DeviceBootOptions) => Promise<CommandRequestResult>;
-        shutdown: (options?: DeviceShutdownOptions) => Promise<CommandRequestResult>;
+        boot: (options?: DeviceBootOptions) => Promise<CommandResult<'boot'>>;
+        shutdown: (options?: DeviceShutdownOptions) => Promise<CommandResult<'shutdown'>>;
     };
     sessions: {
         list: (options?: AgentDeviceRequestOverrides) => Promise<AgentDeviceSession[]>;
@@ -11,9 +11,10 @@ export declare type AgentDeviceClient = {
         close: (options?: AgentDeviceRequestOverrides & {
             shutdown?: boolean;
         }) => Promise<SessionCloseResult>;
+        artifacts: (options?: CloudArtifactsOptions) => Promise<CloudArtifactsResult>;
     };
     apps: {
-        install: (options: AppDeployOptions) => Promise<AppDeployResult>;
+        install: (options: AppInstallOptions) => Promise<AppDeployResult>;
         reinstall: (options: AppDeployOptions) => Promise<AppDeployResult>;
         installFromSource: (options: AppInstallFromSourceOptions) => Promise<AppInstallFromSourceResult>;
         list: (options?: AppListOptions) => Promise<string[]>;
@@ -30,6 +31,7 @@ export declare type AgentDeviceClient = {
         heartbeat: (options: LeaseScopedOptions) => Promise<Lease>;
         release: (options: LeaseScopedOptions) => Promise<{
             released: boolean;
+            provider?: CloudProviderSessionResult;
         }>;
     };
     metro: {
@@ -71,6 +73,7 @@ export declare type AgentDeviceClient = {
         perf: (options?: PerfOptions) => Promise<CommandRequestResult>;
         logs: (options?: LogsOptions) => Promise<CommandRequestResult>;
         network: (options?: NetworkOptions) => Promise<CommandRequestResult>;
+        audio: (options?: AudioOptions) => Promise<CommandRequestResult>;
     };
     debug: {
         symbols: (options: DebugSymbolsOptions) => Promise<DebugSymbolsResult>;
@@ -84,7 +87,7 @@ export declare type AgentDeviceClient = {
     };
 };
 
-export declare type AgentDeviceClientConfig = RemoteConnectionProfileFields & {
+declare type AgentDeviceClientConfig = RemoteConnectionProfileFields & CloudProviderProfileFields & {
     session?: string;
     lockPolicy?: DaemonLockPolicy;
     lockPlatform?: PlatformSelector;
@@ -95,29 +98,32 @@ export declare type AgentDeviceClientConfig = RemoteConnectionProfileFields & {
     runtime?: SessionRuntimeHints;
     cwd?: string;
     debug?: boolean;
+    cost?: boolean;
+    responseLevel?: ResponseLevel;
     iosXctestrunFile?: string;
     iosXctestDerivedDataPath?: string;
     iosXctestEnvDir?: string;
 };
 
-export declare type AgentDeviceCommandClient = {
-    wait: (options: WaitCommandOptions) => Promise<WaitCommandResult>;
-    alert: (options?: AlertCommandOptions) => Promise<AlertCommandResult>;
-    appState: (options?: AppStateCommandOptions) => Promise<AppStateCommandResult>;
-    back: (options?: BackCommandOptions) => Promise<BackCommandResult>;
-    home: (options?: HomeCommandOptions) => Promise<HomeCommandResult>;
-    rotate: (options: RotateCommandOptions) => Promise<RotateCommandResult>;
-    appSwitcher: (options?: AppSwitcherCommandOptions) => Promise<AppSwitcherCommandResult>;
-    keyboard: (options?: KeyboardCommandOptions) => Promise<KeyboardCommandResult>;
-    clipboard: (options: ClipboardCommandOptions) => Promise<ClipboardCommandResult>;
+declare type AgentDeviceCommandClient = {
+    wait: (options: WaitCommandOptions) => Promise<CommandRequestResult>;
+    alert: (options?: AlertCommandOptions) => Promise<CommandRequestResult>;
+    appState: (options?: AppStateCommandOptions) => Promise<CommandResult<'appstate'>>;
+    back: (options?: BackCommandOptions) => Promise<CommandResult<'back'>>;
+    home: (options?: HomeCommandOptions) => Promise<CommandResult<'home'>>;
+    rotate: (options: RotateCommandOptions) => Promise<CommandResult<'rotate'>>;
+    appSwitcher: (options?: AppSwitcherCommandOptions) => Promise<CommandResult<'app-switcher'>>;
+    keyboard: (options?: KeyboardCommandOptions) => Promise<CommandResult<'keyboard'>>;
+    clipboard: (options: ClipboardCommandOptions) => Promise<CommandResult<'clipboard'>>;
     reactNative: (options: ReactNativeCommandOptions) => Promise<CommandRequestResult>;
+    doctor: (options?: DoctorCommandOptions) => Promise<CommandRequestResult>;
     prepare: (options: PrepareCommandOptions) => Promise<CommandRequestResult>;
-    viewport: (options: ViewportCommandOptions) => Promise<ViewportCommandResult>;
+    viewport: (options: ViewportCommandOptions) => Promise<CommandResult<'viewport'>>;
 };
 
-export declare type AgentDeviceDaemonTransport = (req: Omit<DaemonRequest, 'token'>) => Promise<DaemonResponse>;
+declare type AgentDeviceDaemonTransport = (req: Omit<DaemonRequest, 'token'>) => Promise<DaemonResponse>;
 
-export declare type AgentDeviceDevice = {
+declare type AgentDeviceDevice = {
     platform: Platform;
     target: DeviceTarget;
     kind: DeviceKind;
@@ -133,7 +139,7 @@ export declare type AgentDeviceDevice = {
     };
 };
 
-export declare type AgentDeviceIdentifiers = {
+declare type AgentDeviceIdentifiers = {
     session?: string;
     deviceId?: string;
     deviceName?: string;
@@ -144,9 +150,9 @@ export declare type AgentDeviceIdentifiers = {
     package?: string;
 };
 
-export declare type AgentDeviceRequestOverrides = Pick<AgentDeviceClientConfig, 'session' | 'lockPolicy' | 'lockPlatform' | 'requestId' | 'daemonBaseUrl' | 'daemonAuthToken' | 'daemonTransport' | 'daemonServerMode' | 'tenant' | 'sessionIsolation' | 'runId' | 'leaseId' | 'leaseBackend' | 'leaseProvider' | 'deviceKey' | 'clientId' | 'leaseTtlMs' | 'cwd' | 'debug' | 'iosXctestrunFile' | 'iosXctestDerivedDataPath' | 'iosXctestEnvDir'>;
+declare type AgentDeviceRequestOverrides = Pick<AgentDeviceClientConfig, 'session' | 'lockPolicy' | 'lockPlatform' | 'requestId' | 'daemonBaseUrl' | 'daemonAuthToken' | 'daemonTransport' | 'daemonServerMode' | 'tenant' | 'sessionIsolation' | 'runId' | 'leaseId' | 'leaseBackend' | 'leaseProvider' | 'deviceKey' | 'clientId' | 'providerApp' | 'providerOsVersion' | 'providerProject' | 'providerBuild' | 'providerSessionName' | 'awsProjectArn' | 'awsDeviceArn' | 'awsAppArn' | 'awsRegion' | 'awsInteractionMode' | 'leaseTtlMs' | 'cwd' | 'debug' | 'cost' | 'responseLevel' | 'iosXctestrunFile' | 'iosXctestDerivedDataPath' | 'iosXctestEnvDir'>;
 
-export declare type AgentDeviceSelectionOptions = {
+declare type AgentDeviceSelectionOptions = {
     platform?: PlatformSelector;
     target?: DeviceTarget;
     device?: string;
@@ -156,7 +162,7 @@ export declare type AgentDeviceSelectionOptions = {
     androidDeviceAllowlist?: string;
 };
 
-export declare type AgentDeviceSession = {
+declare type AgentDeviceSession = {
     name: string;
     createdAt: number;
     sessionStateDir?: string;
@@ -165,7 +171,7 @@ export declare type AgentDeviceSession = {
     identifiers: AgentDeviceIdentifiers;
 };
 
-export declare type AgentDeviceSessionDevice = {
+declare type AgentDeviceSessionDevice = {
     platform: Platform;
     target: DeviceTarget;
     id: string;
@@ -182,40 +188,13 @@ export declare type AgentDeviceSessionDevice = {
 
 declare const ALERT_ACTIONS: readonly ['get', 'accept', 'dismiss', 'wait'];
 
-export declare type AlertAction = (typeof ALERT_ACTIONS)[number];
+declare type AlertAction = (typeof ALERT_ACTIONS)[number];
 
-export declare type AlertCommandOptions = DeviceCommandBaseOptions & {
+declare type AlertCommandOptions = DeviceCommandBaseOptions & {
     action?: AlertAction;
     timeoutMs?: number;
 };
 
-export declare type AlertCommandResult = DaemonResponseData & {
-    kind?: 'alertStatus' | 'alertHandled' | 'alertWait';
-    action?: AlertCommandOptions['action'];
-    alert?: AlertInfo | null;
-    handled?: boolean;
-    button?: string;
-    waitedMs?: number;
-    timedOut?: boolean;
-    platform?: AlertInfo['platform'];
-    accepted?: boolean;
-    dismissed?: boolean;
-    items?: string[];
-};
-
-export declare type AlertInfo = {
-    title?: string;
-    message?: string;
-    buttons?: string[];
-    platform?: AlertPlatform;
-    source?: AlertSource;
-    packageName?: string;
-};
-
-export declare type AlertPlatform = 'android' | 'ios' | 'macos';
-
-export declare type AlertSource = 'permission' | 'native-dialog' | 'system-dialog';
-
 declare type AndroidSnapshotBackendMetadata = {
     backend: 'android-helper' | 'uiautomator-dump';
     helperVersion?: string;
@@ -243,24 +222,24 @@ declare type AndroidSnapshotHelperInstallReason = 'missing' | 'outdated' | 'forc
 
 declare type AndroidSnapshotHelperTransport = 'instrumentation' | 'persistent-session';
 
-export declare type AppCloseOptions = AgentDeviceRequestOverrides & {
+declare type AppCloseOptions = AgentDeviceRequestOverrides & {
     app?: string;
     shutdown?: boolean;
 };
 
-export declare type AppCloseResult = {
+declare type AppCloseResult = {
     session: string;
     closedApp?: string;
     shutdown?: TargetShutdownResult;
     identifiers: AgentDeviceIdentifiers;
 };
 
-export declare type AppDeployOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+declare type AppDeployOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     app: string;
     appPath: string;
 };
 
-export declare type AppDeployResult = {
+declare type AppDeployResult = {
     app: string;
     appPath: string;
     platform: Platform;
@@ -277,7 +256,7 @@ export declare class AppError extends Error {
     constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown);
 }
 
-export declare type AppErrorCode = KnownAppErrorCode | (string & {});
+declare type AppErrorCode = KnownAppErrorCode | (string & {});
 
 declare type AppErrorDetails = Record<string, unknown> & {
     hint?: string;
@@ -285,13 +264,13 @@ declare type AppErrorDetails = Record<string, unknown> & {
     logPath?: string;
 };
 
-export declare type AppInstallFromSourceOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+declare type AppInstallFromSourceOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     source: DaemonInstallSource;
     retainPaths?: boolean;
     retentionMs?: number;
 };
 
-export declare type AppInstallFromSourceResult = {
+declare type AppInstallFromSourceResult = {
     appName?: string;
     appId?: string;
     bundleId?: string;
@@ -304,11 +283,16 @@ export declare type AppInstallFromSourceResult = {
     identifiers: AgentDeviceIdentifiers;
 };
 
-export declare type AppListOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+declare type AppInstallOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+    app?: string;
+    appPath: string;
+};
+
+declare type AppListOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     appsFilter?: AppsFilter;
 };
 
-export declare type AppOpenOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+declare type AppOpenOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     app?: string;
     url?: string;
     surface?: SessionSurface;
@@ -322,7 +306,7 @@ export declare type AppOpenOptions = AgentDeviceRequestOverrides & AgentDeviceSe
     runtime?: SessionRuntimeHints;
 };
 
-export declare type AppOpenResult = {
+declare type AppOpenResult = {
     session: string;
     sessionStateDir?: string;
     runnerLogPath?: string;
@@ -336,41 +320,62 @@ export declare type AppOpenResult = {
     identifiers: AgentDeviceIdentifiers;
 };
 
-export declare type AppPushOptions = DeviceCommandBaseOptions & {
+declare type AppPushOptions = DeviceCommandBaseOptions & {
     app: string;
     payload: string | Record<string, unknown>;
 };
 
 declare type AppsFilter = 'user-installed' | 'all';
 
-export declare type AppStateCommandOptions = DeviceCommandBaseOptions;
+declare type AppStateCommandOptions = DeviceCommandBaseOptions;
 
-export declare type AppStateCommandResult = DaemonResponseData & {
-    platform?: Platform;
-    appName?: string;
+/**
+ * Closed result of the `appstate` command, grounded in the daemon handler's
+ * success returns (src/daemon/handlers/session-state.ts `handleAppStateCommand`).
+ * A discriminated union on `platform`:
+ *  - Apple (`ios` / `macos`) session state, with iOS-only device locators that
+ *    the previous hand-written mirror omitted; and
+ *  - Android foreground `package` / `activity`.
+ *
+ * The handler returns one of these fixed objects (errors take the `ok: false`
+ * path), so each branch is closed.
+ */
+declare type AppStateCommandResult = {
+    platform: 'ios' | 'macos';
+    appName: string;
     appBundleId?: string;
-    package?: string;
-    activity?: string;
-    source?: 'session';
-    surface?: SessionSurface;
+    source: 'session';
+    surface: SessionSurface;
+    /** iOS only — the session device's UDID. */
+    device_udid?: string;
+    /** iOS only — the simulator set path, or `null` when unknown. */
+    ios_simulator_device_set?: string | null;
+} | {
+    platform: 'android';
+    package: string;
+    activity: string;
 };
 
-export declare type AppSwitcherCommandOptions = DeviceCommandBaseOptions;
+declare type AppSwitcherCommandOptions = DeviceCommandBaseOptions;
 
-export declare type AppSwitcherCommandResult = CommandActionResult<'app-switcher'>;
+/** `app-switcher` — `{ action: 'app-switcher', message: 'Opened app switcher' }`. */
+declare type AppSwitcherCommandResult = {
+    action: 'app-switcher';
+    message: string;
+};
 
-export declare type AppTriggerEventOptions = DeviceCommandBaseOptions & {
+declare type AppTriggerEventOptions = DeviceCommandBaseOptions & {
     event: string;
     payload?: Record<string, unknown>;
 };
 
-export declare type ArtifactAdapter = {
+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 = {
+declare type ArtifactDescriptor = {
     kind: 'localPath';
     field: string;
     path: string;
@@ -386,33 +391,43 @@ export declare type ArtifactDescriptor = {
     metadata?: Record<string, unknown>;
 };
 
+declare type AudioOptions = AgentDeviceRequestOverrides & {
+    action?: 'probe';
+    probeAction?: 'start' | 'status' | 'stop';
+    durationMs?: number;
+    bucketMs?: number;
+};
+
 declare const BACK_MODES: readonly ['in-app', 'system'];
 
-export declare type BackCommandOptions = DeviceCommandBaseOptions & {
+declare type BackCommandOptions = DeviceCommandBaseOptions & {
     mode?: BackMode;
 };
 
-export declare type BackCommandResult = CommandActionResult<'back'> & {
-    mode?: BackMode;
+/** `back` — `{ action: 'back', mode, message: 'Back' }`; `mode` defaults to `'in-app'`. */
+declare type BackCommandResult = {
+    action: 'back';
+    mode: BackMode;
+    message: string;
 };
 
 declare type BackMode = (typeof BACK_MODES)[number];
 
-export declare type BatchRunOptions = AgentDeviceRequestOverrides & {
+declare type BatchRunOptions = AgentDeviceRequestOverrides & {
     steps: BatchStep[];
     onError?: 'stop';
     maxSteps?: number;
     out?: string;
 };
 
-export declare type BatchRunResult = Record<string, unknown> & {
+declare type BatchRunResult = Record<string, unknown> & {
     total: number;
     executed: number;
     totalDurationMs: number;
     results: BatchStepResult[];
 };
 
-export declare type BatchStep = {
+declare type BatchStep = {
     command: string;
     input: Record<string, unknown>;
     runtime?: SessionRuntimeHints;
@@ -426,26 +441,45 @@ declare type BatchStepResult = {
     durationMs: number;
 };
 
-export declare type CaptureDiffOptions = DeviceCommandBaseOptions & Pick<CaptureSnapshotOptions, 'interactiveOnly' | 'depth' | 'scope' | 'raw'> & {
+/**
+ * Closed result of the `boot` command. Mirrors the daemon handler's only
+ * success return EXACTLY (src/daemon/handlers/session-state.ts) — the fixed
+ * object literal `{ platform, target, device, id, kind, booted }`. The handler
+ * spreads nothing, so this shape is intentionally closed.
+ */
+declare type BootCommandResult = {
+    platform: Platform;
+    target: DeviceTarget;
+    /** Human-readable device name (`device.name`). */
+    device: string;
+    /** Stable device id (`device.id`). */
+    id: string;
+    kind: DeviceKind;
+    /** Always `true` on the success path. */
+    booted: true;
+};
+
+declare type CaptureDiffOptions = DeviceCommandBaseOptions & Pick<CaptureSnapshotOptions, 'interactiveOnly' | 'depth' | 'scope' | 'raw'> & {
     kind: 'snapshot';
     out?: string;
 };
 
-export declare type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
+declare type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
     path?: string;
     overlayRefs?: boolean;
     fullscreen?: boolean;
     maxSize?: number;
     stabilize?: boolean;
+    normalizeStatusBar?: boolean;
     surface?: SessionSurface;
 };
 
-export declare type CaptureScreenshotResult = ScreenshotResultData & {
+declare type CaptureScreenshotResult = ScreenshotResultData & {
     path: string;
     identifiers: AgentDeviceIdentifiers;
 };
 
-export declare type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+declare type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     interactiveOnly?: boolean;
     depth?: number;
     scope?: string;
@@ -454,7 +488,7 @@ export declare type CaptureSnapshotOptions = AgentDeviceRequestOverrides & Agent
     timeoutMs?: number;
 };
 
-export declare type CaptureSnapshotResult = {
+declare type CaptureSnapshotResult = {
     nodes: SnapshotNode[];
     truncated: boolean;
     appName?: string;
@@ -471,30 +505,130 @@ declare const CLICK_BUTTONS: readonly ['primary', 'secondary', 'middle'];
 
 declare type ClickButton = (typeof CLICK_BUTTONS)[number];
 
-export declare type ClickOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & {
+declare type ClickOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & {
     button?: ClickButton;
 };
 
-export declare type ClipboardCommandOptions = (DeviceCommandBaseOptions & {
+declare type ClipboardCommandOptions = (DeviceCommandBaseOptions & {
     action: 'read';
 }) | (DeviceCommandBaseOptions & {
     action: 'write';
     text: string;
 });
 
-export declare type ClipboardCommandResult = (DaemonResponseData & {
+/**
+ * Closed result of the `clipboard` command. Mirrors the dispatch handler's
+ * literal return EXACTLY (src/core/dispatch.ts `handleClipboardCommand`): a
+ * discriminated union on `action`. `read` returns the clipboard `text`; `write`
+ * reports the written `textLength` plus the `successText` message. The handler
+ * spreads nothing else, so each branch is closed.
+ */
+declare type ClipboardCommandResult = {
     action: 'read';
     text: string;
-}) | (DaemonResponseData & {
+} | {
     action: 'write';
     textLength: number;
-});
+    message: string;
+};
 
-declare type CommandActionResult<T extends string> = DaemonResponseData & {
-    action?: T;
+declare const CLOUD_ARTIFACT_KINDS: readonly ['video', 'appium-log', 'device-log', 'automation-log', 'provider-session', 'raw'];
+
+declare type CloudArtifact = {
+    provider: string;
+    kind: CloudArtifactKind;
+    name: string;
+    url?: string;
+    providerSessionId?: string;
+    providerArtifactId?: string;
+    contentType?: string;
+    extension?: string;
+    availability?: CloudArtifactAvailability;
+    metadata?: Record<string, unknown>;
+};
+
+declare type CloudArtifactAvailability = 'ready' | 'pending' | 'unavailable' | 'expired';
+
+declare type CloudArtifactKind = (typeof CLOUD_ARTIFACT_KINDS)[number];
+
+declare type CloudArtifactsOptions = AgentDeviceRequestOverrides & {
+    provider?: string;
+    providerSessionId?: string;
+};
+
+declare type CloudArtifactsResult = {
+    provider: string;
+    status: CloudArtifactsStatus;
+    cloudArtifacts: CloudArtifact[];
+    providerSessionId?: string;
+    message?: string;
 };
 
-export declare type CommandRequestResult = DaemonResponseData;
+declare type CloudArtifactsStatus = 'ready' | 'pending' | 'unavailable';
+
+declare type CloudProviderProfileFields = {
+    providerApp?: string;
+    providerOsVersion?: string;
+    providerProject?: string;
+    providerBuild?: string;
+    providerSessionName?: string;
+    awsProjectArn?: string;
+    awsDeviceArn?: string;
+    awsAppArn?: string;
+    awsRegion?: string;
+    awsInteractionMode?: 'INTERACTIVE' | 'NO_VIDEO' | 'VIDEO_ONLY';
+};
+
+declare type CloudProviderSessionResult = {
+    provider?: string;
+    providerSessionId?: string;
+    cloudArtifacts?: CloudArtifactsResult;
+} & Record<string, unknown>;
+
+declare type CommandRequestResult = DaemonResponseData;
+
+/**
+ * The typed result for a command named `N`. Seeded commands resolve to their
+ * contract result type from {@link CommandResultMap}; every other (unmigrated)
+ * command falls back to the untyped `Record<string, unknown>` bag. That default
+ * branch is what keeps the mapping total over every command name, so consumers
+ * can switch to `CommandResult<Name>` without first migrating every command.
+ */
+declare type CommandResult<N extends string> = N extends keyof CommandResultMap ? CommandResultMap[N] : Record<string, unknown>;
+
+/**
+ * The additive typed-result spine (ADR-0008, Phase 1 step 6).
+ *
+ * Maps a command name to the per-command result type from `src/contracts/*`. It
+ * is SEEDED, not exhaustive: a command is listed here only once its accurate,
+ * closed result shape lives in the contracts layer. Commands whose daemon
+ * handler spreads dynamic/Record data (screenshot overlays, gesture
+ * visualization, perf, logs, …) are deliberately omitted rather than given an
+ * invented shape.
+ *
+ * Batches 1-2 wired `boot` / `shutdown` / `viewport` and the navigation/action
+ * commands `home` / `back` / `rotate` / `app-switcher` alongside the seed
+ * interaction trio. Batch 3 adds `clipboard` (a closed `read`/`write` union) and
+ * `appstate` (a closed `platform` union — Apple session state with the iOS-only
+ * device locators, or Android package/activity). Batch 4 adds `keyboard` (a
+ * closed flat shape). Each entry is grounded in a
+ * re-read of the handler's literal return; see the per-type docstrings.
+ */
+declare interface CommandResultMap {
+    press: PressCommandResult;
+    fill: FillCommandResult;
+    longpress: LongPressCommandResult;
+    boot: BootCommandResult;
+    shutdown: ShutdownCommandResult;
+    viewport: ViewportCommandResult;
+    home: HomeCommandResult;
+    back: BackCommandResult;
+    rotate: RotateCommandResult;
+    'app-switcher': AppSwitcherCommandResult;
+    clipboard: ClipboardCommandResult;
+    appstate: AppStateCommandResult;
+    keyboard: KeyboardCommandResult;
+}
 
 declare type CompanionTunnelScope = {
     tenantId: string;
@@ -508,7 +642,7 @@ export declare function createAgentDeviceClient(config?: AgentDeviceClientConfig
 
 export declare function createLocalArtifactAdapter(options?: LocalArtifactAdapterOptions): ArtifactAdapter;
 
-export declare type CreateTempFileOptions = {
+declare type CreateTempFileOptions = {
     prefix: string;
     ext: string;
 };
@@ -534,6 +668,18 @@ declare type DaemonError = {
     diagnosticId?: string;
     logPath?: string;
     details?: Record<string, unknown>;
+    /**
+     * Machine-readable typed-error signals (Phase 2). Additive: present only when
+     * derivable, so the default error wire shape is unchanged.
+     *
+     * `retriable` flags a transient failure an agent should retry (vs. a
+     * deterministic one where a retry is wasted). `supportedOn` lists the platform
+     * families that DO support the command (derived from the capability matrix),
+     * surfaced on platform-mismatch errors so an agent self-corrects without a
+     * wasted round-trip.
+     */
+    retriable?: boolean;
+    supportedOn?: string;
 };
 
 declare type DaemonInstallSource = {
@@ -571,6 +717,8 @@ declare type DaemonRequest = {
 declare type DaemonRequestMeta = {
     requestId?: string;
     debug?: boolean;
+    includeCost?: boolean;
+    responseLevel?: ResponseLevel;
     cwd?: string;
     sessionExplicit?: boolean;
     tenantId?: string;
@@ -590,7 +738,7 @@ declare type DaemonRequestMeta = {
     materializationId?: string;
     lockPolicy?: DaemonLockPolicy;
     lockPlatform?: PlatformSelector;
-    requestProgress?: 'replay-test';
+    requestProgress?: 'replay-test' | 'command';
 };
 
 declare type DaemonResponse = {
@@ -603,6 +751,7 @@ declare type DaemonResponse = {
 
 declare type DaemonResponseData = Record<string, unknown> & {
     artifacts?: DaemonArtifact[];
+    cost?: ResponseCost;
 };
 
 declare type DaemonServerMode = (typeof DAEMON_SERVER_MODES)[number];
@@ -667,7 +816,7 @@ declare const DEVICE_ROTATIONS: readonly ['portrait', 'portrait-upside-down', 'l
 
 declare const DEVICE_TARGETS: readonly ['mobile', 'tv', 'desktop'];
 
-export declare type DeviceBootOptions = DeviceCommandBaseOptions & {
+declare type DeviceBootOptions = DeviceCommandBaseOptions & {
     headless?: boolean;
 };
 
@@ -677,13 +826,18 @@ declare type DeviceKind = (typeof DEVICE_KINDS)[number];
 
 declare type DeviceRotation = (typeof DEVICE_ROTATIONS)[number];
 
-export declare type DeviceShutdownOptions = DeviceCommandBaseOptions;
+declare type DeviceShutdownOptions = DeviceCommandBaseOptions;
 
 declare type DeviceTarget = (typeof DEVICE_TARGETS)[number];
 
-export declare type ElementTarget = RefTarget | SelectorTarget;
+declare type DoctorCommandOptions = DeviceCommandBaseOptions & {
+    targetApp?: string;
+    remote?: boolean;
+};
 
-export declare type FileInputRef = {
+declare type ElementTarget = RefTarget | SelectorTarget;
+
+declare type FileInputRef = {
     kind: 'path';
     path: string;
 } | {
@@ -691,7 +845,7 @@ export declare type FileInputRef = {
     id: string;
 };
 
-export declare type FileOutputRef = {
+declare type FileOutputRef = {
     kind: 'path';
     path: string;
 } | {
@@ -700,7 +854,14 @@ export declare type FileOutputRef = {
     fileName?: string;
 };
 
-export declare type FillOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
+declare type FillCommandResult = ResolvedInteractionTarget & {
+    text: string;
+    warning?: string;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type FillOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
     text: string;
     delayMs?: number;
 };
@@ -714,9 +875,9 @@ declare type FindBaseOptions = DeviceCommandBaseOptions & FindSnapshotCommandOpt
     last?: boolean;
 };
 
-export declare type FindLocator = (typeof FIND_LOCATORS)[number];
+declare type FindLocator = (typeof FIND_LOCATORS)[number];
 
-export declare type FindOptions = (FindBaseOptions & {
+declare type FindOptions = (FindBaseOptions & {
     action?: 'click' | 'focus' | 'exists' | 'getText' | 'getAttrs';
 }) | (FindBaseOptions & {
     action: 'wait';
@@ -740,21 +901,33 @@ declare type FocusOptions_2 = DeviceCommandBaseOptions & {
     x: number;
     y: number;
 };
-export { FocusOptions_2 as FocusOptions }
 
-export declare type GetOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & {
+declare type GetOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & {
     format: 'text' | 'attrs';
 };
 
-export declare type HomeCommandOptions = DeviceCommandBaseOptions;
+declare type HomeCommandOptions = DeviceCommandBaseOptions;
 
-export declare type HomeCommandResult = CommandActionResult<'home'>;
+/**
+ * Closed results of the navigation/global action commands. Each mirrors the
+ * dispatch handler's literal return EXACTLY (src/core/dispatch.ts
+ * `DISPATCH_HANDLERS`): a fixed `action` discriminant plus the always-present
+ * `successText` message (the handlers always pass a non-empty message, so it is
+ * required here). The handlers spread nothing else, so the shapes are closed —
+ * consistent with the `viewport` contract, the generic-dispatch Android
+ * dialog-recovery `warning` annotation is intentionally not part of the contract.
+ */
+/** `home` — `{ action: 'home', message: 'Home' }`. */
+declare type HomeCommandResult = {
+    action: 'home';
+    message: string;
+};
 
-export declare type InteractionTarget = PointTarget | RefTarget | SelectorTarget;
+declare type InteractionTarget = PointTarget | RefTarget | SelectorTarget;
 
 export declare function isAgentDeviceError(err: unknown): err is AppError;
 
-export declare type IsOptions = IsTextPredicateOptions | IsStatePredicateOptions;
+declare type IsOptions = IsTextPredicateOptions | IsStatePredicateOptions;
 
 declare type IsStatePredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & {
     predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected';
@@ -768,23 +941,38 @@ declare type IsTextPredicateOptions = DeviceCommandBaseOptions & SelectorSnapsho
     value: string;
 };
 
-export declare type KeyboardCommandOptions = DeviceCommandBaseOptions & {
+declare type KeyboardCommandOptions = DeviceCommandBaseOptions & {
     action?: 'status' | 'dismiss' | 'enter' | 'return';
 };
 
-export declare type KeyboardCommandResult = DaemonResponseData & {
-    platform?: 'android' | 'ios';
-    action?: 'status' | 'dismiss' | 'enter';
+/**
+ * Closed result of the `keyboard` command, grounded in the dispatch handlers'
+ * literal returns (src/core/dispatch.ts `handleAndroidKeyboardCommand` /
+ * `handleIosKeyboardCommand`).
+ *
+ * `platform` and `action` are always present; the remaining fields appear per
+ * branch (Android `status`/`dismiss` carry the keyboard-state fields; `enter`
+ * and iOS `dismiss` carry a `message`). It is kept as a flat closed shape rather
+ * than a five-way `platform`×`action` union because the per-branch field sets
+ * overlap heavily and the underlying Android keyboard-state types live in the
+ * platform layer (below the public contract). The `Record` index signature of
+ * the previous hand-written mirror is dropped, and the spurious `| null`s are
+ * removed (the handler never returns `null` for these).
+ */
+declare type KeyboardCommandResult = {
+    platform: 'android' | 'ios';
+    action: 'status' | 'dismiss' | 'enter';
     visible?: boolean;
-    inputType?: string | null;
-    inputMethodPackage?: string | null;
-    type?: string | null;
-    focusedPackage?: string | null;
-    focusedResourceId?: string | null;
-    inputOwner?: 'app' | 'ime' | 'unknown';
     wasVisible?: boolean;
     dismissed?: boolean;
     attempts?: number;
+    inputType?: string;
+    type?: 'text' | 'number' | 'email' | 'phone' | 'password' | 'datetime' | 'unknown';
+    inputMethodPackage?: string;
+    focusedPackage?: string;
+    focusedResourceId?: string;
+    inputOwner?: 'app' | 'ime' | 'unknown';
+    message?: string;
 };
 
 declare type KnownAppErrorCode = 'INVALID_ARGS' | 'DEVICE_NOT_FOUND' | 'DEVICE_IN_USE' | 'TOOL_MISSING' | 'APP_NOT_INSTALLED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_OPERATION' | 'NOT_IMPLEMENTED' | 'COMMAND_FAILED' | 'SESSION_NOT_FOUND' | 'UNAUTHORIZED' | 'AMBIGUOUS_MATCH' | 'UNKNOWN';
@@ -816,7 +1004,7 @@ declare type LeaseAllocateOptions = LeaseOptions & {
 
 declare type LeaseBackend = (typeof LEASE_BACKENDS)[number];
 
-declare type LeaseOptions = AgentDeviceRequestOverrides & {
+declare type LeaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     ttlMs?: number;
 };
 
@@ -831,7 +1019,7 @@ declare type LeaseScopedOptions = LeaseOptions & {
     clientId?: string;
 };
 
-export declare type LocalArtifactAdapterOptions = {
+declare type LocalArtifactAdapterOptions = {
     cwd?: string;
     tempDir?: string;
     rootDir?: string;
@@ -841,21 +1029,27 @@ declare const LOG_ACTION_VALUES: readonly ['path', 'start', 'stop', 'doctor', 'm
 
 declare type LogAction = (typeof LOG_ACTION_VALUES)[number];
 
-export declare type LogsOptions = AgentDeviceRequestOverrides & {
+declare type LogsOptions = AgentDeviceRequestOverrides & {
     action?: LogAction;
     message?: string;
     restart?: boolean;
 };
 
-export declare type LongPressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
+declare type LongPressCommandResult = ResolvedInteractionTarget & {
+    durationMs?: number;
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type LongPressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & {
     durationMs?: number;
 };
 
-export declare type MaterializationReleaseOptions = AgentDeviceRequestOverrides & {
+declare type MaterializationReleaseOptions = AgentDeviceRequestOverrides & {
     materializationId: string;
 };
 
-export declare type MaterializationReleaseResult = {
+declare type MaterializationReleaseResult = {
     released: boolean;
     materializationId: string;
     identifiers: AgentDeviceIdentifiers;
@@ -886,7 +1080,7 @@ declare type MetroBridgeScope = CompanionTunnelScope;
 
 declare type MetroPrepareKind = 'auto' | 'react-native' | 'expo';
 
-export declare type MetroPrepareOptions = {
+declare type MetroPrepareOptions = {
     projectRoot?: string;
     kind?: MetroPrepareKind;
     publicBaseUrl?: string;
@@ -907,16 +1101,16 @@ export declare type MetroPrepareOptions = {
     logPath?: string;
 };
 
-export declare type MetroPrepareResult = PrepareMetroRuntimeResult;
+declare type MetroPrepareResult = PrepareMetroRuntimeResult;
 
-export declare type MetroReloadOptions = {
+declare type MetroReloadOptions = {
     metroHost?: string;
     metroPort?: number;
     bundleUrl?: string;
     timeoutMs?: number;
 };
 
-export declare type MetroReloadResult = ReloadMetroResult;
+declare type MetroReloadResult = ReloadMetroResult;
 
 /** Re-export of {@link SessionRuntimeHints} under the Metro-specific alias used by public API consumers. */
 declare type MetroRuntimeHints = SessionRuntimeHints;
@@ -925,7 +1119,7 @@ declare const NETWORK_INCLUDE_MODES: readonly ['summary', 'headers', 'body', 'al
 
 declare type NetworkIncludeMode = (typeof NETWORK_INCLUDE_MODES)[number];
 
-export declare type NetworkOptions = AgentDeviceRequestOverrides & {
+declare type NetworkOptions = AgentDeviceRequestOverrides & {
     action?: 'dump' | 'log';
     limit?: number;
     include?: NetworkIncludeMode;
@@ -936,7 +1130,7 @@ export declare function normalizeAgentDeviceError(err: unknown, context?: {
     logPath?: string;
 }): NormalizedError;
 
-export declare type NormalizedError = {
+declare type NormalizedError = {
     code: string;
     message: string;
     hint?: string;
@@ -945,7 +1139,7 @@ export declare type NormalizedError = {
     details?: Record<string, unknown>;
 };
 
-export declare type OutputVisibility = 'client-visible' | 'internal';
+declare type OutputVisibility = 'client-visible' | 'internal';
 
 declare type PanOptions = DeviceCommandBaseOptions & {
     x: number;
@@ -969,7 +1163,7 @@ declare type PerfArea = (typeof PERF_AREA_VALUES)[number];
 
 declare type PerfKind = (typeof PERF_KIND_VALUES)[number];
 
-export declare type PerfOptions = DeviceCommandBaseOptions & {
+declare type PerfOptions = DeviceCommandBaseOptions & {
     area?: PerfArea;
     subject?: PerfSubject;
     action?: PerfAction;
@@ -981,9 +1175,9 @@ export declare type PerfOptions = DeviceCommandBaseOptions & {
 
 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';
+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 = DeviceCommandBaseOptions & {
+declare type PinchOptions = DeviceCommandBaseOptions & {
     scale: number;
     x?: number;
     y?: number;
@@ -997,7 +1191,7 @@ declare const PLATFORMS: readonly ['ios', 'macos', 'android', 'linux', 'web'];
 
 declare type PlatformSelector = (typeof PLATFORM_SELECTORS)[number];
 
-export declare type Point = {
+declare type Point = {
     x: number;
     y: number;
 };
@@ -1031,7 +1225,12 @@ declare type PrepareMetroRuntimeResult = {
     bridge: MetroBridgeResult | null;
 };
 
-export declare type PressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions;
+declare type PressCommandResult = ResolvedInteractionTarget & {
+    backendResult?: Record<string, unknown>;
+    message?: string;
+};
+
+declare type PressOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions;
 
 declare type PublicSnapshotCaptureAnnotations = Pick<SnapshotCaptureAnnotations, 'androidSnapshot' | 'warnings'> & {
     snapshotQuality?: SnapshotQualityVerdict;
@@ -1072,7 +1271,7 @@ declare const RECORDING_EXPORT_QUALITIES: readonly ['medium', 'high'];
 
 declare type RecordingExportQuality = (typeof RECORDING_EXPORT_QUALITIES)[number];
 
-export declare type RecordOptions = AgentDeviceRequestOverrides & {
+declare type RecordOptions = AgentDeviceRequestOverrides & {
     action: 'start' | 'stop';
     path?: string;
     fps?: number;
@@ -1081,7 +1280,7 @@ export declare type RecordOptions = AgentDeviceRequestOverrides & {
     hideTouches?: boolean;
 };
 
-export declare type Rect = {
+declare type Rect = {
     x: number;
     y: number;
     width: number;
@@ -1127,7 +1326,7 @@ declare type RepeatedPressOptions = {
     doubleTap?: boolean;
 };
 
-export declare type ReplayRunOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+declare type ReplayRunOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     path: string;
     update?: boolean;
     /** @deprecated Use backend: 'maestro'. */
@@ -1137,7 +1336,7 @@ export declare type ReplayRunOptions = AgentDeviceRequestOverrides & AgentDevice
     timeoutMs?: number;
 };
 
-export declare type ReplayTestOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
+declare type ReplayTestOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     paths: string[];
     update?: boolean;
     /** @deprecated Use backend: 'maestro'. */
@@ -1149,43 +1348,88 @@ export declare type ReplayTestOptions = AgentDeviceRequestOverrides & AgentDevic
     retries?: number;
     recordVideo?: boolean;
     artifactsDir?: string;
+    /** @deprecated Use the CLI --reporter junit:<path> or --report-junit <path>. */
     reportJunit?: string;
     shardAll?: number;
     shardSplit?: number;
 };
 
-export declare type ReservedOutputFile = {
+declare type ReservedOutputFile = {
     path: string;
     visibility: OutputVisibility;
     publish: () => Promise<ArtifactDescriptor | undefined>;
     cleanup?: () => Promise<void>;
 };
 
-export declare type ReserveOutputOptions = {
+declare type ReserveOutputOptions = {
     field: string;
     ext: string;
     requestedClientPath?: string;
     visibility?: OutputVisibility;
 };
 
-export declare type ResolvedInputFile = {
+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'>;
 
-export declare type ResolveInputOptions = {
+declare type ResolvedTarget = {
+    kind: 'selector';
+    selector: string;
+} | {
+    kind: 'ref';
+    ref: string;
+};
+
+declare type ResolveInputOptions = {
     usage: string;
     field?: string;
 };
 
-export declare type RotateCommandOptions = DeviceCommandBaseOptions & {
+declare const RESPONSE_LEVELS: readonly ['digest', 'default', 'full'];
+
+declare type ResponseCost = {
+    wallClockMs: number;
+    runnerRoundTrips: number;
+    nodeCount?: number;
+};
+
+declare type ResponseLevel = (typeof RESPONSE_LEVELS)[number];
+
+declare type RotateCommandOptions = DeviceCommandBaseOptions & {
     orientation: DeviceRotation;
 };
 
-export declare type RotateCommandResult = CommandActionResult<'rotate'> & {
-    orientation?: RotateCommandOptions['orientation'];
+/** `rotate` — `{ action: 'rotate', orientation, message: 'Rotated to <orientation>' }`. */
+declare type RotateCommandResult = {
+    action: 'rotate';
+    orientation: DeviceRotation;
+    message: string;
 };
 
 declare type RotateGestureOptions = DeviceCommandBaseOptions & {
@@ -1195,7 +1439,7 @@ declare type RotateGestureOptions = DeviceCommandBaseOptions & {
     velocity?: number;
 };
 
-export declare type ScreenshotOverlayRef = {
+declare type ScreenshotOverlayRef = {
     ref: string;
     label?: string;
     rect: Rect;
@@ -1222,7 +1466,6 @@ declare type ScrollOptions_2 = DeviceCommandBaseOptions & {
     pixels?: number;
     durationMs?: number;
 };
-export { ScrollOptions_2 as ScrollOptions }
 
 declare type SelectorSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
 
@@ -1238,9 +1481,10 @@ declare const SESSION_ISOLATION_MODES: readonly ['none', 'tenant'];
 
 declare const SESSION_SURFACES: readonly ['app', 'frontmost-app', 'desktop', 'menubar'];
 
-export declare type SessionCloseResult = {
+declare type SessionCloseResult = {
     session: string;
     shutdown?: TargetShutdownResult;
+    provider?: CloudProviderSessionResult;
     identifiers: AgentDeviceIdentifiers;
 };
 
@@ -1256,7 +1500,7 @@ declare type SessionRuntimeHints = {
 
 declare type SessionSurface = (typeof SESSION_SURFACES)[number];
 
-export declare type SettingsUpdateOptions = (DeviceCommandBaseOptions & {
+declare type SettingsUpdateOptions = (DeviceCommandBaseOptions & {
     setting: 'clear-app-state';
     state: 'clear';
     app?: string;
@@ -1287,6 +1531,23 @@ export declare type SettingsUpdateOptions = (DeviceCommandBaseOptions & {
     mode?: 'full' | 'limited';
 });
 
+/**
+ * Closed result of the `shutdown` command. Mirrors the daemon handler's success
+ * return EXACTLY (src/daemon/handlers/session-state.ts) — the fixed object
+ * literal `{ platform, target, device, id, kind, shutdown }`. The `shutdown`
+ * field is the raw {@link TargetShutdownResult} from `shutdownDeviceTarget`.
+ */
+declare type ShutdownCommandResult = {
+    platform: Platform;
+    target: DeviceTarget;
+    /** Human-readable device name (`device.name`). */
+    device: string;
+    /** Stable device id (`device.id`). */
+    id: string;
+    kind: DeviceKind;
+    shutdown: TargetShutdownResult;
+};
+
 declare type SnapshotCaptureAnalysis = {
     rawNodeCount: number;
     maxDepth: number;
@@ -1312,13 +1573,17 @@ declare type SnapshotDiagnosticsSummary = {
     warning?: string;
 };
 
-export declare type SnapshotNode = RawSnapshotNode & {
+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.
+ *
+ * Defined here (the foundational snapshot type module) rather than in
+ * snapshot-quality.ts so SnapshotNode can reference it without a cyclic import;
+ * snapshot-quality.ts (the validation logic) re-exports it for existing callers.
  */
 declare type SnapshotQualityVerdict = {
     state: 'healthy' | 'recovered' | 'sparse';
@@ -1346,16 +1611,16 @@ declare type SnapshotUnchanged = {
     scope?: string;
 };
 
-export declare type SnapshotVisibility = {
+declare type SnapshotVisibility = {
     partial: boolean;
     visibleNodeCount: number;
     totalNodeCount: number;
     reasons: SnapshotVisibilityReason[];
 };
 
-export declare type SnapshotVisibilityReason = 'offscreen-nodes' | 'scroll-hidden-above' | 'scroll-hidden-below';
+declare type SnapshotVisibilityReason = 'offscreen-nodes' | 'scroll-hidden-above' | 'scroll-hidden-below';
 
-export declare type StartupPerfSample = {
+declare type StartupPerfSample = {
     durationMs: number;
     measuredAt: string;
     method: string;
@@ -1372,7 +1637,7 @@ declare type SwipeGestureOptions = DeviceCommandBaseOptions & {
     durationMs?: number;
 };
 
-export declare type SwipeOptions = DeviceCommandBaseOptions & {
+declare type SwipeOptions = DeviceCommandBaseOptions & {
     from: {
         x: number;
         y: number;
@@ -1391,7 +1656,7 @@ declare type SwipePattern = (typeof SWIPE_PATTERNS)[number];
 
 declare type SwipePreset = (typeof SWIPE_PRESETS)[number];
 
-export declare type TargetShutdownResult = {
+declare type TargetShutdownResult = {
     success: boolean;
     exitCode: number;
     stdout: string;
@@ -1399,13 +1664,13 @@ export declare type TargetShutdownResult = {
     error?: NormalizedError;
 };
 
-export declare type TemporaryFile = {
+declare type TemporaryFile = {
     path: string;
     visibility: 'internal';
     cleanup: () => Promise<void>;
 };
 
-export declare type TraceOptions = AgentDeviceRequestOverrides & {
+declare type TraceOptions = AgentDeviceRequestOverrides & {
     action: 'start' | 'stop';
     path?: string;
 };
@@ -1422,7 +1687,7 @@ declare type TransformGestureParams = {
     durationMs?: number;
 };
 
-export declare type TypeTextOptions = DeviceCommandBaseOptions & {
+declare type TypeTextOptions = DeviceCommandBaseOptions & {
     text: string;
     delayMs?: number;
 };
@@ -1432,18 +1697,20 @@ declare type ViewportCommandOptions = DeviceCommandBaseOptions & {
     height: number;
 };
 
-declare type ViewportCommandResult = CommandRequestResult & {
+/**
+ * Closed result of the `viewport` command. Mirrors the dispatch handler's return
+ * EXACTLY (src/core/dispatch.ts `handleViewportCommand`) — `{ width, height }`
+ * plus the always-present `successText` message. The generic dispatch path
+ * returns this object unchanged (viewport has no Android dialog guard, so no
+ * `warning` is ever appended), so the shape is intentionally closed.
+ */
+declare type ViewportCommandResult = {
     width: number;
     height: number;
+    message: string;
 };
 
-export declare type WaitCommandOptions = DeviceCommandBaseOptions & WaitCommandTarget;
-
-export declare type WaitCommandResult = DaemonResponseData & {
-    waitedMs?: number;
-    text?: string;
-    selector?: string;
-};
+declare type WaitCommandOptions = DeviceCommandBaseOptions & WaitCommandTarget;
 
 declare type WaitCommandTarget = {
     durationMs: number;