agent-device 0.20.10 → 0.21.1

package/dist/src/sdk-selectors.d.ts

@@ -1,5 +1,4 @@
-import { C as SnapshotNode, E as SnapshotState, S as SnapshotBackend, T as SnapshotQualityVerdict, U as PublicPlatform, V as Platform, b as Rect, m as ResponseCost, v as Point, w as SnapshotOptions$1, x as ScreenshotOverlayRef, y as RawSnapshotNode } from "./sdk-contracts.js";
-import { c as ScrollDirection, o as GesturePlan } from "./sdk-android-adb.js";
+import { D as SnapshotQualityVerdict, E as SnapshotProvenance, I as Platform, O as SnapshotState, R as PublicPlatform, S as ScreenshotOverlayRef, T as SnapshotOptions$1, b as RawSnapshotNode, h as ResponseCost, w as SnapshotNode, x as Rect, y as Point } from "./sdk-contracts.js";
 //#region packages/contracts/src/session-surface.d.ts
 declare const SESSION_SURFACES: readonly ['app', 'frontmost-app', 'desktop', 'menubar'];
 type SessionSurface = (typeof SESSION_SURFACES)[number];
@@ -28,6 +27,7 @@ type ScreenshotResultData = {
   logicalHeight?: number;
   pixelDensity?: number;
   overlayRefs?: ScreenshotOverlayRef[];
+  warnings?: string[];
 };
 type BackendSnapshotResult = {
   nodes?: SnapshotNode[];
@@ -70,7 +70,12 @@ type AndroidSnapshotBackendMetadata = {
   nodeCount?: number;
   helperTruncated?: boolean;
   elapsedMs?: number;
-  /** API 23 helper output carries no `drawing-order`; covered same-window surfaces are not pruned. */
+  presentationFailure?: {
+    phase: 'deadline' | 'complexity' | 'regular-invariant';
+    workUnits: number;
+    maxWorkUnits?: number;
+  };
+  /** API 23 exposes no sibling drawing order, so same-window occlusion fails conservative. */
   occlusionScanUnavailable?: boolean;
 };
 type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
@@ -79,6 +84,58 @@ type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
 declare const CLICK_BUTTONS: readonly ['primary', 'secondary', 'middle'];
 type ClickButton = (typeof CLICK_BUTTONS)[number];
 //#endregion
+//#region packages/contracts/src/scroll-gesture.d.ts
+declare const SCROLL_INPUT_DIRECTIONS: readonly ['up', 'down', 'left', 'right', 'top', 'bottom'];
+type ScrollInputDirection = (typeof SCROLL_INPUT_DIRECTIONS)[number];
+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;
+  durationMs?: number;
+};
+//#endregion
+//#region packages/contracts/src/gesture-plan-types.d.ts
+type GesturePointerCount = 1 | 2;
+/** Selects one-pointer release timing without changing semantic gesture intent. */
+type GestureExecutionProfile = 'endpoint-hold' | 'timed-pan';
+type PointerTrajectorySample = {
+  offsetMs: number;
+  point: Point;
+};
+type PointerTrajectory = {
+  pointerId: 0 | 1;
+  samples: readonly PointerTrajectorySample[];
+};
+type SinglePointerTrajectory = {
+  pointerId: 0;
+  samples: readonly [PointerTrajectorySample, PointerTrajectorySample, ...PointerTrajectorySample[]];
+};
+type SinglePointerGesturePlan = {
+  topology: 'single';
+  intent: 'fling' | 'pan';
+  executionProfile: GestureExecutionProfile;
+  durationMs: number;
+  viewport: Rect;
+  pointers: readonly [SinglePointerTrajectory];
+};
+type MultiTouchGesturePlan = {
+  topology: 'two';
+  intent: 'pan' | 'pinch' | 'rotate' | 'transform';
+  durationMs: number;
+  viewport: Rect;
+  pointers: readonly [PointerTrajectory, PointerTrajectory];
+};
+type GesturePlan = SinglePointerGesturePlan | MultiTouchGesturePlan;
+//#endregion
 //#region packages/contracts/src/back-mode.d.ts
 declare const BACK_MODES: readonly ['in-app', 'system'];
 type BackMode = (typeof BACK_MODES)[number];
