agent-device 0.19.2 → 0.20.0

package/dist/src/index.d.ts

@@ -1,36 +1,11 @@
-import { A as AppError, B as PlatformSelector, C as SnapshotQualityVerdict, D as centerOfRect, E as SnapshotVisibility, I as AppleOS, L as DeviceKind, N as isAgentDeviceError, O as DebugSymbolsOptions, P as normalizeAgentDeviceError, R as DeviceTarget, S as SnapshotNode, T as SnapshotUnchanged, V as PublicPlatform, _ as ResponseLevel, a as DaemonRequest, b as Point, g as NetworkIncludeMode, i as DaemonLockPolicy, j as NormalizedError, k as DebugSymbolsResult, o as DaemonResponse, p as LeaseBackend, r as DaemonInstallSource, s as DaemonResponseData, t as DaemonArtifactType, v as SessionIsolationMode, x as ScreenshotOverlayRef, y as SessionRuntimeHints } from "./sdk-contracts.js";
+import { B as DeviceKind, C as DebugSymbolsResult, D as isAgentDeviceError, I as SnapshotUnchanged, L as SnapshotVisibility, M as ScreenshotOverlayRef, N as SnapshotNode, O as normalizeAgentDeviceError, P as SnapshotQualityVerdict, R as centerOfRect, S as DebugSymbolsOptions, T as NormalizedError, U as PlatformSelector, V as DeviceTarget, W as PublicPlatform, _ as NetworkIncludeMode, a as DaemonLockPolicy, b as SessionIsolationMode, c as DaemonResponseData, i as DaemonInstallSource, m as LeaseBackend, n as DaemonArtifactType, o as DaemonRequest, r as DaemonError, s as DaemonResponse, t as DaemonArtifact, w as AppError, x as SessionRuntimeHints, y as ResponseLevel, z as AppleOS } from "./sdk-contracts.js";
+import { a as GesturePointerCount, c as SwipePreset, l as TransformGestureParams, o as ScrollDirection, s as SwipePattern, u as AndroidSnapshotBackendMetadata } from "./sdk-android-adb.js";
 import { t as AppsFilter } from "./sdk-app-inventory.js";
 import { t as BatchRunResult } from "./sdk-batch-runner.js";
 import { r as FindLocator } from "./sdk-finders.js";
+import { a as LongPressCommandResponseData, i as FindCommandResponseData, o as PressCommandResponseData, r as FillCommandResponseData, s as ClickButton, t as ClickCommandResponseData } from "./interaction.js";
 import { p as createLocalArtifactAdapter } from "./sdk-io.js";
 import { a as PrepareMetroRuntimeResult, c as MetroBridgeScope, i as MetroPrepareKind, o as ReloadMetroResult, r as RemoteConnectionProfileFields, t as CloudProviderProfileFields } from "./sdk-remote-config.js";
