agent-device 0.20.10 → 0.21.1

package/dist/src/client-types.d.ts

@@ -1,8 +1,7 @@
-import { B as DeviceTarget, C as SnapshotNode, D as SnapshotUnchanged, H as PlatformSelector, L as AppleOS, M as NormalizedError, O as SnapshotVisibility, T as SnapshotQualityVerdict, U as PublicPlatform, _ as SessionRuntimeHints, a as DaemonRequest, f as LeaseBackend, g as SessionIsolationMode, h as ResponseLevel, i as DaemonLockPolicy, j as DaemonError, o as DaemonResponse, p as NetworkIncludeMode, r as DaemonInstallSource, s as DaemonResponseData, t as DaemonArtifact, z as DeviceKind } from "./sdk-contracts.js";
+import { A as SnapshotVisibility, B as DaemonError, C as SnapshotCommandOptionFields, D as SnapshotQualityVerdict, F as DeviceTarget, L as PlatformSelector, M as AppleOS, P as DeviceKind, R as PublicPlatform, V as NormalizedError, _ as SessionIsolationMode, a as DaemonRequest, f as LeaseBackend, g as ResponseLevel, i as DaemonLockPolicy, k as SnapshotUnchanged, m as NetworkIncludeMode, o as DaemonResponse, r as DaemonInstallSource, s as DaemonResponseData, t as DaemonArtifact, v as SessionRuntimeHints, w as SnapshotNode } from "./sdk-contracts.js";
 import { t as AppsFilter } from "./app-inventory.js";
-import { C as ClickButton, D as SnapshotDiagnosticsSummary, E as ScreenshotResultData, O as SessionSurface, S as BackMode, T as FindLocator, _ as SettleObservation, b as TvRemoteButton, d as ClickCommandResponseData, f as FillCommandResponseData, g as PressCommandResponseData, h as LongPressCommandResponseData, m as HoverCommandResponseData, p as FindCommandResponseData, w as AndroidSnapshotBackendMetadata, x as DeviceRotation } from "./sdk-selectors.js";
+import { A as ScrollInputDirection, C as BackMode, F as AndroidSnapshotBackendMetadata, I as FindLocator, L as ScreenshotResultData, M as SwipePreset, N as TransformGestureParams, P as ClickButton, R as SnapshotDiagnosticsSummary, S as DeviceRotation, _ as HoverCommandResponseData, b as SettleObservation, g as FindCommandResponseData, h as FillCommandResponseData, j as SwipePattern, k as ScrollDirection, m as ClickCommandResponseData, p as ScrollCommandResult, v as LongPressCommandResponseData, w as GesturePointerCount, x as TvRemoteButton, y as PressCommandResponseData, z as SessionSurface } from "./sdk-selectors.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 ScrollDirection, d as SwipePreset, f as TransformGestureParams, l as ScrollInputDirection, s as GesturePointerCount, u as SwipePattern } from "./sdk-android-adb.js";
 import { t as BatchRunResult } from "./sdk-batch-runner.js";
 import { r as CloudProviderSessionResult, t as AgentArtifactsResult } from "./cloud-artifacts.js";
 //#region packages/contracts/src/json.d.ts