@@ -141,145 +198,33 @@ 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 packages/contracts/src/settings.d.ts
-type SettingOptions = {
-  permissionTarget?: string;
-  permissionMode?: string;
-  latitude?: number;
-  longitude?: number;
-};
-//#endregion
-//#region packages/contracts/src/runner-lease-context.d.ts
-type RunnerLogicalLeaseContext = {
-  leaseId?: string;
-  clientId?: string;
-  tenantId?: string;
-  runId?: string;
-  leaseProvider?: string;
-  deviceKey?: string;
-};
-//#endregion
-//#region packages/contracts/src/interactor-types.d.ts
-type RunnerContext = {
-  requestId?: string;
-  signal?: AbortSignal;
-  appBundleId?: string;
-  verbose?: boolean;
-  logPath?: string;
-  traceLogPath?: string;
-  iosXctestrunFile?: string;
-  iosXctestDerivedDataPath?: string;
-  iosXctestEnvDir?: string;
-  runnerLeaseContext?: RunnerLogicalLeaseContext;
-};
-type ScreenshotOptions = {
-  appBundleId?: string;
-  pixelDensity?: number;
-  fullscreen?: boolean;
-  normalizeStatusBar?: boolean;
-  stabilize?: boolean;
-  surface?: SessionSurface;
-  skipIosSimulatorBootCheck?: boolean;
-  captureBackend?: 'runner';
-};
-type ElementSelectorKey = 'id' | 'label' | 'text' | 'value';
-type ElementSelectorTapOptions = {
-  key: ElementSelectorKey;
-  value: string;
-  allowNonHittableCoordinateFallback?: boolean;
-  expectedPoint?: Point;
-};
+//#region packages/contracts/src/ios-system-surface.d.ts
 /**
- * The channel the XCTest runner actually entered text through — the Swift
- * `TextEntryResult.textEntryRoute` (RunnerTests+TextTyping.swift,
- * RunnerTests+SynthesizedTextEntry.swift). Closed set, because the runner is
- * its only producer and the boundary that narrows it
- * (readTypeTextBackendResult, src/platforms/apple/interactions.ts) drops a
- * route it cannot name — so a Swift-side addition would silently vanish. The
- * route-parity test in src/platforms/apple/core/__tests__/interactions.test.ts
- * reads the Swift sources and fails instead.
+ * iOS out-of-process system surfaces that agent-device observes and drives IN PLACE, never by
+ * activation.
+ *
+ * `com.apple.SafariViewService` hosts `ASWebAuthenticationSession` and `SFSafariViewController`
+ * out of the app's process. It is presented over a still-foreground app, and any
+ * `XCUIApplication.activate()` or `simctl launch` on it cancels the authentication session and
+ * blacks the view (issue #2438). So the runner reads and drives it without activation, and the
+ * `open` path refuses to launch it. The set is deliberately closed and tiny; add a host only with
+ * live evidence that it presents out of process and dies on activation.
+ *
+ * The canonical membership lives in `contracts/fixtures/ios-system-surface-hosts.json`; this module
+ * and the Swift `SystemSurfaceHostRegistry` both mirror it, each guarded by a parity test.
  */
-declare const TEXT_ENTRY_ROUTES: readonly ['xctest-element', 'synthesized-first-responder', 'synthesized-first-responder-replacement', 'xctest-application-fallback'];
-type TextEntryRoute = (typeof TEXT_ENTRY_ROUTES)[number];
+/** Why a system surface is served in place; carried at snapshot-response level as provenance. */
+type IosSystemSurfaceKind = 'web-auth';
 /**
- * What `Interactor.type` reports back about the entry it performed. Only the
- * Apple runner populates it; every other platform types blind and returns void.
+ * Whole-snapshot provenance: the capture describes a system surface presented over the session app,
+ * not the app itself. Carried at response level (it applies to the entire snapshot) and folded into
+ * iOS snapshot lineage so `--verify`/`--settle` never compare an app baseline against a sheet
+ * capture. Mirrors the Android system-chrome/system-surface provenance model.
  */
