agent-device 0.21.22 → 0.21.24

package/dist/src/provider-device-runtime.d.ts

@@ -0,0 +1,556 @@
+import { A as RawSnapshotNode, I as SnapshotOptions$1, L as SnapshotProvenance, O as IosTargetActivation, P as SnapshotKeyboardBandFact, S as DeviceTarget, b as DeviceInfo, f as LeaseBackend, j as Rect, k as Point, w as PlatformSelector, x as DeviceKind } from "./sdk-contracts.js";
+import { t as AppStateRuntimeResult } from "./app-state-runtime.js";
+import { D as DeviceRotation, S as ScrollDirection, _ as SettingOptions, g as ReadableSetting, h as ReadSettingResult, j as BackMode, n as CloudArtifactProvider, o as BackendSnapshotResult, u as SessionSurface, x as ScrollExecutionOptions, y as TvRemoteButton } from "./cloud-artifacts.js";
+import { t as GesturePlan } from "./gesture-plan-types.js";
+//#region packages/contracts/src/device-inventory.d.ts
+type DeviceInventoryRequest = {
+  platform?: PlatformSelector;
+  target?: DeviceTarget;
+  deviceName?: string;
+  udid?: string;
+  serial?: string;
+  leaseId?: string;
+  leaseProvider?: string;
+  deviceKey?: string;
+  clientId?: string;
+  iosSimulatorSetPath?: string;
+  androidSerialAllowlist?: string[];
+  /** Internal local-inventory projection filters; not public command grammar. */
+  kind?: DeviceKind;
+  booted?: boolean;
+  /** Internal target-resolution policy; ordinary inventory leaves this absent and lists all AVDs. */
+  androidAvdSelection?: 'running-only' | 'include-stopped';
+};
+type ProviderDeviceInventoryRequest = Omit<DeviceInventoryRequest, 'booted' | 'kind'>;
+//#endregion
+//#region packages/contracts/src/ios-system-surface.d.ts
+/**
+ * iOS out-of-process system surfaces that agent-device observes and drives IN PLACE, never by
+ * activation: launching or activating the host cancels what it presents (issue #2438), so the
+ * runner addresses the host process while it is foreground and the `open` path refuses 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. Rationale per host lives in the canonical fixture
+ * `contracts/fixtures/ios-system-surface-hosts.json` (see also docs/adr/0004); this module and the
+ * Swift `SystemSurfaceHostRegistry` both mirror it, each guarded by a parity test.
+ */
+/** Why a system surface is served in place; carried at snapshot-response level as provenance. */
+type IosSystemSurfaceKind = 'web-auth' | 'payment';
+/**
+ * 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 IosSystemSurfaceProvenance = Readonly<{
+  bundleId: string;
+  kind: IosSystemSurfaceKind;
+}>;
+//#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 IosAcquisitionResidue = Readonly<{
+  kind: 'provider-pruned';
+  fields: readonly IosProviderPrunedField[];
+}> | Readonly<{
+  kind: 'missing-viewport';
+  reason: 'not-provided' | 'not-supported' | 'invalid';
+}> | Readonly<{
+  kind: 'truncated';
+}> | 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';
+};
+/**
+ * What the capture owner observed while writing the image. `displayRotation` is the rotation the display
+ * rendered the pixels in, so a landscape value pairs with a landscape image; it is absent when the
+ * owner has no rotation reading it can stand behind for this capture.
+ */
+type ScreenshotCaptureFacts = Readonly<{
+  displayRotation?: DeviceRotation;
+}>;
+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 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';
+  /**
+   * A one-off read, such as an open's launch observation. It may use a capture host the session
+   * already keeps warm, but it never installs one or leaves running one that it started. It starts
+   * no re-capture after `settleBy` (epoch ms); only `signal` cancels work already started.
+   */
+  transient?: Readonly<{
+    settleBy: number;
+  }>;
+};
+/**
+ * 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;
+  /**
+   * The keyboard band the producer measured while capturing, when it can measure one (#2660). A
+   * producer that publishes nothing measured nothing, so the tap-path guard keeps deriving the band
+   * from `nodes`; see {@link SnapshotKeyboardBandFact}.
+   */
+  keyboard?: SnapshotKeyboardBandFact;
+  /**
+   * Set when this capture's own command had to bring the session app back to the foreground, i.e.
+   * something else held it and an earlier observation described that instead (#2682).
+   */
+  targetActivation?: IosTargetActivation;
+} & 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>;
+  /**
+   * Fused double-click for owners that have one. The shared `--count` series cannot stand in for it —
+   * it spaces and jitters independent presses rather than firing one pair the target reads as a
+   * double — so an owner with no such mechanic leaves this undefined and `press --double` reports the
+   * gap instead of resolving a denial.
+   */
+  doubleTap?(x: number, y: number): Promise<Record<string, unknown> | void>;
+  longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
+  /**
+   * How the app the runner context names is running, as the platform reports it. The Apple runner
+   * reads `XCUIApplication.state`; owners that read the foreground elsewhere leave it undefined.
+   */
+  appState?(): Promise<AppStateRuntimeResult>;
+  /**
+   * 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<ScreenshotCaptureFacts | 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>;
+  /**
+   * Optional (parity with `actionButton`): opens the springboard, a control not every owner
+   * carries. An owner without it leaves it undefined; its fact refuses the press before binding,
+   * and the system-button binder fails closed rather than resolving an absent member as a
+   * successful no-op.
+   */
+  home?(): Promise<void>;
+  setOrientation(orientation: DeviceRotation): Promise<{
+    orientation?: DeviceRotation;
+  } | void>;
+  performGesture?(plan: GesturePlan): Promise<Record<string, unknown> | void>;
+  /**
+   * Optional (parity with `home`): opens the recents surface, a control not every owner carries.
+   * An owner without it leaves it undefined; its fact refuses the press before binding, and the
+   * system-button binder fails closed rather than resolving an absent member as a successful
+   * no-op.
+   */
+  appSwitcher?(): Promise<void>;
+  /**
+   * Optional (parity with `home`): presses one TV remote key, a control only TV-capable owners
+   * carry. An owner without it leaves it undefined; its fact refuses the press before binding,
+   * and the TV remote binder fails closed rather than resolving an absent member as a silent
+   * no-op.
+   */
+  tvRemote?(button: TvRemoteButton, durationMs?: number): Promise<void>;
+  /**
+   * Optional (parity with `keyboardDismiss`): presses the iPhone/iPad Action Button, hardware only
+   * the Apple owner carries. An owner without the button leaves it undefined; its fact refuses the
+   * press before binding, and the system-button binder fails closed rather than resolving an
+   * absent member as a successful no-op.
+   */
+  actionButton?(): 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>;
+  /**
+   * Optional (parity with `readSetting`): the owner's pasteboard read. An owner with no clipboard
+   * surface leaves both halves undefined; its fact refuses the half before binding, and the
+   * clipboard binder fails closed rather than resolving an absent member as an empty answer.
+   */
+  readClipboard?(): Promise<string>;
+  /**
+   * Optional (parity with `readClipboard`): the owner's pasteboard write, with the same
+   * fact-then-guard contract as the read.
+   */
+  writeClipboard?(text: string): Promise<void>;
+  setSetting(setting: string, state: string, appId?: string, options?: SettingOptions): Promise<Record<string, unknown> | void>;
+  /**
+   * Optional: reads back the value a device holds for one readable setting. The name is narrowed to
+   * `READABLE_SETTINGS`, which is not every setting the write switch serves, and an owner's dispatch
+   * is exhaustive over it — a setting joins the list only with an owner that answers it. An owner with
+   * no read path leaves the member undefined; its fact refuses the read before binding, so an absent
+   * method can never resolve into an empty answer.
+   */
+  readSetting?(setting: ReadableSetting): Promise<ReadSettingResult>;
+  /**
+   * 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.
+   *
+   * Optional: an owner with no alert surface leaves all four undefined. Its facts refuse every leg
+   * before binding, so the absent members are never resolved, and a fact that admitted a leg the
+   * interactor cannot serve fails closed instead of answering empty.
+   */
+  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/contracts/src/device-provider.d.ts
+type DeviceLease = {
+  leaseId: string;
+  tenantId: string;
+  runId: string;
+  backend: LeaseBackend;
+  leaseProvider?: string;
+  deviceKey?: string;
+  clientId?: string;
+  retainOnClose?: true;
+  createdAt: number;
+  heartbeatAt: number;
+  expiresAt: number;
+};
+type LeaseLifecycleContext = {
+  flags?: Readonly<Record<string, unknown>>;
+  initialApp?: string;
+  cwd?: string;
+  publicNetworkOnly?: boolean;
+  /** Request-bound cancellation (explicit cancel or client disconnect). */
+  signal?: AbortSignal;
+  /**
+   * Epoch-ms deadline by which `allocate` must have settled; derived from the
+   * same budget as the client's `lease_allocate` envelope, so a provider that
+   * fits its remote phases within it is never abandoned by a client first.
+   */
+  deadline?: number;
+};
+type LeaseLifecycleProvider = {
+  allocate?: (lease: DeviceLease, context?: LeaseLifecycleContext) => Promise<Record<string, unknown> | undefined>;
+  heartbeat?: (lease: DeviceLease, context?: LeaseLifecycleContext) => Promise<Record<string, unknown> | undefined>;
+  release?: (lease: DeviceLease, context?: LeaseLifecycleContext) => Promise<Record<string, unknown> | undefined>;
+};
+type DeviceInventoryProvider = (request: ProviderDeviceInventoryRequest, signal?: AbortSignal) => Promise<DeviceInfo[] | null | undefined>;
+type ProviderAppCatalogQuery = Readonly<{
+  provider: string;
+  platform: 'android' | 'ios';
+  publicNetworkOnly?: boolean;
+}>;
+type ProviderAppCatalogHandler = (query: ProviderAppCatalogQuery, signal?: AbortSignal) => Promise<readonly string[]>;
+//#endregion
+//#region packages/contracts/src/provider-device-runtime.d.ts
+type ProviderDeviceInstallResult = {
+  bundleId?: string;
+  packageName?: string;
+  appName?: string;
+  launchTarget?: string;
+};
+type ProviderDeviceInstallOptions = {
+  relaunch?: boolean;
+  appIdentifierHint?: string;
+  packageNameHint?: string;
+};
+type ProviderPortReverseOptions = {
+  leaseId: string;
+  provider?: string;
+  devicePort: number;
+  hostPort: number;
+  name: string;
+};
+type ProviderExpiredLeaseRecovery = (lease: DeviceLease) => Promise<void>;
+/** Provider adapter contract; root owns active-runtime and request composition. */
+type ProviderDeviceRuntime = {
+  provider: string;
+  leaseLifecycle: LeaseLifecycleProvider;
+  recoverExpiredLease?: ProviderExpiredLeaseRecovery;
+  cloudArtifacts?: CloudArtifactProvider;
+  appCatalog?: ProviderAppCatalogHandler;
+  deviceInventoryProvider: DeviceInventoryProvider;
+  ownsDevice(device: DeviceInfo): boolean;
+  getInteractor(device: DeviceInfo, runnerContext?: RunnerContext): Interactor | undefined;
+  installApp?(device: DeviceInfo, app: string, appPath: string, options?: ProviderDeviceInstallOptions): Promise<ProviderDeviceInstallResult | undefined>;
+  installInstallablePath?(device: DeviceInfo, installablePath: string, options?: ProviderDeviceInstallOptions): Promise<ProviderDeviceInstallResult | undefined>;
+  configurePortReverse?(options: ProviderPortReverseOptions): Promise<Record<string, unknown> | undefined>;
+  shutdown(): Promise<void>;
+};
+//#endregion
+export { ProviderPortReverseOptions as a, LeaseLifecycleContext as c, ProviderExpiredLeaseRecovery as i, LeaseLifecycleProvider as l, ProviderDeviceInstallResult as n, DeviceInventoryProvider as o, ProviderDeviceRuntime as r, DeviceLease as s, ProviderDeviceInstallOptions as t, Interactor as u };