-//#region src/platforms/android/snapshot-helper-types.d.ts
-type AndroidSnapshotHelperTransport = 'instrumentation' | 'persistent-session';
-type AndroidSnapshotCaptureMode = 'interactive-windows' | 'active-window';
-type AndroidSnapshotHelperInstallReason = 'missing' | 'outdated' | 'forced' | 'current' | 'skipped';
-//#endregion
-//#region src/platforms/android/snapshot-types.d.ts
-type AndroidSnapshotBackendMetadata = {
-  backend: 'android-helper' | 'uiautomator-dump';
-  helperVersion?: string;
-  helperApiVersion?: string;
-  helperTransport?: AndroidSnapshotHelperTransport;
-  helperSessionReused?: boolean;
-  fallbackReason?: string;
-  installReason?: AndroidSnapshotHelperInstallReason;
-  waitForIdleTimeoutMs?: number;
-  waitForIdleQuietMs?: number;
-  timeoutMs?: number;
-  maxDepth?: number;
-  maxNodes?: number;
-  rootPresent?: boolean;
-  captureMode?: AndroidSnapshotCaptureMode;
-  windowCount?: number;
-  nodeCount?: number;
-  helperTruncated?: boolean;
-  elapsedMs?: number;
-};
-//#endregion
 //#region src/snapshot-capture-annotations.d.ts
 type SnapshotCaptureAnalysis = {
   rawNodeCount: number;
@@ -68,27 +43,15 @@ type SnapshotDiagnosticsSummary = {
   warning?: string;
 };
 //#endregion
-//#region src/core/back-mode.d.ts
+//#region src/contracts/back-mode.d.ts
 declare const BACK_MODES: readonly ['in-app', 'system'];
 type BackMode = (typeof BACK_MODES)[number];
 //#endregion
-//#region src/core/click-button.d.ts
-declare const CLICK_BUTTONS: readonly ['primary', 'secondary', 'middle'];
-type ClickButton = (typeof CLICK_BUTTONS)[number];
-//#endregion
-//#region src/core/recording-export-quality.d.ts
-declare const RECORDING_EXPORT_QUALITIES: readonly ['medium', 'high'];
-type RecordingExportQuality = (typeof RECORDING_EXPORT_QUALITIES)[number];
-//#endregion
-//#region src/core/recording-scope.d.ts
-declare const RECORDING_SCOPE_VALUES: readonly ['app', 'device', 'system'];
-type RecordingScope = (typeof RECORDING_SCOPE_VALUES)[number];
-//#endregion
-//#region src/core/device-rotation.d.ts
+//#region src/contracts/device-rotation.d.ts
 declare const DEVICE_ROTATIONS: readonly ['portrait', 'portrait-upside-down', 'landscape-left', 'landscape-right'];
 type DeviceRotation = (typeof DEVICE_ROTATIONS)[number];
 //#endregion
-//#region src/core/tv-remote.d.ts
+//#region src/contracts/tv-remote.d.ts
 declare const TV_REMOTE_BUTTON_DEFINITIONS: {
   readonly up: {
     readonly aliases: readonly [];
@@ -134,23 +97,65 @@ declare const TV_REMOTE_BUTTON_DEFINITIONS: {
 declare const TV_REMOTE_BUTTONS: (keyof typeof TV_REMOTE_BUTTON_DEFINITIONS)[];
 type TvRemoteButton = (typeof TV_REMOTE_BUTTONS)[number];
 //#endregion
-//#region src/core/scroll-gesture.d.ts
-declare const SCROLL_DIRECTIONS: readonly ['up', 'down', 'left', 'right'];
-type ScrollDirection = (typeof SCROLL_DIRECTIONS)[number];
-declare const SWIPE_PRESETS: readonly ['left', 'right', 'left-edge', 'right-edge'];
-type SwipePreset = (typeof SWIPE_PRESETS)[number];
-declare const SWIPE_PATTERNS: readonly ['one-way', 'ping-pong'];
-type SwipePattern = (typeof SWIPE_PATTERNS)[number];
-type TransformGestureParams = {
-  x: number;
-  y: number;
-  dx: number;
-  dy: number;
-  scale: number;
-  degrees: number;
+//#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/core/recording-export-quality.d.ts
+declare const RECORDING_EXPORT_QUALITIES: readonly ['medium', 'high'];
+type RecordingExportQuality = (typeof RECORDING_EXPORT_QUALITIES)[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/alert-contract.d.ts
 declare const ALERT_ACTIONS: readonly ['get', 'accept', 'dismiss', 'wait'];
 type AlertAction = (typeof ALERT_ACTIONS)[number];
@@ -162,7 +167,27 @@ type JsonObject = {
   [key: string]: JsonValue;
 };
 //#endregion
-//#region src/core/session-surface.d.ts
+//#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/session-surface.d.ts
 declare const SESSION_SURFACES: readonly ['app', 'frontmost-app', 'desktop', 'menubar'];
 type SessionSurface = (typeof SESSION_SURFACES)[number];
 //#endregion
@@ -177,157 +202,38 @@ type ScreenshotResultData = {
   overlayRefs?: ScreenshotOverlayRef[];
 };
 //#endregion
-//#region src/contracts/interaction.d.ts
-type ResolvedTarget = {
-  kind: 'selector';
-  selector: string;
-} | {
-  kind: 'ref';
-  ref: string;
-};
-type ResolvedInteractionTarget = {
-  kind: 'point';
-  point: Point;
-  preActionNodes?: SnapshotNode[];
-} | {
-  kind: 'ref';
-  point?: Point;
-  target: Extract<ResolvedTarget, {
-    kind: 'ref';
-  }>;
-  node?: SnapshotNode;
-  selectorChain?: string[];
-  refLabel?: string;
-  targetHittable?: boolean;
-  hint?: string;
-  preActionNodes?: SnapshotNode[];
-} | {
-  kind: 'selector';
-  point: Point;
-  target: Extract<ResolvedTarget, {
-    kind: 'selector';
-  }>;
-  node: SnapshotNode;
-  selectorChain: string[];
-  refLabel?: string;
-  targetHittable?: boolean;
-  hint?: string;
-  preActionNodes?: SnapshotNode[];
-};
-/**
- * Opt-in (`--verify`) cheap post-condition evidence for mutating interaction
- * commands (#1047). `digest`/`nodeCount`/`interactiveNodeCount` describe a single
- * interactive-only capture taken right after the action; `changedFromBefore`
- * compares that digest against the pre-action capture the resolution path already
- * held, so no extra device round trip is spent beyond the one verify capture.
- * `changedFromBefore: false` is evidence, not failure — the command still
- * succeeded.
- */
-type InteractionEvidence = {
-  foregroundApp?: string;
-  nodeCount: number;
-  interactiveNodeCount: number;
-  digest: string;
-  changedFromBefore: boolean;
-};
-type SettleDiffLine = {
-  kind: 'added' | 'removed';
-  text: string;
-  /**
-   * Plain ref body (`e12`) for ADDED lines: minted from the settled tree that
-   * became the stored session snapshot, so it is immediately actionable and
-   * lets the MCP layer pin it at `refsGeneration`. Removed lines never carry
-   * one — their refs name nodes of the replaced tree.
-   */
-  ref?: string;
-};
-/**
- * One still-present, actionable element on the settled tree, surfaced by the
- * unchanged-interactive tail (see `SettleObservation.tail`).
- */
-type SettleTailEntry = {
-  ref: string;
-  role: string;
-  label?: string;
-};
-type SettleObservation = {
-  settled: boolean;
-  waitedMs: number;
-  captures: number;
-  quietMs: number;
-  timeoutMs: number;
-  /**
-   * The session's snapshot generation after the settled tree became the stored
-   * snapshot (#1076 versioned refs). Attached by the daemon response layer
-   * when `diff` is present: added lines carry refs minted from that tree, so
-   * the response is ref-issuing — the MCP layer merges per-ref pins from it
-   * exactly like snapshot/find responses.
-   */
-  refsGeneration?: number;
-  /**
-   * Digest response view only: capped added-line refs preserved without the
-   * verbose diff line text, so MCP can still pin refs when `diff.lines` is
-   * intentionally omitted.
-   */
-  refs?: Array<{
-    ref: string;
-  }>;
-  /** Present only for `settled: true` observations that stored the settled tree. */
-  diff?: {
-    summary: {
-      additions: number;
-      removals: number;
-      unchanged: number;
-    };
-    lines: SettleDiffLine[];
-    /** Present (true) when lines were capped to the response bound. */
-    truncated?: boolean;
-  };
-  /**
-   * Unchanged interactive refs tail: benchmarks (July 2026) showed 27% of
-   * `--settle` actions were followed by a fallback `snapshot -i` because a
-   * change-only diff omits refs for elements that did not change — after a
-   * modal dismiss the diff shows only removals, and the next button to press
-   * (already on screen, untouched) is absent from the response. `tail` lists
-   * the settled tree's remaining hittable, uncovered interactive elements so
-   * the response stays actionable without that extra round trip. Attached
-   * ONLY when `diff` carries zero added-line refs (the modal-dismiss/
-   * toast-only signature) — a diff with fresh added refs already hands the
-   * next target, so the tail would be pure byte cost. Refs already present on
-   * `diff`'s added lines are excluded. Capped; `tailTruncated` marks when
-   * candidates exceeded the cap.
-   */
-  tail?: SettleTailEntry[];
-  tailTruncated?: true;
-  hint?: string;
-};
-type PressCommandResult = ResolvedInteractionTarget & {
-  backendResult?: Record<string, unknown>;
-  message?: string;
-  warning?: string;
-  evidence?: InteractionEvidence;
-  settle?: SettleObservation;
-};
-type FillCommandResult = ResolvedInteractionTarget & {
-  text: string;
-  warning?: string;
-  backendResult?: Record<string, unknown>;
-  message?: string;
-  evidence?: InteractionEvidence;
-  settle?: SettleObservation;
-};
-type LongPressCommandResult = ResolvedInteractionTarget & {
-  durationMs?: number;
-  backendResult?: Record<string, unknown>;
-  message?: string;
-  warning?: string;
-  settle?: SettleObservation;
-};
-//#endregion
 //#region src/commands/interaction/runtime/gestures.d.ts
 declare const SCROLL_INPUT_DIRECTIONS: readonly ['up', 'down', 'left', 'right', 'top', 'bottom'];
 type ScrollInputDirection = (typeof SCROLL_INPUT_DIRECTIONS)[number];
 //#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/logs.d.ts
 declare const LOG_ACTION_VALUES: readonly ['path', 'start', 'stop', 'doctor', 'mark', 'clear'];
 type LogAction = (typeof LOG_ACTION_VALUES)[number];
@@ -413,46 +319,6 @@ type ViewportCommandResult = {
   message: string;
 };
 //#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;
-};
-/** `rotate` — `{ action: 'rotate', orientation, message: 'Rotated to <orientation>' }`. */
-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/contracts/clipboard.d.ts
 /**
  * Closed result of the `clipboard` command. Mirrors the dispatch handler's
@@ -609,6 +475,172 @@ type TriggerAppEventCommandResult = {
   message: string;
 };
 //#endregion
+//#region src/contracts/doctor.d.ts
+type DoctorStatus = 'pass' | 'warn' | 'fail' | 'info';
+type DoctorKind = 'auto' | 'react-native' | 'expo' | 'repack';
+type DoctorCheck = {
+  id: string;
+  status: DoctorStatus;
+  summary: string;
+  hint?: string;
+  command?: string;
+  evidence?: Record<string, unknown>;
+};
+type DoctorCommandResult = {
+  status: DoctorStatus;
+  summary: string;
+  kind: DoctorKind;
+  platform?: PlatformSelector;
+  target?: DeviceTarget;
+  targetApp?: string;
+  metro?: {
+    host: string;
+    port: number;
+  };
+  checks: DoctorCheck[];
+};
+//#endregion
+//#region src/snapshot/snapshot-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.
+   */
+  ref?: string;
+};
+type SnapshotDiffSummary = {
+  additions: number;
+  removals: number;
+  unchanged: number;
+};
+//#endregion
+//#region src/contracts/diff.d.ts
+type DiffSnapshotCommandResult = {
+  mode: 'snapshot';
+  baselineInitialized: boolean;
+  summary: SnapshotDiffSummary;
+  lines: SnapshotDiffLine[];
+  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;
+};
+//#endregion
+//#region src/contracts/replay.d.ts
+type ReplayCommandResult = {
+  replayed: number;
+  healed: number;
+  session: string;
+  artifactPaths: string[];
+  warnings?: string[];
+  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
+  message: string;
+};
+type ReplaySuiteTestSkipReason = 'skipped-by-filter';
+type ReplaySuiteAttemptFailure = {
+  attempt: number;
+  message: string;
+  durationMs?: number;
+};
+type ReplaySuiteTestPassed = {
+  file: string;
+  title?: string;
+  session: string;
+  status: 'passed';
+  durationMs: number;
+  finalAttemptDurationMs?: number;
+  attempts: number;
+  artifactsDir?: string;
+  replayed: number;
+  healed: number;
+  warnings?: string[];
+  attemptFailures?: ReplaySuiteAttemptFailure[];
+  shardIndex?: number;
+  shardCount?: number;
+  deviceId?: string;
+  deviceName?: string;
+  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
+};
+type ReplaySuiteTestFailed = {
+  file: string;
+  title?: string;
+  session: string;
+  status: 'failed';
+  durationMs: number;
+  attempts: number;
+  artifactsDir?: string;
+  error: DaemonError;
+  shardIndex?: number;
+  shardCount?: number;
+  deviceId?: string;
+  deviceName?: string;
+  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
+};
+type ReplaySuiteTestSkipped = {
+  file: string;
+  title?: string;
+  status: 'skipped';
+  durationMs: 0;
+  reason: ReplaySuiteTestSkipReason;
+  message: string;
+};
+type ReplaySuiteTestResult = ReplaySuiteTestPassed | ReplaySuiteTestFailed | ReplaySuiteTestSkipped;
+type ReplaySuiteResult = {
+  total: number;
+  executed: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  notRun: number;
+  durationMs: number;
+  failures: ReplaySuiteTestFailed[];
+  tests: ReplaySuiteTestResult[];
+  snapshotDiagnostics?: SnapshotDiagnosticsSummary;
+};
+//#endregion
 //#region src/core/command-descriptor/command-result.d.ts
 /**
  * The additive typed-result spine (ADR-0008, Phase 1 step 6).
@@ -621,8 +653,8 @@ type TriggerAppEventCommandResult = {
  * 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
+ * commands `home` / `back` / `orientation` / `app-switcher` alongside the seed
+ * interaction quartet. 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). Batch 5 adds the compact daemon projections for `wait`,
@@ -630,15 +662,17 @@ type TriggerAppEventCommandResult = {
  * re-read of the handler's literal return; see the per-type docstrings.
  */
 interface CommandResultMap {
-  press: PressCommandResult;
-  fill: FillCommandResult;
-  longpress: LongPressCommandResult;
+  press: PressCommandResponseData;
+  click: ClickCommandResponseData;
+  fill: FillCommandResponseData;
+  longpress: LongPressCommandResponseData;
+  find: FindCommandResponseData;
   boot: BootCommandResult;
   shutdown: ShutdownCommandResult;
   viewport: ViewportCommandResult;
   home: HomeCommandResult;
   back: BackCommandResult;
-  rotate: RotateCommandResult;
+  orientation: OrientationCommandResult;
   'app-switcher': AppSwitcherCommandResult;
   clipboard: ClipboardCommandResult;
   appstate: AppStateCommandResult;
@@ -648,6 +682,12 @@ interface CommandResultMap {
   prepare: PrepareCommandResult;
   push: PushCommandResult;
   'trigger-app-event': TriggerAppEventCommandResult;
+  doctor: DoctorCommandResult;
+  diff: DiffSnapshotCommandResult;
+  replay: ReplayCommandResult;
+  test: ReplaySuiteResult;
+  record: RecordingCommandResult;
+  trace: TraceCommandResult;
 }
 /**
  * The typed result for a command named `N`. Seeded commands resolve to their
@@ -805,6 +845,23 @@ type SessionCloseResult = {
   session: string;
   shutdown?: TargetShutdownResult;
   provider?: CloudProviderSessionResult;
+  /**
+   * #1258: absolute path of the committed session/healed script when this close
+   * published one (`close --save-script`, or a repair-armed session's finalize)
+   * — so a client that requested publication learns where the file landed.
+   */
+  savedScript?: string;
+  identifiers: AgentDeviceIdentifiers;
+};
+type SessionSaveScriptOptions = AgentDeviceRequestOverrides & {
+  path?: string;
+  /** Atomically replace an existing target instead of refusing publication. */
+  force?: boolean;
+};
+type SessionSaveScriptResult = {
+  session: string;
+  savedScript: string;
+  actionCount: number;
   identifiers: AgentDeviceIdentifiers;
 };
 type CloudArtifactsOptions = AgentDeviceRequestOverrides & {
@@ -837,12 +894,16 @@ type AppOpenOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions
   launchArgs?: string[];
   relaunch?: boolean;
   saveScript?: boolean | string;
+  /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
+  force?: boolean;
   deviceHub?: boolean;
+  testIme?: boolean;
   noRecord?: boolean;
   runtime?: SessionRuntimeHints;
 };
 type AppOpenResult = {
   session: string;
+  warnings?: string[];
   sessionStateDir?: string;
   runnerLogPath?: string;
   requestLogPath?: string;
@@ -858,11 +919,20 @@ type AppOpenResult = {
 type AppCloseOptions = AgentDeviceRequestOverrides & {
   app?: string;
   shutdown?: boolean;
+  saveScript?: boolean | string;
+  /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
+  force?: boolean;
 };
 type AppCloseResult = {
   session: string;
   closedApp?: string;
   shutdown?: TargetShutdownResult;
+  /**
+   * #1258: absolute path of the committed session/healed script when this close
+   * published one (`close --save-script`, or a repair-armed session's finalize)
+   * — so a client that requested publication learns where the file landed.
+   */
+  savedScript?: string;
   identifiers: AgentDeviceIdentifiers;
 };
 type AppInstallFromSourceOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
@@ -962,6 +1032,13 @@ type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelection
   raw?: boolean;
   forceFull?: boolean;
   timeoutMs?: number;
+  /**
+   * #1271 stage 2 (ADR 0012 amendment): `snapshot` is observation-only and
+   * excluded from a repair-armed heal by default; `record` forces it
+   * through. Mutually exclusive with `noRecord`.
+   */
+  noRecord?: boolean;
+  record?: boolean;
 };
 type CaptureSnapshotResult = {
   nodes: SnapshotNode[];
@@ -972,6 +1049,21 @@ type CaptureSnapshotResult = {
   unchanged?: SnapshotUnchanged;
   snapshotDiagnostics?: SnapshotDiagnosticsSummary;
   identifiers: AgentDeviceIdentifiers;
+  /**
+   * ADR 0014: the response-level ref-frame epoch the plain node refs were minted
+   * from. A ref-issuing snapshot carries it ONCE (nodes stay plain `@e12` for the
+   * token budget); pair a ref with it (`@e12~s<refsGeneration>`) before a mutation.
+   */
+  refsGeneration?: number;
+  /**
+   * Digest response view only: a capped list of `{ ref, label? }` pairs taken
+   * from the full `nodes` tree so the MCP layer can still pin refs when the
+   * default-level `nodes` payload is intentionally omitted.
+   */
+  refs?: Array<{
+    ref: string;
+    label?: string;
+  }>;
 } & PublicSnapshotCaptureAnnotations;
 type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
   path?: string;
@@ -1035,14 +1127,9 @@ type AlertCommandOptions = DeviceCommandBaseOptions & {
   timeoutMs?: number;
 };
 type AppStateCommandOptions = DeviceCommandBaseOptions;
-type BackCommandOptions = DeviceCommandBaseOptions & {
-  mode?: BackMode;
-};
-type HomeCommandOptions = DeviceCommandBaseOptions;
-type RotateCommandOptions = DeviceCommandBaseOptions & {
-  orientation: DeviceRotation;
-};
-type AppSwitcherCommandOptions = DeviceCommandBaseOptions;
+type OrientationCommandOptions = DeviceCommandBaseOptions & NavigationCommandOptions<'orientation'>;
+/** @deprecated Renamed to `OrientationCommandOptions`. Retained until the next major. */
+type RotateCommandOptions = OrientationCommandOptions;
 type KeyboardCommandOptions = DeviceCommandBaseOptions & {
   action?: 'status' | 'dismiss' | 'enter' | 'return';
 };
@@ -1052,10 +1139,6 @@ type ClipboardCommandOptions = (DeviceCommandBaseOptions & {
   action: 'write';
   text: string;
 });
-type TvRemoteCommandOptions = DeviceCommandBaseOptions & {
-  button: TvRemoteButton;
-  durationMs?: number;
-};
 type ReactNativeCommandOptions = DeviceCommandBaseOptions & {
   action: 'dismiss-overlay';
 };
@@ -1071,19 +1154,14 @@ type ViewportCommandOptions = DeviceCommandBaseOptions & {
   width: number;
   height: number;
 };
-type AgentDeviceCommandClient = {
+type NonNavigationCommandClient = {
   wait: (options: WaitCommandOptions) => Promise<CommandResult<'wait'>>;
   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'>>;
-  tvRemote: (options: TvRemoteCommandOptions) => Promise<CommandResult<'tv-remote'>>;
   reactNative: (options: ReactNativeCommandOptions) => Promise<CommandRequestResult>;
-  doctor: (options?: DoctorCommandOptions) => Promise<CommandRequestResult>;
+  doctor: (options?: DoctorCommandOptions) => Promise<CommandResult<'doctor'>>;
   /**
    * JSON prepare results include timing.additiveParts for additive wall-clock phases.
    * Top-level buildMs/connectMs/healthCheckMs are diagnostics and may overlap.
@@ -1091,6 +1169,15 @@ type AgentDeviceCommandClient = {
   prepare: (options: PrepareCommandOptions) => Promise<CommandResult<'prepare'>>;
   viewport: (options: ViewportCommandOptions) => Promise<CommandResult<'viewport'>>;
 };
+type AgentDeviceCommandClient = ProjectedNavigationCommandClient<DeviceCommandBaseOptions> & NonNavigationCommandClient & DeprecatedCommandClient;
+/** Renamed command methods retained for existing consumers until the next major. */
+type DeprecatedCommandClient = {
+  /**
+   * @deprecated Renamed to `orientation`. Delegates to it and returns the legacy
+   * `action: 'rotate'` response contract. Retained until the next major version.
+   */
+  rotate: (options: RotateCommandOptions) => Promise<RotateCommandResult>;
+};
 type SelectorSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
 type FindSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'raw'>;
 type PointTarget = {
@@ -1176,7 +1263,6 @@ type SwipeOptions = DeviceCommandBaseOptions & {
     x: number;
     y: number;
   };
-  durationMs?: number;
   count?: number;
   pauseMs?: number;
   pattern?: SwipePattern;
@@ -1186,6 +1272,7 @@ type PanOptions = DeviceCommandBaseOptions & {
   y: number;
   dx: number;
   dy: number;
+  pointerCount?: GesturePointerCount;
   durationMs?: number;
 };
 type FlingOptions = DeviceCommandBaseOptions & {
@@ -1193,11 +1280,9 @@ type FlingOptions = DeviceCommandBaseOptions & {
   x: number;
   y: number;
   distance?: number;
-  durationMs?: number;
 };
 type SwipeGestureOptions = DeviceCommandBaseOptions & {
   preset: SwipePreset;
-  durationMs?: number;
 };
 type FocusOptions = DeviceCommandBaseOptions & {
   x: number;
@@ -1227,24 +1312,33 @@ type RotateGestureOptions = DeviceCommandBaseOptions & {
   degrees: number;
   x?: number;
   y?: number;
-  velocity?: number;
 };
 type TransformGestureOptions = DeviceCommandBaseOptions & TransformGestureParams;
-type GetOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & {
+/**
+ * #1271 stage 2 (ADR 0012 amendment): `get`/`is`/`find` are observation-only
+ * and excluded from a repair-armed heal by default. `record` forces this
+ * action through (the corrective-read case); `noRecord` continues to opt the
+ * action out entirely. Mutually exclusive.
+ */
+type RecordControlOptions = {
+  noRecord?: boolean;
+  record?: boolean;
+};
+type GetOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & ElementTarget & RecordControlOptions & {
   format: 'text' | 'attrs';
 };
-type IsTextPredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & {
+type IsTextPredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & RecordControlOptions & {
   predicate: 'text';
   selector: string;
   value: string;
 };
-type IsStatePredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & {
+type IsStatePredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & RecordControlOptions & {
   predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected' | 'focused';
   selector: string;
   value?: never;
 };
 type IsOptions = IsTextPredicateOptions | IsStatePredicateOptions;
-type FindBaseOptions = DeviceCommandBaseOptions & FindSnapshotCommandOptions & {
+type FindBaseOptions = DeviceCommandBaseOptions & FindSnapshotCommandOptions & RecordControlOptions & {
   locator?: FindLocator;
   query: string;
   first?: boolean;
@@ -1261,15 +1355,40 @@ type FindOptions = (FindBaseOptions & {
 });
 type ReplayRunOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
   path: string;
+  runtime?: SessionRuntimeHints;
+  /**
+   * @deprecated ADR 0012 migration step 6: `--update` no longer rewrites
+   * the script. Accepted for backward compatibility; every divergence
+   * already carries ranked selector suggestions regardless of this flag.
+   */
   update?: boolean;
   /** @deprecated Use backend: 'maestro'. */
   maestro?: boolean;
   backend?: string;
   env?: string[];
   timeoutMs?: number;
+  /**
+   * ADR 0012 decision 4 / migration step 5: resume at this 1-based plan
+   * step, skipping `1..resumeFrom-1` without executing them. Requires
+   * `resumePlanDigest` from the divergence report that reported this
+   * step as the failure. `replay` only — `test` has no resume fields.
+   */
+  resumeFrom?: number;
+  /** The `resume.planDigest` from the divergence report `resumeFrom` came from. */
+  resumePlanDigest?: string;
+  /**
+   * ADR 0012 decision 6, R1/R6: arms agent-supervised re-record repair
+   * from this replay attempt onward. Optional string value is the healed
+   * `.ad`'s output path; absent one, it defaults to the `<path>` sibling
+   * `<stem>.healed.ad` when the repair ends with `close --save-script`.
+   */
+  saveScript?: boolean | string;
+  /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
+  force?: boolean;
 };
 type ReplayTestOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
   paths: string[];
+  runtime?: SessionRuntimeHints;
   update?: boolean;
   /** @deprecated Use backend: 'maestro'. */
   maestro?: boolean;
@@ -1383,7 +1502,11 @@ type AgentDeviceClient = {
     stateDir: (options?: AgentDeviceRequestOverrides & Pick<AgentDeviceClientConfig, 'stateDir'>) => Promise<string>;
     close: (options?: AgentDeviceRequestOverrides & {
       shutdown?: boolean;
+      saveScript?: boolean | string;
+      /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
+      force?: boolean;
     }) => Promise<SessionCloseResult>;
+    saveScript: (options?: SessionSaveScriptOptions) => Promise<SessionSaveScriptResult>;
     artifacts: (options?: CloudArtifactsOptions) => Promise<AgentArtifactsResult>;
   };
   apps: {
@@ -1414,30 +1537,30 @@ type AgentDeviceClient = {
   capture: {
     snapshot: (options?: CaptureSnapshotOptions) => Promise<CaptureSnapshotResult>;
     screenshot: (options?: CaptureScreenshotOptions) => Promise<CaptureScreenshotResult>;
-    diff: (options: CaptureDiffOptions) => Promise<CommandRequestResult>;
+    diff: (options: CaptureDiffOptions) => Promise<CommandResult<'diff'>>;
   };
   interactions: {
-    click: (options: ClickOptions) => Promise<CommandRequestResult>;
-    press: (options: PressOptions) => Promise<CommandRequestResult>;
-    longPress: (options: LongPressOptions) => Promise<CommandRequestResult>;
+    click: (options: ClickOptions) => Promise<CommandResult<'click'>>;
+    press: (options: PressOptions) => Promise<CommandResult<'press'>>;
+    longPress: (options: LongPressOptions) => Promise<CommandResult<'longpress'>>;
     swipe: (options: SwipeOptions) => Promise<CommandRequestResult>;
     pan: (options: PanOptions) => Promise<CommandRequestResult>;
     fling: (options: FlingOptions) => Promise<CommandRequestResult>;
     swipeGesture: (options: SwipeGestureOptions) => Promise<CommandRequestResult>;
     focus: (options: FocusOptions) => Promise<CommandRequestResult>;
     type: (options: TypeTextOptions) => Promise<CommandRequestResult>;
-    fill: (options: FillOptions) => Promise<CommandRequestResult>;
+    fill: (options: FillOptions) => Promise<CommandResult<'fill'>>;
     scroll: (options: ScrollOptions) => Promise<CommandRequestResult>;
     pinch: (options: PinchOptions) => Promise<CommandRequestResult>;
     rotateGesture: (options: RotateGestureOptions) => Promise<CommandRequestResult>;
     transformGesture: (options: TransformGestureOptions) => Promise<CommandRequestResult>;
     get: (options: GetOptions) => Promise<CommandRequestResult>;
     is: (options: IsOptions) => Promise<CommandRequestResult>;
-    find: (options: FindOptions) => Promise<CommandRequestResult>;
+    find: (options: FindOptions) => Promise<CommandResult<'find'>>;
   };
   replay: {
-    run: (options: ReplayRunOptions) => Promise<CommandRequestResult>;
-    test: (options: ReplayTestOptions) => Promise<CommandRequestResult>;
+    run: (options: ReplayRunOptions) => Promise<CommandResult<'replay'>>;
+    test: (options: ReplayTestOptions) => Promise<CommandResult<'test'>>;
   };
   batch: {
     run: (options: BatchRunOptions) => Promise<BatchRunResult>;
@@ -1453,15 +1576,15 @@ type AgentDeviceClient = {
     symbols: (options: DebugSymbolsOptions) => Promise<DebugSymbolsResult>;
   };
   recording: {
-    record: (options: RecordOptions) => Promise<CommandRequestResult>;
-    trace: (options: TraceOptions) => Promise<CommandRequestResult>;
+    record: (options: RecordOptions) => Promise<CommandResult<'record'>>;
+    trace: (options: TraceOptions) => Promise<CommandResult<'trace'>>;
   };
   settings: {
     update: (options: SettingsUpdateOptions) => Promise<CommandRequestResult>;
   };
 };
 //#endregion
-//#region src/client/client.d.ts
+//#region src/agent-device-client.d.ts
 declare function createAgentDeviceClient(config?: AgentDeviceClientConfig, deps?: {
   transport?: AgentDeviceDaemonTransport;
 }): AgentDeviceClient;