-type TypeTextBackendResult = {
-  textEntryRoute?: TextEntryRoute;
-};
-type FillVerificationTarget = {
-  resourceId: string | null;
-  className: string | null;
-  packageName: string | null;
-  rect: Rect;
-};
-type FillUnconfirmedVerification = {
-  verification: 'unconfirmed';
-  requested: string;
-  before: string | null;
-  after: string | null;
-  target: FillVerificationTarget;
-};
-type SnapshotOptions = SnapshotOptions$1 & {
-  appBundleId?: string;
-  signal?: AbortSignal;
-  includeRects?: boolean;
-  includeHiddenContentHints?: boolean;
-  surface?: SessionSurface;
-};
-type SnapshotResult = Omit<BackendSnapshotResult, 'backend' | 'nodes'> & {
-  nodes?: RawSnapshotNode[];
-  backend: Extract<SnapshotBackend, 'android' | 'harmonyos-arkui' | 'xctest' | 'linux-atspi' | 'macos-helper' | 'web'>;
-};
-type Interactor = {
-  open(app: string, options?: {
-    activity?: string;
-    appBundleId?: string;
-    launchConsole?: string;
-    launchArgs?: string[];
-    terminateRunningApp?: boolean;
-    url?: string;
-  }): Promise<void>;
-  openDevice(): Promise<void>;
-  close(app: string): Promise<void>;
-  tap(x: number, y: number): Promise<Record<string, unknown> | void>;
-  tapElementSelector?(selector: ElementSelectorTapOptions): Promise<Record<string, unknown> | void>;
-  doubleTap(x: number, y: number): Promise<Record<string, unknown> | void>;
-  longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
-  /**
-   * Move the pointer to a point without pressing. Only pointer-driven
-   * platforms (web today) implement it; touch platforms have no hover state
-   * and leave it undefined, which the `hover` command reports as unsupported.
-   */
-  hover?(x: number, y: number): Promise<Record<string, unknown> | void>;
-  focus(x: number, y: number): Promise<Record<string, unknown> | void>;
-  type(text: string, delayMs?: number): Promise<TypeTextBackendResult | void>;
-  fillElementSelector?(selector: ElementSelectorTapOptions, text: string, delayMs?: number): Promise<Record<string, unknown> | void>;
-  fill(x: number, y: number, text: string, delayMs?: number, options?: {
-    allowNonHittableCoordinateFallback?: boolean;
-  }): Promise<Record<string, unknown> | void>;
-  scroll(direction: ScrollDirection, options?: {
-    amount?: number;
-    pixels?: number;
-    durationMs?: number;
-  }): Promise<Record<string, unknown> | void>;
-  screenshot(outPath: string, options?: ScreenshotOptions): Promise<void>;
-  setViewport?(width: number, height: number): Promise<Record<string, unknown> | void>;
-  snapshot(options?: SnapshotOptions): Promise<SnapshotResult>;
-  gestureViewport?(): Promise<Rect>;
-  back(mode?: BackMode): Promise<void>;
-  home(): Promise<void>;
-  setOrientation(orientation: DeviceRotation): Promise<{
-    orientation?: DeviceRotation;
-  } | void>;
-  performGesture?(plan: GesturePlan): Promise<Record<string, unknown> | void>;
-  appSwitcher(): Promise<void>;
-  tvRemote(button: TvRemoteButton, durationMs?: number): Promise<void>;
-  readClipboard(): Promise<string>;
-  writeClipboard(text: string): Promise<void>;
-  setSetting(setting: string, state: string, appId?: string, options?: SettingOptions): Promise<Record<string, unknown> | void>;
-};
+type IosSystemSurfaceProvenance = Readonly<{
+  bundleId: string;
+  kind: IosSystemSurfaceKind;
+}>;
 //#endregion
 //#region packages/contracts/src/interaction.d.ts
 /** The decisive criterion separating a resolveSelectorChain winner from its strongest runner-up (ADR 0012). */
@@ -327,6 +272,22 @@ type ResolutionDisclosure = {
   source: 'direct-ios';
   kind: 'not-observed';
 };