package/dist/src/provider-policy.js

@@ -0,0 +1 @@
+import{_ as e}from"./base-url.js";import{n as t,t as n}from"./client-companion-tunnel.js";import{i as r}from"./providers.js";import{t as i}from"./manifest.js";import{n as a}from"./store.js";const o={slug:`react-devtools-companion`,runArg:e,displayName:`React DevTools companion`};async function s(e){return await n({...e,definition:o,localBaseUrl:e.localBaseUrl??`http://127.0.0.1:8097`,registerPath:`/api/react-devtools/companion/register`,unregisterPath:`/api/react-devtools/companion/unregister`,devicePort:e.devicePort??8097})}async function c(e){return await t({...e,definition:o})}function l(e,t=process.env){return e===void 0?void 0:a(t).find(t=>t.agentDevicePlugin.provider===e)?.agentDevicePlugin.connection}function u(e=process.env){return a(e).filter(e=>e.agentDevicePlugin.connection).map(e=>e.agentDevicePlugin.provider)}const d={leaseKind:`direct-device-provider`,requiresAppAttachment:!1,requiresRemoteDaemon:!1,supportsArtifacts:!1,supportsDeferredAppSelection:!0,supportsDirectPortReverse:!0,usesCloudWebDriverLease:!1};function f(e){return{leaseKind:e,requiresAppAttachment:!1,requiresRemoteDaemon:!0,supportsArtifacts:!1,supportsDeferredAppSelection:!1,supportsDirectPortReverse:!1,usesCloudWebDriverLease:!1}}function p(e,t=process.env){return e===`cloud`||e===`proxy`||e===`limrun`||r(e)!==void 0||l(e,t)!==void 0}function m(){return[...i,...u()].join(`, `)}function h(e,t=process.env){return e===`limrun`?d:e===`proxy`?f(`proxy`):r(e)?.connection??(e===`cloud`?void 0:l(e,t))??f(`remote-provider`)}export{c as a,s as i,h as n,p as r,m as t};