@@ -79,6 +78,15 @@ type AgentDeviceDevice = {
    */
   appleOs?: AppleOS;
   identifiers: AgentDeviceIdentifiers;
+  /**
+   * Present when a host-local device claim currently blocks foreign use of
+   * this device (#1320). Provably dead owners are not projected — the next
+   * open reconciles and replaces them automatically.
+   */
+  claimedBy?: {
+    session: string;
+    workspace: string;
+  };
   ios?: {
     udid: string;
   };
@@ -123,6 +131,13 @@ type AgentDeviceSessionDevice = {
 };
 type AgentDeviceSession = {
   name: string;
+  /**
+   * The exact value `--session` must carry to address this session, which is not always `name`:
+   * a session opened without `--session` is named `default` but stored — and addressed — as
+   * `cwd:<hash>:default` (#2031/#1394). Optional only because a daemon older than the field does
+   * not send it.
+   */
+  address?: string;
   createdAt: number;
   sessionStateDir?: string;
   runnerLogPath?: string;
@@ -142,6 +157,16 @@ type DeviceBootOptions = DeviceCommandBaseOptions & {
 type DeviceShutdownOptions = DeviceCommandBaseOptions;
 //#endregion
 //#region packages/contracts/src/client-app.d.ts
+type DeviceSelectionReason = 'explicit-selector' | 'existing-session' | 'single-booted-local' | 'single-bootable-local' | 'single-app-installed-local' | 'preferred-local' | 'single-provider-device';
+type DeviceSelectionSource = 'session' | 'local' | 'provider';
+/** Deterministic device-selection evidence shared by daemon responses and the published client. */
+type DeviceSelectionMetadata = {
+  reason: DeviceSelectionReason;
+  source: DeviceSelectionSource;
+  candidateCount: number;
+  /** Whether this request booted a previously stopped local virtual target during open. */
+  bootOccurred: boolean;
+};
 type AppInstallOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
   app?: string;
   appPath: string;
@@ -167,10 +192,12 @@ type AppOpenOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions
   launchConsole?: string;
   launchArgs?: string[];
   relaunch?: boolean;
+  /** Startup budget in milliseconds: bounds the Simulator boot wait on a cold device. */
+  timeoutMs?: number;
   /**
-   * Include the initial interactive snapshot in a fresh open response. With
-   * no app argument, iOS can discover the sole running app on the sole booted
-   * simulator and fails closed when that environment is ambiguous.
+   * Include an initial interactive snapshot in a fresh open response. With no
+   * app argument, discover the sole running app on the sole booted iOS
+   * simulator; ambiguous environments fail closed.
    */
   foreground?: boolean;
   saveScript?: boolean | string;
@@ -193,6 +220,7 @@ type AppOpenResult = {
   appId?: string;
   startup?: StartupPerfSample;
   runtime?: SessionRuntimeHints;
+  selection?: DeviceSelectionMetadata;
   device?: AgentDeviceSessionDevice;
   /**
    * Initial interactive snapshot captured immediately after an open that
@@ -291,14 +319,17 @@ type PublicSnapshotCaptureAnnotations = Pick<SnapshotCaptureAnnotations, 'androi
 };
 //#endregion
 //#region packages/contracts/src/client-capture.d.ts
-type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
-  interactiveOnly?: boolean;
-  depth?: number;
-  scope?: string;
-  raw?: boolean;
-  /** List accessibility custom actions on merged elements (iOS simulator). */
-  customActions?: boolean;
-  forceFull?: boolean;
+type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & Omit<SnapshotCommandOptionFields, 'customActions'> & {
+  /**
+   * Name the affordances an element merged away (iOS UIAccessibilityCustomAction,
+   * React Native accessibilityActions) — a card whose reply/options controls are not
+   * separate elements still lists them here. The names are for PLANNING, not
+   * invocation: there is no API to trigger them, so reach the affordance through the
+   * element detail screen, through the same control exposed as a labeled element
+   * elsewhere, or by coordinates from its rect. iOS simulator only; costs one
+   * accessibility round trip per merged element.
+   */
+  customActions?: SnapshotCommandOptionFields['customActions'];
   timeoutMs?: number;
   /**
    * #1271 stage 2 (ADR 0012 amendment): `snapshot` is observation-only and
@@ -310,7 +341,8 @@ type CaptureSnapshotOptions = AgentDeviceRequestOverrides & AgentDeviceSelection
 };
 type CaptureSnapshotResult = {
   nodes: SnapshotNode[];
-  truncated: boolean;
+  /** Present only when the capture owner establishes whether the tree was truncated. */
+  truncated?: boolean;
   appName?: string;
   appBundleId?: string;
   visibility?: SnapshotVisibility;
@@ -341,6 +373,8 @@ type CaptureSnapshotResult = {
 type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
   path?: string;
   overlayRefs?: boolean;
+  /** Crop the capture to the frame of the selector resolved on the same screen. */
+  cropOn?: string;
   pixelDensity?: number;
   fullscreen?: boolean;
   scale?: number;
@@ -489,6 +523,8 @@ type ScrollOptions = DeviceCommandBaseOptions & SettleCommandOptions & {
   amount?: number;
   pixels?: number;
   durationMs?: number;
+  /** Repeat scroll passes until this selector is visible on screen, then stop. */
+  until?: string;
 };
 //#endregion
 //#region packages/contracts/src/client-lease.d.ts
@@ -530,13 +566,31 @@ type CloudArtifactsOptions = AgentDeviceRequestOverrides & {
   provider?: string;
   providerSessionId?: string;
 };
+type HumanControlHoldScope = {
+  backend: LeaseBackend;
+  leaseProvider?: string;
+  deviceKey: string;
+};
+type HumanControlHold = {
+  id: string;
+  scope: HumanControlHoldScope;
+  reason?: string;
+  state: 'activating' | 'active';
+  createdAt: number;
+  updatedAt: number;
+  expiresAt?: number;
+};
+type HumanControlHoldOptions = {
+  reason?: string;
+  ttlMs?: number;
+};
 //#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/perf.d.ts
-declare const PERF_AREA_VALUES: readonly ['metrics', 'frames', 'memory', 'cpu', 'trace'];
+declare const PERF_AREA_VALUES: readonly ['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'];
@@ -555,11 +609,8 @@ type RecordingScope = (typeof RECORDING_SCOPE_VALUES)[number];
 //#endregion
 //#region packages/contracts/src/client-observability.d.ts
 type PerfOptions = DeviceCommandBaseOptions & {
-  /**
-   * Select focused performance evidence. Omitted values retain the deprecated aggregate
-   * metrics response for compatibility; prefer an explicit area.
-   */
-  area?: PerfArea;
+  /** Select focused performance evidence. */
+  area: PerfArea;
   subject?: PerfSubject;
   action?: PerfAction;
   kind?: PerfKind;
@@ -718,6 +769,8 @@ type ReplaySuiteTestFailed = {
   attempts: number;
   artifactsDir?: string;
   error: DaemonError;
+  /** Present when the owning runtime classified the failure as device/runner infrastructure. */
+  infrastructure?: true;
   shardIndex?: number;
   shardCount?: number;
   deviceId?: string;
@@ -743,12 +796,24 @@ type ReplaySuiteResult = {
   durationMs: number;
   failures: ReplaySuiteTestFailed[];
   tests: ReplaySuiteTestResult[];
+  /**
+   * The suite's own artifacts root (the parent of every test's `artifactsDir`), as resolved on
+   * the host that ran the suite. Absent when the suite produced no attempt (e.g. every source
+   * was filtered out). #2246: a remote daemon rewrites this to the caller-local path once the
+   * directory has been transferred back, so it always names a path the caller can open.
+   */
+  artifactsDir?: string;
   snapshotDiagnostics?: SnapshotDiagnosticsSummary;
 };
 //#endregion
 //#region packages/contracts/src/client-request.d.ts
 type CommandRequestResult = DaemonResponseData;
 //#endregion
+//#region packages/contracts/src/is-predicate.d.ts
+/** The complete predicate vocabulary accepted by the `is` command. */
+declare const IS_PREDICATES: readonly ['visible', 'hidden', 'exists', 'absent', 'editable', 'selected', 'focused', 'text'];
+type IsPredicate = (typeof IS_PREDICATES)[number];
+//#endregion
 //#region packages/contracts/src/client-selector-read.d.ts
 /**
  * #1271 stage 2 (ADR 0012 amendment): `get`/`is`/`find` are observation-only
@@ -764,12 +829,12 @@ type GetOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & El
   format: 'text' | 'attrs';
 };
 type IsTextPredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & RecordControlOptions & {
-  predicate: 'text';
+  predicate: Extract<IsPredicate, 'text'>;
   selector: string;
   value: string;
 };
 type IsStatePredicateOptions = DeviceCommandBaseOptions & SelectorSnapshotCommandOptions & RecordControlOptions & {
-  predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected' | 'focused';
+  predicate: Exclude<IsPredicate, 'text'>;
   selector: string;
   value?: never;
 };
@@ -821,6 +886,9 @@ type SettingsUpdateOptions = (DeviceCommandBaseOptions & {
   setting: 'clear-app-state';
   state: 'clear';
   app?: string;
+}) | (DeviceCommandBaseOptions & {
+  setting: 'reset-keychain';
+  state: 'clear';
 }) | (DeviceCommandBaseOptions & {
   setting: 'wifi' | 'airplane' | 'location';
   state: 'on' | 'off';
@@ -858,6 +926,7 @@ type WaitCommandTarget = {
   text?: never;
   ref?: never;
   selector?: never;
+  absent?: never;
   stable?: never;
   quietMs?: never;
   timeoutMs?: never;
@@ -866,6 +935,7 @@ type WaitCommandTarget = {
   durationMs?: never;
   ref?: never;
   selector?: never;
+  absent?: never;
   stable?: never;
   quietMs?: never;
   timeoutMs?: number;
@@ -874,6 +944,7 @@ type WaitCommandTarget = {
   durationMs?: never;
   text?: never;
   selector?: never;
+  absent?: never;
   stable?: never;
   quietMs?: never;
   timeoutMs?: number;
@@ -882,6 +953,16 @@ type WaitCommandTarget = {
   durationMs?: never;
   text?: never;
   ref?: never;
+  absent?: never;
+  stable?: never;
+  quietMs?: never;
+  timeoutMs?: number;
+}) | (SelectorSnapshotCommandOptions & {
+  absent: string;
+  durationMs?: never;
+  text?: never;
+  ref?: never;
+  selector?: never;
   stable?: never;
   quietMs?: never;
   timeoutMs?: number;
@@ -891,6 +972,7 @@ type WaitCommandTarget = {
   text?: never;
   ref?: never;
   selector?: never;
+  absent?: never;
   quietMs?: number;
   timeoutMs?: number;
 });
@@ -900,6 +982,19 @@ type AlertCommandOptions = DeviceCommandBaseOptions & {
   timeoutMs?: number;
 };
 type AppStateCommandOptions = DeviceCommandBaseOptions;
+/** #1638: `back` carries the shared `--settle` triple, and its result may carry the settled diff. */
+type BackCommandOptions = DeviceCommandBaseOptions & {
+  mode?: BackMode;
+} & SettleCommandOptions;
+type HomeCommandOptions = DeviceCommandBaseOptions;
+type OrientationCommandOptions = DeviceCommandBaseOptions & {
+  orientation: DeviceRotation;
+};
+type AppSwitcherCommandOptions = DeviceCommandBaseOptions;
+type TvRemoteCommandOptions = DeviceCommandBaseOptions & {
+  button: TvRemoteButton;
+  durationMs?: number;
+};
 type KeyboardCommandOptions = DeviceCommandBaseOptions & {
   action?: 'status' | 'dismiss' | 'enter' | 'return';
 };
@@ -1009,136 +1104,6 @@ type ShutdownCommandResult = {
   appleOs?: AppleOS;
 };
 //#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;
-};
-//#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;
-  /** iOS `dismiss` only (#1598): which mechanism actually resigned the
-   *  keyboard — 'dismissKey' (tapped the keyboard's own Hide/Dismiss/Done
-   *  key). Generic background-tap dismissal is deliberately unsupported
-   *  (#1606 review): no query can prove a coordinate is side-effect-free,
-   *  so the runner only ever taps the keyboard's own control. Absent when
-   *  the keyboard was not dismissed. */
-  mechanism?: 'dismissKey';
-};
-//#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'`. The one field the generic route may add on top of the dispatch
- * handler's literal return: `settle`, the opt-in `--settle` observation
- * (#1638), attached after the command by the generic dispatcher.
- */
-type BackCommandResult = {
-  action: 'back';
-  mode: BackMode;
-  message: string;
-  settle?: SettleObservation;
-};
-/** `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/prepare.d.ts
 type PrepareIosRunnerCacheKind = 'exact' | 'restore-key' | 'miss' | 'external';
 type PrepareIosRunnerArtifactState = 'valid' | 'rebuilt';
@@ -1193,55 +1158,6 @@ type PushCommandResult = {
   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[];
-  not?: 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;
-  } & SettleCommandOptions, 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 packages/contracts/src/debug-symbols.d.ts
 type DebugSymbolsOptions = {
   action?: 'symbols';
@@ -1340,19 +1256,138 @@ type DiffSnapshotCommandResult = {
 };
 //#endregion
 //#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 packages/contracts/src/navigation.d.ts
+/**
+ * Closed results of the navigation/global action commands. Each mirrors its
+ * request-scoped runtime's literal return: 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'`. The one field the generic route may add on top of the dispatch
+ * runtime's literal return: `settle`, the opt-in `--settle` observation
+ * (#1638), attached after the command by the generic dispatcher.
+ */
+type BackCommandResult = {
+  action: 'back';
+  mode: BackMode;
+  message: string;
+  settle?: SettleObservation;
+};
+/**
+ * `orientation` — `{ action: 'orientation', orientation, message: 'Rotated to <orientation>' }`.
+ *
+ * An owner that reports no resulting rotation is not evidence that the device
+ * rotated. That case keeps the requested `orientation` for compatibility, but
+ * discloses `confirmed: false` plus a `warning`, and names the request in
+ * `message` (`Rotation requested: <orientation> (unconfirmed)`).
+ */
+type OrientationCommandResult = {
+  action: 'orientation';
+  orientation: DeviceRotation;
+  message: string;
+  confirmed?: boolean;
+  warning?: 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/clipboard.d.ts
+/**
+ * Closed result of the `clipboard` command. Mirrors the session runtime's
+ * literal return exactly (`src/daemon/handlers/session-clipboard.ts`): 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 packages/contracts/src/keyboard.d.ts
+/**
+ * Closed result of the `keyboard` command, grounded in the runtime operation
+ * results projected by `src/daemon/keyboard-runtime.ts`.
+ *
+ * `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;
+  /** iOS `dismiss` only (#1598): which mechanism actually resigned the
+   *  keyboard — 'dismissKey' (tapped the keyboard's own Hide/Dismiss/Done
+   *  key). Generic background-tap dismissal is deliberately unsupported
+   *  (#1606 review): no query can prove a coordinate is side-effect-free,
+   *  so the runner only ever taps the keyboard's own control. Absent when
+   *  the keyboard was not dismissed. */
+  mechanism?: 'dismissKey';
+};
+//#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/recording.d.ts
 type RecordingAppIdentity = {
   bundleId: string;
@@ -1396,7 +1431,7 @@ type TraceCommandResult = {
   artifacts: DaemonArtifact[];
 };
 //#endregion
-//#region src/core/command-descriptor/command-result.d.ts
+//#region packages/command-registry/src/command-result.d.ts
 /**
  * The additive typed-result spine (ADR-0008, Phase 1 step 6).
  *
@@ -1413,37 +1448,42 @@ type TraceCommandResult = {
  * `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`,
- * `prepare`, `push`, and `trigger-app-event`. Each entry is grounded in a
+ * `prepare`, `push`, and `trigger-app-event`. #1652 adds `scroll`
+ * (ScrollCommandResult): the shared dispatch vocabulary plus the opt-in
+ * settle observation, so the settle-capable generic-route pair (`back`,
+ * `scroll`) is fully typed and its MCP output schema derives from the trait.
+ * Each entry is grounded in a
  * re-read of the handler's literal return; see the per-type docstrings.
  */
 interface CommandResultMap {
-  press: PressCommandResponseData;
+  'app-switcher': AppSwitcherCommandResult;
+  appstate: AppStateCommandResult;
+  back: BackCommandResult;
+  boot: BootCommandResult;
   click: ClickCommandResponseData;
+  clipboard: ClipboardCommandResult;
+  diff: DiffSnapshotCommandResult;
+  doctor: DoctorCommandResult;
   fill: FillCommandResponseData;
-  longpress: LongPressCommandResponseData;
-  hover: HoverCommandResponseData;
   find: FindCommandResponseData;
-  boot: BootCommandResult;
-  shutdown: ShutdownCommandResult;
-  viewport: ViewportCommandResult;
   home: HomeCommandResult;
-  back: BackCommandResult;
-  orientation: OrientationCommandResult;
-  'app-switcher': AppSwitcherCommandResult;
-  clipboard: ClipboardCommandResult;
-  appstate: AppStateCommandResult;
+  hover: HoverCommandResponseData;
   keyboard: KeyboardCommandResult;
-  'tv-remote': TvRemoteCommandResult;
-  wait: WaitCommandResult;
+  longpress: LongPressCommandResponseData;
+  orientation: OrientationCommandResult;
   prepare: PrepareCommandResult;
+  press: PressCommandResponseData;
   push: PushCommandResult;
-  'trigger-app-event': TriggerAppEventCommandResult;
-  doctor: DoctorCommandResult;
-  diff: DiffSnapshotCommandResult;
+  record: RecordingCommandResult;
   replay: ReplayCommandResult;
+  scroll: ScrollCommandResult;
+  shutdown: ShutdownCommandResult;
   test: ReplaySuiteResult;
-  record: RecordingCommandResult;
   trace: TraceCommandResult;
+  'trigger-app-event': TriggerAppEventCommandResult;
+  'tv-remote': TvRemoteCommandResult;
+  viewport: ViewportCommandResult;
+  wait: WaitCommandResult;
 }
 /**
  * The typed result for a command named `N`. Seeded commands resolve to their
@@ -1455,10 +1495,12 @@ interface CommandResultMap {
 type CommandResult<N extends string> = N extends keyof CommandResultMap ? CommandResultMap[N] : Record<string, unknown>;
 //#endregion
 //#region src/client/client-types.d.ts
-type OrientationCommandOptions = DeviceCommandBaseOptions & NavigationCommandOptions<'orientation'>;
-/** @deprecated Renamed to `OrientationCommandOptions`. Retained until the next major. */
-type RotateCommandOptions = OrientationCommandOptions;
-type NonNavigationCommandClient = {
+type AgentDeviceCommandClient = {
+  back: (options?: BackCommandOptions) => Promise<CommandResult<'back'>>;
+  home: (options?: HomeCommandOptions) => Promise<CommandResult<'home'>>;
+  orientation: (options: OrientationCommandOptions) => Promise<CommandResult<'orientation'>>;
+  appSwitcher: (options?: AppSwitcherCommandOptions) => Promise<CommandResult<'app-switcher'>>;
+  tvRemote: (options: TvRemoteCommandOptions) => Promise<CommandResult<'tv-remote'>>;
   wait: (options: WaitCommandOptions) => Promise<CommandResult<'wait'>>;
   alert: (options?: AlertCommandOptions) => Promise<CommandRequestResult>;
   appState: (options?: AppStateCommandOptions) => Promise<CommandResult<'appstate'>>;
@@ -1473,15 +1515,6 @@ type NonNavigationCommandClient = {
   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 AgentDeviceClient = {
   command: AgentDeviceCommandClient;
   devices: {
@@ -1522,6 +1555,11 @@ type AgentDeviceClient = {
       released: boolean;
       provider?: CloudProviderSessionResult;
     }>;
+    humanControl: {
+      list: (options?: AgentDeviceRequestOverrides) => Promise<HumanControlHold[]>;
+      put: (id: string, input?: HumanControlHoldOptions, options?: AgentDeviceRequestOverrides) => Promise<HumanControlHold>;
+      remove: (id: string, options?: AgentDeviceRequestOverrides) => Promise<boolean>;
+    };
   };
   metro: {
     prepare: (options: MetroPrepareOptions) => Promise<MetroPrepareResult>;
@@ -1561,7 +1599,7 @@ type AgentDeviceClient = {
     run: (options: BatchRunOptions) => Promise<BatchRunResult>;
   };
   observability: {
-    perf: (options?: PerfOptions) => Promise<CommandRequestResult>;
+    perf: (options: PerfOptions) => Promise<CommandRequestResult>;
     logs: (options?: LogsOptions) => Promise<CommandRequestResult>;
     events: (options?: EventsOptions) => Promise<CommandRequestResult>;
     network: (options?: NetworkOptions) => Promise<CommandRequestResult>;