+/**
+ * A post-action capture that describes a DIFFERENT surface than the pre-action baseline (#2438): an
+ * in-place iOS system surface (a web sign-in sheet, hosted out of the app's process) was presented
+ * over the app, or left it. `from`/`to` name the two surfaces — a host bundle id, or `app` for
+ * ordinary app content.
+ *
+ * Its presence IS the refusal of a same-surface claim: the two captures are not one presentation,
+ * so `--verify` reports `changedFromBefore` from this transition instead of from a digest
+ * comparison across it, and `--settle` attaches no settled diff (and therefore no refs) across it.
+ */
+type PostActionSurfaceChange = {
+  from: string;
+  to: string;
+  /** The one agent-facing sentence for this transition (`@agent-device/contracts/ios-system-surface`). */
+  disclosure: string;
+};
 /**
  * Opt-in (`--verify`) cheap post-condition evidence for mutating interaction
  * commands (#1047). `digest`/`nodeCount`/`interactiveNodeCount` describe a single
@@ -335,6 +296,10 @@ type ResolutionDisclosure = {
  * held, so no extra device round trip is spent beyond the one verify capture.
  * `changedFromBefore: false` is evidence, not failure — the command still
  * succeeded.
+ *
+ * When `surfaceChange` is present the two captures describe different surfaces, so the digest
+ * comparison is not made at all: `changedFromBefore` then reports that transition, which replaced
+ * the whole observed surface.
  */
 type InteractionEvidence = {
   foregroundApp?: string;
@@ -342,6 +307,7 @@ type InteractionEvidence = {
   interactiveNodeCount: number;
   digest: string;
   changedFromBefore: boolean;
+  surfaceChange?: PostActionSurfaceChange;
 };
 type SettleDiffLine = {
   kind: 'added' | 'removed';
@@ -385,7 +351,17 @@ type SettleObservation = {
   refs?: Array<{
     ref: string;
   }>;
-  /** Present only for `settled: true` observations that stored the settled tree. */
+  /**
+   * Present when the settled capture describes a different surface than the pre-action baseline
+   * (#2438). The settled tree then replaced the whole surface rather than changing within one, so
+   * `diff` is omitted: its lines (and their refs) would present a surface replacement as an
+   * in-surface change. `hint` says what to do instead.
+   */
+  surfaceChange?: PostActionSurfaceChange;
+  /**
+   * Present only for `settled: true` observations that stored the settled tree, and never across a
+   * `surfaceChange` — a diff describes change WITHIN one surface.
+   */
   diff?: {
     summary: {
       additions: number;
@@ -520,6 +496,414 @@ type FindCommandResponseData = {
   cost?: ResponseCost;
 };
 //#endregion
+//#region packages/contracts/src/scroll-command.d.ts
+type ScrollReleaseBehavior = 'controlled' | 'inertial';
+type ScrollDistanceOptions = {
+  amount?: number;
+  pixels?: number;
+};
+type ScrollTimingOptions = {
+  durationMs?: number;
+};
+type ScrollCommandOptions = ScrollDistanceOptions & ScrollTimingOptions;
+type ScrollExecutionOptions = ScrollCommandOptions & {
+  releaseBehavior?: ScrollReleaseBehavior;
+};
+/**
+ * `scroll` — the generic-route result built by `buildDispatchedScrollResult`
+ * (src/core/dispatch-scroll.ts): the resolved direction, the edge-pass
+ * bookkeeping for `top`/`bottom` scrolls, the honored distance/timing echo,
+ * and the success message. Platform leaves add gesture-plan coordinates
+ * (`x1`/`y1`/`x2`/`y2`, reference frame) on top; the output schema stays
+ * non-strict so those additive fields validate. The one field the dispatcher
+ * itself may add: `settle`, the opt-in `--settle` observation (#1638),
+ * attached after the command — same shape as `BackCommandResult`.
+ */
+type ScrollCommandResult = {
+  direction: ScrollDirection;
+  /** Set for `top`/`bottom` requests: the extreme being scrolled to. */
+  edge?: 'top' | 'bottom';
+  /** Set for `--until` requests: the selector the passes stopped on. */
+  until?: string;
+  /** Edge and until scrolls only: how many scroll-and-check passes ran. */
+  passes?: number;
+  amount?: number;
+  pixels?: number;
+  durationMs?: number;
+  message?: string;
+  settle?: SettleObservation;
+};
+//#endregion
+//#region packages/contracts/src/settings.d.ts
+type SettingOptions = {
+  permissionTarget?: string;
+  permissionMode?: string;
+  latitude?: number;
+  longitude?: number;
+};
+//#endregion
+//#region packages/contracts/src/runner-lease-context.d.ts
+type RunnerLogicalLeaseContext = {
+  leaseId?: string;
+  clientId?: string;
+  tenantId?: string;
+  runId?: string;
+  leaseProvider?: string;
+  deviceKey?: string;
+};
+//#endregion
+//#region packages/contracts/src/ios-snapshot.d.ts
+type IosSnapshotProducer = 'apple-runner' | 'simulator-ax-bridge' | 'appium-source' | 'limrun-ios-tree';
+type IosAcquisitionProducer = Exclude<IosSnapshotProducer, 'apple-runner'>;
+type IosAcquisitionIntent = 'full' | 'surface-observation';
+type IosSnapshotProjection = 'regular' | 'raw';
+type IosSnapshotGeneration = string;
+type IosSnapshotLineage = Readonly<{
+  targetId?: string;
+  generation?: IosSnapshotGeneration;
+}>;
+type IosSnapshotPresentationKey = Readonly<{
+  projection: IosSnapshotProjection;
+  interactiveOnly: boolean;
+  depth: number | null;
+  scope: string | null;
+  customActions: boolean;
+}>;
+type CaptureHint = Readonly<{
+  projection: IosSnapshotProjection;
+  rawTraversalDepth: number | null;
+  regularPresentedDepth: number | null;
+  interactiveOnly: boolean;
+  customActions: boolean;
+  acquisitionIntent: IosAcquisitionIntent;
+}>;
+type IosSnapshotFact = 'acquisition-depth' | 'scope' | 'interactive-query' | 'viewport' | 'hittability' | 'generation' | 'truncation';
+type IosViewportEvidence = Readonly<{
+  kind: 'reported';
+  rect: Rect;
+}> | Readonly<{
+  kind: 'derived';
+  rect: Rect;
+}> | Readonly<{
+  kind: 'missing';
+  reason: 'not-provided' | 'not-supported' | 'invalid';
+}>;
+type IosProviderPrunedField = 'nodes' | 'depth' | 'scope' | 'interactive-only';
+type IosTruncationDimension = 'nodes' | 'depth' | 'payload';
+type IosAcquisitionResidue = Readonly<{
+  kind: 'provider-pruned';
+  fields: readonly IosProviderPrunedField[];
+}> | Readonly<{
+  kind: 'missing-viewport';
+  reason: 'not-provided' | 'not-supported' | 'invalid';
+}> | Readonly<{
+  kind: 'truncated';
+  dimension: IosTruncationDimension;
+  limit?: number;
+}> | Readonly<{
+  kind: 'stale-generation';
+  expected?: IosSnapshotGeneration;
+  observed?: IosSnapshotGeneration;
+}> | Readonly<{
+  kind: 'unknown-generation';
+  captureId: string;
+}> | Readonly<{
+  kind: 'unavailable-fact';
+  fact: IosSnapshotFact;
+}> | Readonly<{
+  kind: 'fallback-source';
+  producer: IosSnapshotProducer;
+}>;
+type IosSnapshotAcquisitionForIntent<Intent extends IosAcquisitionIntent> = Readonly<{
+  producer: IosAcquisitionProducer;
+  intent: Intent;
+  hint: CaptureHint & Readonly<{
+    acquisitionIntent: Intent;
+  }>;
+  nodes: readonly RawSnapshotNode[];
+  truncated?: boolean;
+  viewport: IosViewportEvidence;
+  lineage: IosSnapshotLineage;
+  residue: readonly IosAcquisitionResidue[];
+}>;
+type IosSnapshotAcquisition = IosSnapshotAcquisitionForIntent<'full'> | IosSnapshotAcquisitionForIntent<'surface-observation'>;
+type IosSnapshotAcquisitionFacts = Omit<IosSnapshotAcquisition, 'hint'>;
+type IosSnapshotComparisonIdentity = Readonly<{
+  producer: IosSnapshotProducer;
+  intent: IosAcquisitionIntent;
+  lineage: IosSnapshotLineage;
+  presentationKey: IosSnapshotPresentationKey;
+  residue: readonly IosAcquisitionResidue[];
+}>;
+//#endregion
+//#region packages/contracts/src/interactor-types.d.ts
+type RunnerContext = {
+  requestId?: string;
+  signal?: AbortSignal;
+  appBundleId?: string;
+  verbose?: boolean;
+  logPath?: string;
+  traceLogPath?: string;
+  iosXctestrunFile?: string;
+  iosXctestDerivedDataPath?: string;
+  iosXctestEnvDir?: string;
+  runnerLeaseContext?: RunnerLogicalLeaseContext;
+};
+type ScreenshotOptions = {
+  appBundleId?: string;
+  pixelDensity?: number;
+  fullscreen?: boolean;
+  normalizeStatusBar?: boolean;
+  stabilize?: boolean;
+  surface?: SessionSurface;
+  skipIosSimulatorBootCheck?: boolean;
+  captureBackend?: 'runner';
+};
+type ElementSelectorKey = 'id' | 'label' | 'text' | 'value';
+type ElementSelectorTapOptions = {
+  key: ElementSelectorKey;
+  value: string;
+  allowNonHittableCoordinateFallback?: boolean;
+  expectedPoint?: Point;
+};
+type PressPointOptions = Readonly<{
+  button: 'primary' | 'secondary' | 'middle';
+  count: number;
+  intervalMs: number;
+  holdMs: number;
+  jitterPx: number;
+  doubleTap: boolean;
+  surface?: SessionSurface;
+}>;
+/**
+ * The channel the XCTest runner actually entered text through — the Swift
+ * `TextEntryResult.textEntryRoute` (RunnerTests+TextTyping.swift,
+ * RunnerTests+SynthesizedTextEntry.swift). Closed set, because the runner is
+ * its only producer and the boundary that narrows it
+ * (readTypeTextBackendResult, packages/platform-apple/src/interactions.ts) drops a
+ * route it cannot name — so a Swift-side addition would silently vanish. The
+ * route-parity test in packages/platform-apple/src/core/__tests__/interactions.test.ts
+ * reads the Swift sources and fails instead.
+ */
+declare const TEXT_ENTRY_ROUTES: readonly ['xctest-element', 'synthesized-first-responder', 'synthesized-first-responder-replacement', 'xctest-application-fallback'];
+type TextEntryRoute = (typeof TEXT_ENTRY_ROUTES)[number];
+/**
+ * What `Interactor.type` reports back about the entry it performed. Only the
+ * Apple runner populates it; every other platform types blind and returns void.
+ */
+type TypeTextBackendResult = {
+  textEntryRoute?: TextEntryRoute;
+};
+type FillVerificationTarget = {
+  resourceId: string | null;
+  className: string | null;
+  packageName: string | null;
+  rect: Rect;
+};
+type FillUnconfirmedVerification = {
+  verification: 'unconfirmed';
+  requested: string;
+  before: string | null;
+  after: string | null;
+  target: FillVerificationTarget;
+};
+type SnapshotOptions = SnapshotOptions$1 & {
+  appBundleId?: string;
+  signal?: AbortSignal;
+  includeRects?: boolean;
+  includeHiddenContentHints?: boolean;
+  surface?: SessionSurface;
+  /** Internal capture purpose; action outcomes always require the full tree. */
+  acquisitionIntent?: 'full' | 'surface-observation';
+};
+/**
+ * Android's live IME status read. Optional on {@link Interactor}: parity with the retired leaf,
+ * which refused `status`/`get` on every other family (no other platform's runner exposes one).
+ * A single-member discriminated union rather than a bare object so the daemon can derive its wire
+ * `platform` label from `kind` the same way it does for dismiss and enter — an owner can only ever
+ * produce its own result shape.
+ */
+type KeyboardStatusResult = Readonly<{
+  kind: 'ime-probe';
+  visible: boolean;
+  inputType?: string;
+  type?: string;
+  inputMethodPackage?: string;
+  focusedPackage?: string;
+  focusedResourceId?: string;
+  inputOwner?: string;
+}>;
+/**
+ * Owner-shaped dismiss evidence, discriminated by which owner produced it: Android's IME probe
+ * fields, or iOS's `mechanism` disclosure (#1598), or HarmonyOS's bare acknowledgment (its HDC
+ * key press reports nothing beyond success). The daemon derives the wire `platform` label from
+ * `kind` rather than re-deriving it from the device, so an owner can only ever produce its own
+ * result shape — an android-probe result under an `ios` label is unrepresentable.
+ */
+type KeyboardDismissResult = Readonly<{
+  kind: 'ime-probe';
+  attempts?: number;
+  wasVisible?: boolean;
+  dismissed?: boolean;
+  visible?: boolean;
+  inputType?: string;
+  type?: string;
+  inputMethodPackage?: string;
+  focusedPackage?: string;
+  focusedResourceId?: string;
+  inputOwner?: string;
+}> | Readonly<{
+  kind: 'mechanism';
+  wasVisible?: boolean;
+  dismissed?: boolean;
+  visible?: boolean;
+  mechanism?: string;
+}> | Readonly<{
+  kind: 'acknowledged';
+}>;
+/**
+ * Only the Apple runner echoes visibility around the return-key press; Android and HarmonyOS
+ * acknowledge with no fields beyond success. Kind is owner-specific, not just content-shaped —
+ * Android's and HarmonyOS's acknowledgments are structurally identical, so only the discriminant
+ * itself tells the daemon which owner actually pressed enter.
+ */
+type KeyboardEnterResult = Readonly<{
+  kind: 'visibility-echo';
+  visible?: boolean;
+  wasVisible?: boolean;
+}> | Readonly<{
+  kind: 'android-acknowledged';
+}> | Readonly<{
+  kind: 'harmonyos-acknowledged';
+}>;
+/**
+ * Every acquisition carries its provenance pair atomically: the channel alone cannot say who
+ * acquired the tree or which guarantees it carries, and `SnapshotProvenance`
+ * (`@agent-device/kernel/snapshot`) makes a cross-channel `backend`/`producer` combination
+ * fail to compile.
+ */
+type SnapshotResult = Omit<BackendSnapshotResult, 'backend' | 'nodes'> & {
+  nodes?: RawSnapshotNode[];
+  comparisonIdentity?: IosSnapshotComparisonIdentity;
+  /**
+   * Set when the capture describes an in-place iOS system surface (a web sign-in sheet) presented
+   * over the session app rather than the app itself (#2438).
+   */
+  systemSurface?: IosSystemSurfaceProvenance;
+} & SnapshotProvenance;
+type SnapshotRuntimeAcquiredResult = Readonly<{
+  stage: 'acquired';
+  acquisition: IosSnapshotAcquisitionFacts & Readonly<{
+    producer: IosAcquisitionProducer;
+  }>;
+}>;
+type SnapshotRuntimeResult = SnapshotResult | SnapshotRuntimeAcquiredResult;
+type Interactor = {
+  open(app: string, options?: {
+    activity?: string;
+    appBundleId?: string;
+    launchConsole?: string;
+    launchArgs?: string[];
+    terminateRunningApp?: boolean;
+    url?: string;
+  }): Promise<void>;
+  openDevice(): Promise<void>;
+  close(app: string): Promise<void>;
+  tap(x: number, y: number): Promise<Record<string, unknown> | void>;
+  /** Complete point-press semantics for owners with fused series, alternate buttons, or surfaces. */
+  pressPoint?(point: Point, options: PressPointOptions): Promise<Record<string, unknown> | void>;
+  /** Alternate mouse buttons for owners that otherwise use the shared point-press series. */
+  alternateClick?(point: Point, button: 'secondary' | 'middle'): Promise<Record<string, unknown> | void>;
+  /** Owner-native ref routes; currently the managed web runtime is their only local owner. */
+  tapRef?(ref: string): Promise<Record<string, unknown> | void>;
+  tapElementSelector?(selector: ElementSelectorTapOptions): Promise<Record<string, unknown> | void>;
+  doubleTap(x: number, y: number): Promise<Record<string, unknown> | void>;
+  longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
+  /**
+   * Move the pointer to a point without pressing. Only pointer-driven
+   * platforms (web today) implement it; touch platforms have no hover state
+   * and leave it undefined, which the `hover` command reports as unsupported.
+   */
+  hover?(x: number, y: number): Promise<Record<string, unknown> | void>;
+  hoverRef?(ref: string): Promise<Record<string, unknown> | void>;
+  focus(x: number, y: number): Promise<Record<string, unknown> | void>;
+  type(text: string, delayMs?: number): Promise<TypeTextBackendResult | void>;
+  /**
+   * Replace the target's text with `text`. The empty string is the clear request (#2063), not a
+   * no-op: an implementation must empty the field or fail — never report success over an
+   * untouched value. A backend with no clear mechanism refuses the empty text up front (see the
+   * webdriver interactor).
+   */
+  fill(x: number, y: number, text: string, delayMs?: number, options?: {
+    allowNonHittableCoordinateFallback?: boolean;
+  }): Promise<Record<string, unknown> | void>;
+  fillRef?(ref: string, text: string, delayMs?: number): Promise<Record<string, unknown> | void>;
+  scroll(direction: ScrollDirection, options?: ScrollExecutionOptions): Promise<Record<string, unknown> | void>;
+  screenshot(outPath: string, options?: ScreenshotOptions): Promise<void>;
+  setViewport?(width: number, height: number): Promise<Record<string, unknown> | void>;
+  snapshot(options?: SnapshotOptions): Promise<SnapshotRuntimeResult>;
+  /**
+   * Native reading of the live text at a point, when the backend has one. Answers the text the
+   * owner can see right now, which can exceed what an already-captured node carries (an editable
+   * field whose value is longer than its label). Optional: a backend without it leaves the
+   * captured tree as the complete answer.
+   */
+  readTextAtPoint?(point: Point, options?: {
+    appBundleId?: string;
+    surface?: SessionSurface;
+    signal?: AbortSignal;
+  }): Promise<string | undefined>;
+  /**
+   * Native text-presence reading, when the backend has one that does not require a tree capture.
+   * A `true` answer is authoritative; anything else means "not proven here" and the caller
+   * consults the canonical tree (see `FindTextResult`).
+   */
+  findText?(text: string, options?: {
+    appBundleId?: string;
+    signal?: AbortSignal;
+  }): Promise<{
+    found: boolean;
+  }>;
+  gestureViewport?(): Promise<Rect>;
+  back(mode?: BackMode): Promise<void>;
+  home(): Promise<void>;
+  setOrientation(orientation: DeviceRotation): Promise<{
+    orientation?: DeviceRotation;
+  } | void>;
+  performGesture?(plan: GesturePlan): Promise<Record<string, unknown> | void>;
+  appSwitcher(): Promise<void>;
+  tvRemote(button: TvRemoteButton, durationMs?: number): Promise<void>;
+  /** Optional: only Android implements a live status read (see {@link KeyboardStatusResult}). */
+  keyboardStatus?(): Promise<KeyboardStatusResult>;
+  /** Optional: platforms with no keyboard-dismiss concept leave it undefined. */
+  keyboardDismiss?(): Promise<KeyboardDismissResult>;
+  /** Optional: platforms with no keyboard-return concept leave it undefined. */
+  keyboardEnter?(): Promise<KeyboardEnterResult>;
+  readClipboard(): Promise<string>;
+  writeClipboard(text: string): Promise<void>;
+  setSetting(setting: string, state: string, appId?: string, options?: SettingOptions): Promise<Record<string, unknown> | void>;
+  /**
+   * The four alert legs. Each owner runs its own observation and, where it needs one, its own
+   * poll: an alert is a transient device surface, and how long to look for it — and how to press
+   * its buttons — is family mechanics, not something a caller can supply. `timeoutMs` is the
+   * whole window the caller allows; the owner spends it however its backend requires.
+   */
+  readAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  awaitAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  acceptAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  dismissAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+};
+/**
+ * The session-derived target one alert leg acts on. `appBundleId` is separate from the runner
+ * context's because the macOS helper reads a frontmost-app surface with no bundle at all, and
+ * the two must not collapse into one field that means both.
+ */
+type AlertInteractorOptions = {
+  timeoutMs?: number;
+  appBundleId?: string;
+  surface?: SessionSurface;
+};
+//#endregion
 //#region packages/selectors/src/internal/parse.d.ts
 type SelectorKey = 'id' | 'role' | 'text' | 'label' | 'value' | 'appname' | 'windowtitle' | 'visible' | 'hidden' | 'editable' | 'selected' | 'focused' | 'enabled' | 'hittable';
 type SelectorTerm = {
@@ -614,4 +998,4 @@ declare function formatSelectorFailure(chain: SelectorChain | string, diagnostic
   unique?: boolean;
 }): string;
 //#endregion
-export { ClickButton as C, SnapshotDiagnosticsSummary as D, ScreenshotResultData as E, SessionSurface as O, BackMode as S, FindLocator as T, SettleObservation as _, resolveSelectorChain as a, TvRemoteButton as b, isSelectorToken as c, ClickCommandResponseData as d, FillCommandResponseData as f, PressCommandResponseData as g, LongPressCommandResponseData as h, findSelectorChainMatch as i, parseSelectorChain as l, HoverCommandResponseData as m, isNodeEditable as n, SelectorDiagnostics as o, FindCommandResponseData as p, isNodeVisible as r, SelectorChain as s, formatSelectorFailure as t, tryParseSelectorChain as u, Interactor as v, AndroidSnapshotBackendMetadata as w, DeviceRotation as x, RunnerContext as y };
+export { ScrollInputDirection as A, BackMode as C, PointerTrajectorySample as D, PointerTrajectory as E, AndroidSnapshotBackendMetadata as F, FindLocator as I, ScreenshotResultData as L, SwipePreset as M, TransformGestureParams as N, SinglePointerGesturePlan as O, ClickButton as P, SnapshotDiagnosticsSummary as R, DeviceRotation as S, MultiTouchGesturePlan as T, HoverCommandResponseData as _, resolveSelectorChain as a, SettleObservation as b, isSelectorToken as c, Interactor as d, RunnerContext as f, FindCommandResponseData as g, FillCommandResponseData as h, findSelectorChainMatch as i, SwipePattern as j, ScrollDirection as k, parseSelectorChain as l, ClickCommandResponseData as m, isNodeEditable as n, SelectorDiagnostics as o, ScrollCommandResult as p, isNodeVisible as r, SelectorChain as s, formatSelectorFailure as t, tryParseSelectorChain as u, LongPressCommandResponseData as v, GesturePointerCount as w, TvRemoteButton as x, PressCommandResponseData as y, SessionSurface as z };