agent-device 0.20.3 → 0.20.4

package/dist/src/index.d.ts

@@ -1,55 +1,169 @@
-import { A as SnapshotNode, B as DeviceTarget, C as normalizeAgentDeviceError, F as SnapshotVisibility, H as PlatformSelector, I as centerOfRect, L as AppleOS, P as SnapshotUnchanged, S as isAgentDeviceError, U as PublicPlatform, _ as SessionIsolationMode, a as DaemonLockPolicy, b as NormalizedError, c as DaemonResponseData, g as ResponseLevel, i as DaemonInstallSource, m as NetworkIncludeMode, o as DaemonRequest, p as LeaseBackend, r as DaemonError, s as DaemonResponse, t as DaemonArtifact, v as SessionRuntimeHints, y as AppError, z as DeviceKind } from "./sdk-contracts.js";
+import { A as SnapshotNode, B as DeviceTarget, C as normalizeAgentDeviceError, F as SnapshotVisibility, H as PlatformSelector, I as centerOfRect, L as AppleOS, M as SnapshotQualityVerdict, P as SnapshotUnchanged, S as isAgentDeviceError, U as PublicPlatform, _ as SessionRuntimeHints, a as DaemonRequest, b as NormalizedError, f as LeaseBackend, g as SessionIsolationMode, h as ResponseLevel, i as DaemonLockPolicy, o as DaemonResponse, p as NetworkIncludeMode, r as DaemonInstallSource, s as DaemonResponseData, t as DaemonArtifact, v as AppError, y as DaemonError, z as DeviceKind } from "./sdk-contracts.js";
 import { c as ScrollDirection, d as SwipePreset, f as TransformGestureParams, l as ScrollInputDirection, s as GesturePointerCount, u as SwipePattern } from "./sdk-android-adb.js";
-import { t as AppsFilter } from "./sdk-app-inventory.js";
+import { c as SnapshotDiagnosticsSummary, d as DeviceRotation, f as BackMode, i as AndroidSnapshotBackendMetadata, l as SessionSurface, o as FindLocator, r as CloudProviderSessionResult, s as ScreenshotResultData, t as AgentArtifactsResult, u as TvRemoteButton } from "./cloud-artifacts.js";
+import { a as LongPressCommandResponseData, i as FindCommandResponseData, o as PressCommandResponseData, r as FillCommandResponseData, s as ClickButton, t as ClickCommandResponseData } from "./interaction.js";
+import { t as AppsFilter } from "./app-inventory.js";
 import { t as BatchRunResult } from "./sdk-batch-runner.js";
-import { r as FindLocator } from "./sdk-finders.js";
 import { a as RemoteConnectionProfileFields, c as MetroPrepareResult, i as CloudProviderProfileFields, l as MetroReloadOptions, s as MetroPrepareOptions, u as MetroReloadResult } from "./sdk-remote-config.js";
-import { c as RecordingExportQuality, d as PublicSnapshotCaptureAnnotations, i as AgentArtifactsResult, l as ScreenshotResultData, m as JsonObject, n as DeviceRotation, o as CloudProviderSessionResult, p as SessionSurface, r as AlertAction, s as BackMode, t as TvRemoteButton, u as SnapshotDiagnosticsSummary } from "./tv-remote.js";
-import { t as ClickButton } from "./click-button.js";
-import { a as LongPressCommandResponseData, i as FindCommandResponseData, o as PressCommandResponseData, r as FillCommandResponseData, t as ClickCommandResponseData } from "./interaction.js";
 import { p as createLocalArtifactAdapter } from "./sdk-io.js";