package/dist/src/provider-profile-fields.js

@@ -1 +1 @@
-import{r as e}from"./rolldown-runtime.js";import{P as t}from"./sdk-contracts.js";import{l as n,u as r}from"./sdk-remote-config.js";var i=e({rejectRefusedProviderProfileFields:()=>a});function a(e,r){let i=Object.keys(r.fields).filter(t=>r.fields[t]===`refused`&&s(e?.[t]));if(i.length===0)return;let a=i.length!==1;throw new t(`INVALID_ARGS`,`${i.map(o).join(`, `)} ${a?`are`:`is`} not supported by ${r.label}.`,{hint:`Drop ${a?`those flags`:`the flag`} or use a provider that supports ${a?`them`:`it`}.`,provider:r.provider,flags:i.map(e=>n[e])})}function o(e){let t=r[e],i=n[e];return t?.length?`${i} (${t.join(`, `)})`:i}function s(e){return e!=null&&e!==!1&&e!==``}export{a as n,i as t};
+import{r as e}from"./rolldown-runtime.js";import{P as t}from"./sdk-contracts.js";import{d as n,u as r}from"./sdk-remote-config.js";var i=e({rejectRefusedProviderProfileFields:()=>a,requireResolvedProfilePlatform:()=>s,requireResolvedProfileValue:()=>o});function a(e,n){let i=Object.keys(n.fields).filter(t=>n.fields[t]===`refused`&&l(e?.[t]));if(i.length===0)return;let a=i.length!==1;throw new t(`INVALID_ARGS`,`${i.map(c).join(`, `)} ${a?`are`:`is`} not supported by ${n.label}.`,{hint:`Drop ${a?`those flags`:`the flag`} or use a provider that supports ${a?`them`:`it`}.`,provider:n.provider,flags:i.map(e=>r[e])})}function o(e,n){if(e!==void 0)return e;throw new t(`COMMAND_FAILED`,n,{hint:`Reconnect to regenerate and validate the provider profile.`})}function s(e,n){if(e===`android`||e===`ios`)return e;throw new t(`COMMAND_FAILED`,`${n} profile missed a mobile platform.`,{hint:`Reconnect with --platform ios|android.`})}function c(e){let t=n[e],i=r[e];return t?.length?`${i} (${t.join(`, `)})`:i}function l(e){return e!=null&&e!==!1&&e!==``}export{o as i,a as n,s as r,i as t};