-//#region src/contracts/client-connection.d.ts
-type AgentDeviceDaemonTransport = (req: Omit<DaemonRequest, 'token'>) => Promise<DaemonResponse>;
-type AgentDeviceClientConfig = RemoteConnectionProfileFields & CloudProviderProfileFields & {
-  session?: string;
-  lockPolicy?: DaemonLockPolicy;
-  lockPlatform?: PlatformSelector;
-  requestId?: string;
-  sessionIsolation?: SessionIsolationMode;
-  leaseBackend?: LeaseBackend;
-  leaseTtlMs?: number;
-  runtime?: SessionRuntimeHints;
-  cwd?: string;
-  debug?: boolean;
-  cost?: boolean;
-  responseLevel?: ResponseLevel;
-  iosXctestrunFile?: string;
-  iosXctestDerivedDataPath?: string;
-  iosXctestEnvDir?: string;
+//#region packages/contracts/src/alert-contract.d.ts
+declare const ALERT_ACTIONS: readonly ['get', 'accept', 'dismiss', 'wait'];
+type AlertAction = (typeof ALERT_ACTIONS)[number];
+//#endregion
+//#region packages/contracts/src/clipboard.d.ts
+/**
+ * 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.
+ */
+type ClipboardCommandResult = {
+  action: 'read';
+  text: string;
+} | {
+  action: 'write';
+  textLength: number;
+  message: string;
 };
-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'>;
-type AgentDeviceIdentifiers = {
-  session?: string;
-  deviceId?: string;
-  deviceName?: string;
-  udid?: string;
-  serial?: string;
-  appId?: string;
-  appBundleId?: string;
-  package?: string;
+//#endregion
+//#region packages/contracts/src/keyboard.d.ts
+/**
+ * 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).
+ */
+type KeyboardCommandResult = {
+  platform: 'android' | 'ios';
+  action: 'status' | 'dismiss' | 'enter';
+  visible?: boolean;
+  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;
 };
-type AgentDeviceSelectionOptions = {
-  platform?: PlatformSelector;
-  target?: DeviceTarget;
-  device?: string;
-  udid?: string;
-  serial?: string;
-  iosSimulatorDeviceSet?: string;
-  androidDeviceAllowlist?: string;
+//#endregion
+//#region packages/contracts/src/navigation.d.ts
+/**
+ * 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' }`. */
+type HomeCommandResult = {
+  action: 'home';
+  message: string;
+};
+/** `back` — `{ action: 'back', mode, message: 'Back' }`; `mode` defaults to `'in-app'`. */
+type BackCommandResult = {
+  action: 'back';
+  mode: BackMode;
+  message: string;
+};
+/** `orientation` — `{ action: 'orientation', orientation, message: 'Rotated to <orientation>' }`. */
+type OrientationCommandResult = {
+  action: 'orientation';
+  orientation: DeviceRotation;
+  message: string;
+};
+/**
+ * @deprecated The `rotate` command was renamed to `orientation`. This is the
+ * legacy response contract (`action: 'rotate'`) that shipped in v0.18/v0.19,
+ * retained for existing SDK consumers until the next major version. New code
+ * should use {@link OrientationCommandResult}.
+ */
+type RotateCommandResult = {
+  action: 'rotate';
+  orientation: DeviceRotation;
+  message: string;
+};
+/** `app-switcher` — `{ action: 'app-switcher', message: 'Opened app switcher' }`. */
+type AppSwitcherCommandResult = {
+  action: 'app-switcher';
+  message: string;
+};
+/** `tv-remote` — `{ action: 'tv-remote', button, durationMs?, message }`. */
+type TvRemoteCommandResult = {
+  action: 'tv-remote';
+  button: TvRemoteButton;
+  durationMs?: number;
+  message: string;
+};
+//#endregion
+//#region packages/contracts/src/wait.d.ts
+/**
+ * Public daemon result for `wait`. The runtime-local result carries a `kind`
+ * discriminant, but `toDaemonWaitData` intentionally projects the normal daemon
+ * payload to this compact shape. The direct iOS selector fast path may still
+ * include `kind: 'selector'` additively.
+ */
+type WaitCommandResult = {
+  waitedMs: number;
+  kind?: 'selector';
+  text?: string;
+  selector?: string;
+  captures?: number;
+  nodeCount?: number;
+  hint?: string;
+  warning?: string;
+};
+//#endregion
+//#region packages/contracts/src/app-events.d.ts
+type TriggerAppEventCommandResult = {
+  event: string;
+  eventUrl: string;
+  transport: 'deep-link';
+  message: string;
+};
+//#endregion
+//#region packages/contracts/src/app-state.d.ts
+/**
+ * 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.
+ */
+type AppStateCommandResult = {
+  platform: 'ios' | 'macos';
+  appName: string;
+  appBundleId?: string;
+  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;
 };
-type DeviceCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
 //#endregion
-//#region src/contracts/target-shutdown-contract.d.ts
+//#region packages/contracts/src/target-shutdown-contract.d.ts
 type TargetShutdownResult = {
   success: boolean;
   exitCode: number;
@@ -58,67 +172,285 @@ type TargetShutdownResult = {
   error?: NormalizedError;
 };
 //#endregion
-//#region src/contracts/client-device-view.d.ts
-type AgentDeviceDevice = {
+//#region packages/contracts/src/device.d.ts
+/**
+ * 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 }` plus the
+ * additive `appleOs` discriminant, emitted only for Apple devices.
+ */
+type BootCommandResult = {
   platform: PublicPlatform;
   target: DeviceTarget;
-  kind: DeviceKind;
+  /** Human-readable device name (`device.name`). */
+  device: string;
+  /** Stable device id (`device.id`). */
   id: string;
-  name: string;
-  booted?: boolean;
+  kind: DeviceKind;
+  /** Always `true` on the success path. */
+  booted: true;
   /**
-   * Additive Apple-OS discriminant (iPhone/iPad/tvOS/visionOS/macOS). Present only for
-   * Apple devices; `platform` still carries the leaf (`ios`/`macos`).
+   * Additive Apple-OS discriminant (`device.appleOs`): iPhone/iPad/tvOS/visionOS/macOS.
+   * Present only for Apple devices; absent for non-Apple platforms. `platform` stays the
+   * leaf (`ios`/`macos`) — this is an extra field, not a replacement.
    */
   appleOs?: AppleOS;
-  identifiers: AgentDeviceIdentifiers;
-  ios?: {
-    udid: string;
-  };
-  android?: {
-    serial: string;
-  };
-  vega?: {
-    serial: string;
-  };
-};
-type AgentDeviceCapabilitiesResult = {
-  device: AgentDeviceDevice;
-  availableCommands: string[];
 };
-type AgentDeviceSessionDevice = {
+/**
+ * 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 }` plus the additive
+ * `appleOs` discriminant (Apple devices only). The `shutdown` field is the raw
+ * {@link TargetShutdownResult} from `shutdownDeviceTarget`.
+ */
+type ShutdownCommandResult = {
   platform: PublicPlatform;
   target: DeviceTarget;
+  /** Human-readable device name (`device.name`). */
+  device: string;
+  /** Stable device id (`device.id`). */
   id: string;
-  name: string;
+  kind: DeviceKind;
+  shutdown: TargetShutdownResult;
   /**
-   * Additive Apple-OS discriminant (iPhone/iPad/tvOS/visionOS/macOS). Present only for
-   * Apple devices; `platform` still carries the leaf (`ios`/`macos`).
+   * Additive Apple-OS discriminant (`device.appleOs`): iPhone/iPad/tvOS/visionOS/macOS.
+   * Present only for Apple devices; absent for non-Apple platforms. `platform` stays the
+   * leaf (`ios`/`macos`) — this is an extra field, not a replacement.
    */
   appleOs?: AppleOS;
-  identifiers: AgentDeviceIdentifiers;
-  ios?: {
-    udid: string;
-    simulatorSetPath?: string | null;
-  };
-  android?: {
-    serial: string;
-  };
-  vega?: {
-    serial: string;
-  };
-};
-type AgentDeviceSession = {
-  name: string;
-  createdAt: number;
-  sessionStateDir?: string;
-  runnerLogPath?: string;
-  device: AgentDeviceSessionDevice;
-  identifiers: AgentDeviceIdentifiers;
 };
-type StartupPerfSample = {
-  durationMs: number;
-  measuredAt: string;
+//#endregion
+//#region packages/contracts/src/logs.d.ts
+declare const LOG_ACTION_VALUES: readonly ['path', 'start', 'stop', 'doctor', 'mark', 'clear'];
+type LogAction = (typeof LOG_ACTION_VALUES)[number];
+//#endregion
+//#region packages/contracts/src/recording-scope.d.ts
+declare const RECORDING_SCOPE_VALUES: readonly ['app', 'device', 'system'];
+type RecordingScope = (typeof RECORDING_SCOPE_VALUES)[number];
+//#endregion
+//#region packages/contracts/src/recording.d.ts
+type RecordingAppIdentity = {
+  bundleId: string;
+  name?: string;
+};
+type RecordingStartCommandResult = {
+  recording: 'started';
+  outPath: string;
+  sessionStateDir: string;
+  recordingBackend?: string;
+  recordingScope?: RecordingScope;
+  recordOnlySession?: boolean;
+  activeSessionApp?: RecordingAppIdentity;
+  showTouches: boolean;
+};
+type RecordingStopCommandResult = {
+  recording: 'stopped';
+  outPath: string;
+  telemetryPath?: string;
+  artifacts: DaemonArtifact[];
+  recordingBackend?: string;
+  recordingScope?: RecordingScope;
+  recordOnlySession?: boolean;
+  activeSessionApp?: RecordingAppIdentity;
+  durationMs: number;
+  showTouches: boolean;
+  warning?: string;
+  overlayWarning?: string;
+  chunks?: Array<{
+    index: number;
+    path: string;
+  }>;
+};
+type RecordingCommandResult = RecordingStartCommandResult | RecordingStopCommandResult;
+type TraceCommandResult = {
+  trace: 'started';
+  outPath: string;
+} | {
+  trace: 'stopped';
+  outPath: string;
+  artifacts: DaemonArtifact[];
+};
+//#endregion
+//#region packages/contracts/src/perf.d.ts
+declare const PERF_AREA_VALUES: readonly ['metrics', 'frames', 'memory', 'cpu', 'trace'];
+declare const PERF_ACTION_VALUES: readonly ['sample', 'snapshot', 'start', 'stop', 'report'];
+declare const PERF_SUBJECT_VALUES: readonly ['profile'];
+declare const PERF_KIND_VALUES: readonly ['xctrace', 'simpleperf', 'perfetto', 'android-hprof', 'memgraph'];
+type PerfArea = (typeof PERF_AREA_VALUES)[number];
+type PerfAction = (typeof PERF_ACTION_VALUES)[number];
+type PerfSubject = (typeof PERF_SUBJECT_VALUES)[number];
+type PerfKind = (typeof PERF_KIND_VALUES)[number];
+//#endregion
+//#region packages/contracts/src/recording-export-quality.d.ts
+declare const RECORDING_EXPORT_QUALITIES: readonly ['medium', 'high'];
+type RecordingExportQuality = (typeof RECORDING_EXPORT_QUALITIES)[number];
+//#endregion
+//#region packages/contracts/src/json.d.ts
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+type JsonObject = {
+  [key: string]: JsonValue;
+};
+//#endregion
+//#region packages/contracts/src/prepare.d.ts
+type PrepareIosRunnerCacheKind = 'exact' | 'restore-key' | 'miss' | 'external';
+type PrepareIosRunnerArtifactState = 'valid' | 'rebuilt';
+type PrepareIosRunnerTiming = {
+  totalMs: number;
+  additiveParts: {
+    buildMs?: number;
+    connectAfterBuildMs: number;
+    healthCheckMs: number;
+  };
+  containment: {
+    connectMs?: ['buildMs'];
+    healthCheckMs: [];
+  };
+  note: string;
+};
+/**
+ * Public daemon result for `prepare ios-runner`. The runner-local prepare result
+ * is projected by `prepareIosRunnerResponseData` with device identity and timing
+ * guidance before it reaches the client.
+ */
+type PrepareCommandResult = {
+  action: 'ios-runner';
+  platform: PublicPlatform;
+  deviceId: string;
+  deviceName: string;
+  kind: DeviceKind;
+  durationMs: number;
+  runner: JsonObject;
+  cache?: PrepareIosRunnerCacheKind;
+  artifact?: PrepareIosRunnerArtifactState;
+  buildMs?: number;
+  connectMs: number;
+  healthCheckMs: number;
+  xctestrunPath?: string;
+  recoveryReason?: string;
+  failureReason?: string;
+  timing: PrepareIosRunnerTiming;
+  message: string;
+};
+//#endregion
+//#region packages/contracts/src/push.d.ts
+type PushCommandResult = {
+  platform: 'ios';
+  bundleId: string;
+  message: string;
+} | {
+  platform: 'android';
+  package: string;
+  action: string;
+  extrasCount: number;
+  message: string;
+};
+//#endregion
+//#region packages/contracts/src/client-connection.d.ts
+type AgentDeviceDaemonTransportContext = {
+  authToken?: string;
+};
+type AgentDeviceDaemonTransport = (req: Omit<DaemonRequest, 'token'>, context?: AgentDeviceDaemonTransportContext) => Promise<DaemonResponse>;
+type AgentDeviceClientConfig = RemoteConnectionProfileFields & CloudProviderProfileFields & {
+  session?: string;
+  lockPolicy?: DaemonLockPolicy;
+  lockPlatform?: PlatformSelector;
+  requestId?: string;
+  sessionIsolation?: SessionIsolationMode;
+  leaseBackend?: LeaseBackend;
+  leaseTtlMs?: number;
+  runtime?: SessionRuntimeHints;
+  cwd?: string;
+  debug?: boolean;
+  cost?: boolean;
+  responseLevel?: ResponseLevel;
+  iosXctestrunFile?: string;
+  iosXctestDerivedDataPath?: string;
+  iosXctestEnvDir?: string;
+};
+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' | 'providerDeviceOrientation' | 'providerGeoLocation' | 'providerTimezone' | 'providerLanguage' | 'providerLocale' | 'providerNetworkProfile' | 'providerCustomNetwork' | 'providerNoResignApp' | 'awsProjectArn' | 'awsDeviceArn' | 'awsAppArn' | 'awsRegion' | 'awsInteractionMode' | 'leaseTtlMs' | 'cwd' | 'debug' | 'cost' | 'responseLevel' | 'iosXctestrunFile' | 'iosXctestDerivedDataPath' | 'iosXctestEnvDir'>;
+type AgentDeviceIdentifiers = {
+  session?: string;
+  deviceId?: string;
+  deviceName?: string;
+  udid?: string;
+  serial?: string;
+  appId?: string;
+  appBundleId?: string;
+  package?: string;
+};
+type AgentDeviceSelectionOptions = {
+  platform?: PlatformSelector;
+  target?: DeviceTarget;
+  device?: string;
+  udid?: string;
+  serial?: string;
+  iosSimulatorDeviceSet?: string;
+  androidDeviceAllowlist?: string;
+};
+type DeviceCommandBaseOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
+//#endregion
+//#region packages/contracts/src/client-device-view.d.ts
+type AgentDeviceDevice = {
+  platform: PublicPlatform;
+  target: DeviceTarget;
+  kind: DeviceKind;
+  id: string;
+  name: string;
+  booted?: boolean;
+  /**
+   * Additive Apple-OS discriminant (iPhone/iPad/tvOS/visionOS/macOS). Present only for
+   * Apple devices; `platform` still carries the leaf (`ios`/`macos`).
+   */
+  appleOs?: AppleOS;
+  identifiers: AgentDeviceIdentifiers;
+  ios?: {
+    udid: string;
+  };
+  android?: {
+    serial: string;
+  };
+  vega?: {
+    serial: string;
+  };
+};
+type AgentDeviceCapabilitiesResult = {
+  device: AgentDeviceDevice;
+  availableCommands: string[];
+};
+type AgentDeviceSessionDevice = {
+  platform: PublicPlatform;
+  target: DeviceTarget;
+  id: string;
+  name: string;
+  /**
+   * Additive Apple-OS discriminant (iPhone/iPad/tvOS/visionOS/macOS). Present only for
+   * Apple devices; `platform` still carries the leaf (`ios`/`macos`).
+   */
+  appleOs?: AppleOS;
+  identifiers: AgentDeviceIdentifiers;
+  ios?: {
+    udid: string;
+    simulatorSetPath?: string | null;
+  };
+  android?: {
+    serial: string;
+  };
+  vega?: {
+    serial: string;
+  };
+};
+type AgentDeviceSession = {
+  name: string;
+  createdAt: number;
+  sessionStateDir?: string;
+  runnerLogPath?: string;
+  device: AgentDeviceSessionDevice;
+  identifiers: AgentDeviceIdentifiers;
+};
+type StartupPerfSample = {
+  durationMs: number;
+  measuredAt: string;
   method: string;
   appTarget?: string;
   appBundleId?: string;
@@ -128,7 +460,7 @@ type DeviceBootOptions = DeviceCommandBaseOptions & {
 };
 type DeviceShutdownOptions = DeviceCommandBaseOptions;
 //#endregion
-//#region src/contracts/client-app.d.ts
+//#region packages/contracts/src/client-app.d.ts
 type AppInstallOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
   app?: string;
   appPath: string;
@@ -233,7 +565,29 @@ type MaterializationReleaseResult = {
   identifiers: AgentDeviceIdentifiers;
 };
 //#endregion
-//#region src/contracts/client-capture.d.ts
+//#region packages/contracts/src/snapshot-capture-annotations.d.ts
+type SnapshotCaptureAnalysis = {
+  rawNodeCount: number;
+  maxDepth: number;
+};
+type SnapshotCaptureFreshness = {
+  action: string;
+  retryCount: number;
+  staleAfterRetries: boolean;
+  reason?: 'empty-interactive' | 'sharp-drop' | 'stuck-route';
+};
+type SnapshotCaptureAnnotations = {
+  analysis?: SnapshotCaptureAnalysis;
+  androidSnapshot?: AndroidSnapshotBackendMetadata;
+  freshness?: SnapshotCaptureFreshness;
+  quality?: SnapshotQualityVerdict;
+  warnings?: string[];
+};
+type PublicSnapshotCaptureAnnotations = Pick<SnapshotCaptureAnnotations, 'androidSnapshot' | 'warnings'> & {
+  snapshotQuality?: SnapshotQualityVerdict;
+};
+//#endregion
+//#region packages/contracts/src/client-capture.d.ts
 type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
   interactiveOnly?: boolean;
   depth?: number;
@@ -295,7 +649,7 @@ type CaptureDiffOptions = DeviceCommandBaseOptions & Pick<CaptureSnapshotOptions
 type SelectorSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
 type FindSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'raw'>;
 //#endregion
-//#region src/contracts/client-target.d.ts
+//#region packages/contracts/src/client-target.d.ts
 type PointTarget = {
   x: number;
   y: number;
@@ -320,7 +674,7 @@ type SelectorTarget = {
 type InteractionTarget = PointTarget | RefTarget | SelectorTarget;
 type ElementTarget = RefTarget | SelectorTarget;
 //#endregion
-//#region src/contracts/client-gesture.d.ts
+//#region packages/contracts/src/client-gesture.d.ts
 type RepeatedPressOptions = {
   count?: number;
   intervalMs?: number;
@@ -419,7 +773,7 @@ type ScrollOptions = DeviceCommandBaseOptions & {
   durationMs?: number;
 };
 //#endregion
-//#region src/contracts/client-lease.d.ts
+//#region packages/contracts/src/client-lease.d.ts
 type Lease = {
   leaseId: string;
   tenantId: string;
@@ -459,25 +813,7 @@ type CloudArtifactsOptions = AgentDeviceRequestOverrides & {
   providerSessionId?: string;
 };
 //#endregion
-//#region src/contracts/logs.d.ts
-declare const LOG_ACTION_VALUES: readonly ['path', 'start', 'stop', 'doctor', 'mark', 'clear'];
-type LogAction = (typeof LOG_ACTION_VALUES)[number];
-//#endregion
-//#region src/contracts/perf.d.ts
-declare const PERF_AREA_VALUES: readonly ['metrics', 'frames', 'memory', 'cpu', 'trace'];
-declare const PERF_ACTION_VALUES: readonly ['sample', 'snapshot', 'start', 'stop', 'report'];
-declare const PERF_SUBJECT_VALUES: readonly ['profile'];
-declare const PERF_KIND_VALUES: readonly ['xctrace', 'simpleperf', 'perfetto', 'android-hprof', 'memgraph'];
-type PerfArea = (typeof PERF_AREA_VALUES)[number];
-type PerfAction = (typeof PERF_ACTION_VALUES)[number];
-type PerfSubject = (typeof PERF_SUBJECT_VALUES)[number];
-type PerfKind = (typeof PERF_KIND_VALUES)[number];
-//#endregion
-//#region src/contracts/recording-scope.d.ts
-declare const RECORDING_SCOPE_VALUES: readonly ['app', 'device', 'system'];
-type RecordingScope = (typeof RECORDING_SCOPE_VALUES)[number];
-//#endregion
-//#region src/contracts/client-observability.d.ts
+//#region packages/contracts/src/client-observability.d.ts
 type PerfOptions = DeviceCommandBaseOptions & {
   area?: PerfArea;
   subject?: PerfSubject;
@@ -521,7 +857,7 @@ type TraceOptions = AgentDeviceRequestOverrides & {
   path?: string;
 };
 //#endregion
-//#region src/contracts/client-replay.d.ts
+//#region packages/contracts/src/client-replay.d.ts
 type ReplayRunOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
   path: string;
   runtime?: SessionRuntimeHints;
@@ -545,6 +881,8 @@ type ReplayRunOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOption
   resumeFrom?: number;
   /** The `resume.planDigest` from the divergence report `resumeFrom` came from. */
   resumePlanDigest?: string;
+  /** Leave the session active by suppressing an authored terminal `close` in native `.ad`. */
+  keepSession?: boolean;
   /**
    * ADR 0012 decision 6, R1/R6: arms agent-supervised re-record repair
    * from this replay attempt onward. Optional string value is the healed
@@ -585,10 +923,10 @@ type BatchRunOptions = AgentDeviceRequestOverrides & {
   out?: string;
 };
 //#endregion
-//#region src/contracts/client-request.d.ts
+//#region packages/contracts/src/client-request.d.ts
 type CommandRequestResult = DaemonResponseData;
 //#endregion
-//#region src/contracts/client-selector-read.d.ts
+//#region packages/contracts/src/client-selector-read.d.ts
 /**
  * #1271 stage 2 (ADR 0012 amendment): `get`/`is`/`find` are observation-only
  * and excluded from a repair-armed heal by default. `record` forces this
@@ -629,7 +967,7 @@ type FindOptions = (FindBaseOptions & {
   value: string;
 });
 //#endregion
-//#region src/contracts/client-session.d.ts
+//#region packages/contracts/src/client-session.d.ts
 type SessionCloseResult = {
   session: string;
   shutdown?: TargetShutdownResult;
@@ -654,7 +992,7 @@ type SessionSaveScriptResult = {
   identifiers: AgentDeviceIdentifiers;
 };
 //#endregion
-//#region src/contracts/client-settings.d.ts
+//#region packages/contracts/src/client-settings.d.ts
 type PermissionTarget = 'camera' | 'microphone' | 'photos' | 'contacts' | 'contacts-limited' | 'notifications' | 'calendar' | 'location' | 'location-always' | 'media-library' | 'motion' | 'reminders' | 'siri' | 'accessibility' | 'screen-recording' | 'input-monitoring';
 type SettingsUpdateOptions = (DeviceCommandBaseOptions & {
   setting: 'clear-app-state';
@@ -687,7 +1025,7 @@ type SettingsUpdateOptions = (DeviceCommandBaseOptions & {
   mode?: 'full' | 'limited';
 });
 //#endregion
-//#region src/contracts/client-system.d.ts
+//#region packages/contracts/src/client-system.d.ts
 type WaitCommandTarget = {
   durationMs: number;
   text?: never;
@@ -734,399 +1072,130 @@ type AlertCommandOptions = DeviceCommandBaseOptions & {
   action?: AlertAction;
   timeoutMs?: number;
 };
-type AppStateCommandOptions = DeviceCommandBaseOptions;
-type KeyboardCommandOptions = DeviceCommandBaseOptions & {
-  action?: 'status' | 'dismiss' | 'enter' | 'return';
-};
-type ClipboardCommandOptions = (DeviceCommandBaseOptions & {
-  action: 'read';
-}) | (DeviceCommandBaseOptions & {
-  action: 'write';
-  text: string;
-});
-type ReactNativeCommandOptions = DeviceCommandBaseOptions & {
-  action: 'dismiss-overlay';
-};
-type PrepareCommandOptions = DeviceCommandBaseOptions & {
-  action: 'ios-runner';
-  timeoutMs?: number;
-};
-type DoctorCommandOptions = DeviceCommandBaseOptions & {
-  targetApp?: string;
-  remote?: boolean;
-};
-type ViewportCommandOptions = DeviceCommandBaseOptions & {
-  width: number;
-  height: number;
-};
-//#endregion
-//#region src/contracts/navigation.d.ts
-/**
- * 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' }`. */
-type HomeCommandResult = {
-  action: 'home';
-  message: string;
-};
-/** `back` — `{ action: 'back', mode, message: 'Back' }`; `mode` defaults to `'in-app'`. */
-type BackCommandResult = {
-  action: 'back';
-  mode: BackMode;
-  message: string;
-};
-/** `orientation` — `{ action: 'orientation', orientation, message: 'Rotated to <orientation>' }`. */
-type OrientationCommandResult = {
-  action: 'orientation';
-  orientation: DeviceRotation;
-  message: string;
-};
-/**
- * @deprecated The `rotate` command was renamed to `orientation`. This is the
- * legacy response contract (`action: 'rotate'`) that shipped in v0.18/v0.19,
- * retained for existing SDK consumers until the next major version. New code
- * should use {@link OrientationCommandResult}.
- */
-type RotateCommandResult = {
-  action: 'rotate';
-  orientation: DeviceRotation;
-  message: string;
-};
-/** `app-switcher` — `{ action: 'app-switcher', message: 'Opened app switcher' }`. */
-type AppSwitcherCommandResult = {
-  action: 'app-switcher';
-  message: string;
-};
-/** `tv-remote` — `{ action: 'tv-remote', button, durationMs?, message }`. */
-type TvRemoteCommandResult = {
-  action: 'tv-remote';
-  button: TvRemoteButton;
-  durationMs?: number;
-  message: string;
-};
-//#endregion
-//#region src/commands/command-contract.d.ts
-type JsonSchema = {
-  type?: string | readonly string[];
-  description?: string;
-  properties?: Record<string, JsonSchema>;
-  required?: readonly string[];
-  additionalProperties?: boolean | JsonSchema;
-  items?: JsonSchema;
-  prefixItems?: readonly JsonSchema[];
-  oneOf?: readonly JsonSchema[];
-  enum?: readonly unknown[];
-  const?: unknown;
-  minimum?: number;
-  maximum?: number;
-};
-type ExecutableCommandProjection<ClientMethod extends string = string> = {
-  clientMethod: ClientMethod;
-  outputSchema: JsonSchema;
-};
-//#endregion
-//#region src/commands/system/navigation-projection.d.ts
-declare const navigationCommandProjectionType: unique symbol;
-type NavigationCommandProjection<Options, Result, Required extends boolean, ClientMethod extends string> = ExecutableCommandProjection<ClientMethod> & {
-  readonly [navigationCommandProjectionType]?: {
-    options: Options;
-    result: Result;
-    required: Required;
-  };
-};
-declare const NAVIGATION_COMMAND_PROJECTIONS: {
-  readonly back: NavigationCommandProjection<{
-    mode?: BackMode;
-  }, BackCommandResult, false, "back">;
-  readonly home: NavigationCommandProjection<{}, HomeCommandResult, false, "home">;
-  readonly orientation: NavigationCommandProjection<{
-    orientation: DeviceRotation;
-  }, OrientationCommandResult, true, "orientation">;
-  readonly 'app-switcher': NavigationCommandProjection<{}, AppSwitcherCommandResult, false, "appSwitcher">;
-  readonly 'tv-remote': NavigationCommandProjection<{
-    button: TvRemoteButton;
-    durationMs?: number;
-  }, TvRemoteCommandResult, true, "tvRemote">;
-};
-type NavigationCommandName = keyof typeof NAVIGATION_COMMAND_PROJECTIONS;
-type NavigationCommandOptions<Name extends NavigationCommandName> = (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name] extends NavigationCommandProjection<infer Options, unknown, boolean, string> ? Options : never;
-type ProjectedNavigationCommandMethod<BaseOptions, Projection> = Projection extends NavigationCommandProjection<infer Options, infer Result, infer Required, string> ? Required extends true ? (options: BaseOptions & Options) => Promise<Result> : (options?: BaseOptions & Options) => Promise<Result> : never;
-type ProjectedNavigationCommandClient<BaseOptions> = { [Name in NavigationCommandName as (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name]['clientMethod']]: ProjectedNavigationCommandMethod<BaseOptions, (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name]>; };
-//#endregion
-//#region src/contracts/debug-symbols.d.ts
-type DebugSymbolsOptions = {
-  action?: 'symbols';
-  artifact: string;
-  dsym?: string;
-  searchPath?: string;
-  out?: string;
-  cwd?: string;
-};
-type DebugSymbolsImage = {
-  name: string;
-  uuid: string;
-  arch?: string;
-  dsymPath: string;
-  binaryPath: string;
-};
-type DebugSymbolsCrashFrame = {
-  index: number;
-  image: string;
-  address: string;
-  symbol?: string;
-};
-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[];
-};
-type DebugSymbolsResult = {
-  kind: 'debugSymbols';
-  platform: 'apple';
-  artifactPath: string;
-  outPath: string;
-  crash: DebugSymbolsCrashSummary;
-  matchedImages: DebugSymbolsImage[];
-  symbolicatedFrames: number;
-  skippedImages: number;
-  warnings?: string[];
-  message: string;
-};
-//#endregion
-//#region src/contracts/device.d.ts
-/**
- * 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 }` plus the
- * additive `appleOs` discriminant, emitted only for Apple devices.
- */
-type BootCommandResult = {
-  platform: PublicPlatform;
-  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;
-  /**
-   * Additive Apple-OS discriminant (`device.appleOs`): iPhone/iPad/tvOS/visionOS/macOS.
-   * Present only for Apple devices; absent for non-Apple platforms. `platform` stays the
-   * leaf (`ios`/`macos`) — this is an extra field, not a replacement.
-   */
-  appleOs?: AppleOS;
-};
-/**
- * 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 }` plus the additive
- * `appleOs` discriminant (Apple devices only). The `shutdown` field is the raw
- * {@link TargetShutdownResult} from `shutdownDeviceTarget`.
- */
-type ShutdownCommandResult = {
-  platform: PublicPlatform;
-  target: DeviceTarget;
-  /** Human-readable device name (`device.name`). */
-  device: string;
-  /** Stable device id (`device.id`). */
-  id: string;
-  kind: DeviceKind;
-  shutdown: TargetShutdownResult;
-  /**
-   * Additive Apple-OS discriminant (`device.appleOs`): iPhone/iPad/tvOS/visionOS/macOS.
-   * Present only for Apple devices; absent for non-Apple platforms. `platform` stays the
-   * leaf (`ios`/`macos`) — this is an extra field, not a replacement.
-   */
-  appleOs?: AppleOS;
-};
-//#endregion
-//#region src/contracts/viewport.d.ts
-/**
- * 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.
- */
-type ViewportCommandResult = {
-  width: number;
-  height: number;
-  message: string;
-};
-//#endregion
-//#region src/contracts/clipboard.d.ts
-/**
- * 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.
- */
-type ClipboardCommandResult = {
-  action: 'read';
-  text: string;
-} | {
-  action: 'write';
-  textLength: number;
-  message: string;
-};
-//#endregion
-//#region src/contracts/app-state.d.ts
-/**
- * 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.
- */
-type AppStateCommandResult = {
-  platform: 'ios' | 'macos';
-  appName: string;
-  appBundleId?: string;
-  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;
-};
-//#endregion
-//#region src/contracts/keyboard.d.ts
-/**
- * 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).
- */
-type KeyboardCommandResult = {
-  platform: 'android' | 'ios';
-  action: 'status' | 'dismiss' | 'enter';
-  visible?: boolean;
-  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;
+type AppStateCommandOptions = DeviceCommandBaseOptions;
+type KeyboardCommandOptions = DeviceCommandBaseOptions & {
+  action?: 'status' | 'dismiss' | 'enter' | 'return';
+};
+type ClipboardCommandOptions = (DeviceCommandBaseOptions & {
+  action: 'read';
+}) | (DeviceCommandBaseOptions & {
+  action: 'write';
+  text: string;
+});
+type ReactNativeCommandOptions = DeviceCommandBaseOptions & {
+  action: 'dismiss-overlay';
+};
+type PrepareCommandOptions = DeviceCommandBaseOptions & {
+  action: 'ios-runner';
+  timeoutMs?: number;
+};
+type DoctorCommandOptions = DeviceCommandBaseOptions & {
+  targetApp?: string;
+  remote?: boolean;
+};
+type ViewportCommandOptions = DeviceCommandBaseOptions & {
+  width: number;
+  height: number;
 };
 //#endregion
-//#region src/contracts/wait.d.ts
-/**
- * Public daemon result for `wait`. The runtime-local result carries a `kind`
- * discriminant, but `toDaemonWaitData` intentionally projects the normal daemon
- * payload to this compact shape. The direct iOS selector fast path may still
- * include `kind: 'selector'` additively.
- */
-type WaitCommandResult = {
-  waitedMs: number;
-  kind?: 'selector';
-  text?: string;
-  selector?: string;
-  captures?: number;
-  nodeCount?: number;
-  hint?: string;
-  warning?: string;
+//#region src/commands/command-contract.d.ts
+type JsonSchema = {
+  type?: string | readonly string[];
+  description?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: readonly string[];
+  additionalProperties?: boolean | JsonSchema;
+  items?: JsonSchema;
+  prefixItems?: readonly JsonSchema[];
+  oneOf?: readonly JsonSchema[];
+  enum?: readonly unknown[];
+  const?: unknown;
+  minimum?: number;
+  maximum?: number;
+};
+type ExecutableCommandProjection<ClientMethod extends string = string> = {
+  clientMethod: ClientMethod;
+  outputSchema: JsonSchema;
 };
 //#endregion
-//#region src/contracts/prepare.d.ts
-type PrepareIosRunnerCacheKind = 'exact' | 'restore-key' | 'miss' | 'external';
-type PrepareIosRunnerArtifactState = 'valid' | 'rebuilt';
-type PrepareIosRunnerTiming = {
-  totalMs: number;
-  additiveParts: {
-    buildMs?: number;
-    connectAfterBuildMs: number;
-    healthCheckMs: number;
-  };
-  containment: {
-    connectMs?: ['buildMs'];
-    healthCheckMs: [];
+//#region src/commands/system/navigation-projection.d.ts
+declare const navigationCommandProjectionType: unique symbol;
+type NavigationCommandProjection<Options, Result, Required extends boolean, ClientMethod extends string> = ExecutableCommandProjection<ClientMethod> & {
+  readonly [navigationCommandProjectionType]?: {
+    options: Options;
+    result: Result;
+    required: Required;
   };
-  note: string;
 };
-/**
- * Public daemon result for `prepare ios-runner`. The runner-local prepare result
- * is projected by `prepareIosRunnerResponseData` with device identity and timing
- * guidance before it reaches the client.
- */
-type PrepareCommandResult = {
-  action: 'ios-runner';
-  platform: PublicPlatform;
-  deviceId: string;
-  deviceName: string;
-  kind: DeviceKind;
-  durationMs: number;
-  runner: JsonObject;
-  cache?: PrepareIosRunnerCacheKind;
-  artifact?: PrepareIosRunnerArtifactState;
-  buildMs?: number;
-  connectMs: number;
-  healthCheckMs: number;
-  xctestrunPath?: string;
-  recoveryReason?: string;
-  failureReason?: string;
-  timing: PrepareIosRunnerTiming;
-  message: string;
+declare const NAVIGATION_COMMAND_PROJECTIONS: {
+  readonly back: NavigationCommandProjection<{
+    mode?: BackMode;
+  }, BackCommandResult, false, "back">;
+  readonly home: NavigationCommandProjection<{}, HomeCommandResult, false, "home">;
+  readonly orientation: NavigationCommandProjection<{
+    orientation: DeviceRotation;
+  }, OrientationCommandResult, true, "orientation">;
+  readonly 'app-switcher': NavigationCommandProjection<{}, AppSwitcherCommandResult, false, "appSwitcher">;
+  readonly 'tv-remote': NavigationCommandProjection<{
+    button: TvRemoteButton;
+    durationMs?: number;
+  }, TvRemoteCommandResult, true, "tvRemote">;
 };
+type NavigationCommandName = keyof typeof NAVIGATION_COMMAND_PROJECTIONS;
+type NavigationCommandOptions<Name extends NavigationCommandName> = (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name] extends NavigationCommandProjection<infer Options, unknown, boolean, string> ? Options : never;
+type ProjectedNavigationCommandMethod<BaseOptions, Projection> = Projection extends NavigationCommandProjection<infer Options, infer Result, infer Required, string> ? Required extends true ? (options: BaseOptions & Options) => Promise<Result> : (options?: BaseOptions & Options) => Promise<Result> : never;
+type ProjectedNavigationCommandClient<BaseOptions> = { [Name in NavigationCommandName as (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name]['clientMethod']]: ProjectedNavigationCommandMethod<BaseOptions, (typeof NAVIGATION_COMMAND_PROJECTIONS)[Name]>; };
 //#endregion
-//#region src/contracts/push.d.ts
-type PushCommandResult = {
-  platform: 'ios';
-  bundleId: string;
-  message: string;
-} | {
-  platform: 'android';
-  package: string;
-  action: string;
-  extrasCount: number;
-  message: string;
+//#region packages/contracts/src/debug-symbols.d.ts
+type DebugSymbolsOptions = {
+  action?: 'symbols';
+  artifact: string;
+  dsym?: string;
+  searchPath?: string;
+  out?: string;
+  cwd?: string;
 };
-//#endregion
-//#region src/contracts/app-events.d.ts
-type TriggerAppEventCommandResult = {
-  event: string;
-  eventUrl: string;
-  transport: 'deep-link';
+type DebugSymbolsImage = {
+  name: string;
+  uuid: string;
+  arch?: string;
+  dsymPath: string;
+  binaryPath: string;
+};
+type DebugSymbolsCrashFrame = {
+  index: number;
+  image: string;
+  address: string;
+  symbol?: string;
+};
+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[];
+};
+type DebugSymbolsResult = {
+  kind: 'debugSymbols';
+  platform: 'apple';
+  artifactPath: string;
+  outPath: string;
+  crash: DebugSymbolsCrashSummary;
+  matchedImages: DebugSymbolsImage[];
+  symbolicatedFrames: number;
+  skippedImages: number;
+  warnings?: string[];
   message: string;
 };
 //#endregion
-//#region src/contracts/doctor.d.ts
+//#region packages/contracts/src/doctor.d.ts
 type DoctorStatus = 'pass' | 'warn' | 'fail' | 'info';
 type DoctorKind = 'auto' | 'react-native' | 'expo' | 'repack';
 type DoctorCheck = {
@@ -1151,15 +1220,13 @@ type DoctorCommandResult = {
   checks: DoctorCheck[];
 };
 //#endregion
-//#region src/snapshot/snapshot-diff.d.ts
+//#region packages/contracts/src/diff.d.ts
 type SnapshotDiffLine = {
   kind: 'added' | 'removed' | 'unchanged';
   text: string;
   /**
-   * Plain ref body (`e12`) of the CURRENT-tree node behind an added line.
-   * Only populated with `withRefs` (interaction `--settle`, #1101) so the
-   * `diff` command's wire shape stays byte-identical. Removed/unchanged lines
-   * never carry it: a removed line's ref names a node of the replaced tree.
+   * Plain ref body (`e12`) of the current-tree node behind an added line.
+   * Only populated with `withRefs`; removed and unchanged lines never carry it.
    */
   ref?: string;
 };
@@ -1168,8 +1235,6 @@ type SnapshotDiffSummary = {
   removals: number;
   unchanged: number;
 };
-//#endregion
-//#region src/contracts/diff.d.ts
 type DiffSnapshotCommandResult = {
   mode: 'snapshot';
   baselineInitialized: boolean;
@@ -1178,59 +1243,31 @@ type DiffSnapshotCommandResult = {
   warnings?: string[];
 };
 //#endregion
-//#region src/contracts/recording.d.ts
-type RecordingAppIdentity = {
-  bundleId: string;
-  name?: string;
-};
-type RecordingStartCommandResult = {
-  recording: 'started';
-  outPath: string;
-  sessionStateDir: string;
-  recordingBackend?: string;
-  recordingScope?: RecordingScope;
-  recordOnlySession?: boolean;
-  activeSessionApp?: RecordingAppIdentity;
-  showTouches: boolean;
-};
-type RecordingStopCommandResult = {
-  recording: 'stopped';
-  outPath: string;
-  telemetryPath?: string;
-  artifacts: DaemonArtifact[];
-  recordingBackend?: string;
-  recordingScope?: RecordingScope;
-  recordOnlySession?: boolean;
-  activeSessionApp?: RecordingAppIdentity;
-  durationMs: number;
-  showTouches: boolean;
-  warning?: string;
-  overlayWarning?: string;
-  chunks?: Array<{
-    index: number;
-    path: string;
-  }>;
-};
-type RecordingCommandResult = RecordingStartCommandResult | RecordingStopCommandResult;
-type TraceCommandResult = {
-  trace: 'started';
-  outPath: string;
-} | {
-  trace: 'stopped';
-  outPath: string;
+//#region packages/contracts/src/viewport.d.ts
+/**
+ * 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.
+ */
+type ViewportCommandResult = {
+  width: number;
+  height: number;
+  message: string;
 };
 //#endregion
-//#region src/contracts/replay.d.ts
+//#region packages/contracts/src/replay.d.ts
 type ReplayCommandResult = {
   replayed: number;
   healed: number;
   session: string;
   /**
    * True iff `session` still exists in the daemon's session store when the
-   * response is built — i.e. the replayed script had no terminal `close`
-   * (ADR 0016's consumption contract). The client uses this, not script
-   * parsing, to decide whether an owned one-shot daemon must stay alive so
-   * the caller can keep addressing this session.
+   * response is built. This remains true when replay suppresses an authored
+   * terminal `close` for an explicit live-session handoff. The client uses
+   * this, not script parsing, to decide whether an owned one-shot daemon must
+   * stay alive so the caller can keep addressing this session.
    */
   sessionActive: boolean;
   artifactPaths: string[];
@@ -1304,7 +1341,7 @@ type ReplaySuiteResult = {
 /**
  * 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
+ * Maps a command name to the per-command result type from `@agent-device/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