prowl-tools 0.1.4 → 0.1.5

package/dist/lib.d.ts

@@ -22,7 +22,40 @@ type MacosTarget = {
     type: "macos";
     app: string;
 };
-type Target = WebTarget | MacosTarget;
+/**
+ * Android native execution target (experimental, PROWL-058). `app` is an Android
+ * package name (e.g. `com.example.app`) or an absolute/relative path to an `.apk`
+ * file, which Prowl installs before launch. Optional `deviceSerial` selects one of
+ * several attached devices/emulators; `coldStart` opts into a deterministic
+ * `pm clear` before launch (default off). Android guardrails match package IDs
+ * or canonical full APK paths; APK package IDs are resolved before install.
+ */
+type AndroidTarget = {
+    type: "android";
+    app: string;
+    /** adb device serial to target when more than one device is attached. */
+    deviceSerial?: string;
+    /** Run `pm clear <package>` before launch for a deterministic cold start (default off). */
+    coldStart?: boolean;
+};
+/**
+ * iOS simulator native execution target (experimental, PROWL-059). `app` is an
+ * iOS bundle identifier (e.g. `com.example.App`) or an absolute/relative path to
+ * a built `.app` bundle, which Prowl installs onto the simulator before launch.
+ * Optional `udid` selects a specific booted simulator; `coldStart` opts into an
+ * uninstall+reinstall before launch (default off, and only possible with a `.app`
+ * path). Real devices are out of scope (PROWL-062) — simulators only. iOS
+ * guardrails match bundle ids, the bundle name, or the canonical `.app` path.
+ */
+type IosTarget = {
+    type: "ios";
+    app: string;
+    /** UDID of the booted simulator to target when more than one is booted. */
+    udid?: string;
+    /** Uninstall+reinstall the app before launch for a deterministic cold start (default off). */
+    coldStart?: boolean;
+};
+type Target = WebTarget | MacosTarget | AndroidTarget | IosTarget;
 type Config = {
     target: Target;
     browser: {
@@ -48,7 +81,7 @@ type Config = {
     guardrails: {
         maxSteps: number;
         allowedDomains: string[];
-        /** Native scope analog of `allowedDomains`: allowed bundle IDs, app bundle names, or `.app` paths. */
+        /** Native scope analog of `allowedDomains`: allowed bundle/package IDs or canonical app artifact paths. */
         allowedApps: string[];
         forbiddenSelectors: string[];
         selfHealing: boolean;
@@ -558,6 +591,538 @@ declare function launchMacSession(options: LaunchMacOptions): Promise<MacSession
 /** Quit the target app (best effort) and shut the helper down. */
 declare function closeMacSession(session: MacSession): Promise<void>;
 
+/** A structured query the {@link AndroidAgentClient} resolves against the device. */
+type AndroidQuery = {
+    by: "id";
+    value: string;
+} | {
+    by: "accessibilityId";
+    value: string;
+} | {
+    by: "role";
+    role: string;
+    name?: string;
+} | {
+    by: "text";
+    value: string;
+} | {
+    by: "focused";
+};
+/**
+ * A locator in the uiautomator2 server's native wire shape. The raw on-device
+ * server does NOT accept W3C `{using, value}` — that translation normally lives
+ * in Appium's driver layer, which we bypass — it requires `{strategy, selector}`
+ * (plus a `context` field, empty for a root-scoped search). Device-verified
+ * against appium-uiautomator2-server 10.6.2 (2026-08-19).
+ */
+type AndroidLocator = {
+    strategy: string;
+    selector: string;
+    context: string;
+};
+/**
+ * The semantic transport `AndroidDriver` talks to: element lookups return opaque
+ * element ids, and interactions take those ids. The HTTP/UiAutomator2
+ * implementation lives in {@link ./android-agent.js}; tests fake this interface.
+ */
+interface AndroidAgentClient {
+    /** Resolve the first element matching `query`, or null when none match. */
+    findElement(query: AndroidQuery): Promise<string | null>;
+    /** Resolve every element id matching `query` (empty when none match). */
+    findElements(query: AndroidQuery): Promise<string[]>;
+    click(elementId: string): Promise<void>;
+    /** Replace an element's text (unicode-safe; W3C `element/value`). */
+    setValue(elementId: string, text: string): Promise<void>;
+    getText(elementId: string): Promise<string | null>;
+    /** Dispatch a global key event by Android key code (goes to the focused view). */
+    pressKeyCode(keyCode: number): Promise<void>;
+    /** Capture the current screen as PNG bytes. */
+    screenshotPng(): Promise<Buffer>;
+    close(): Promise<void>;
+}
+type AndroidDriverOptions = {
+    /** Package name, used only for the informational `currentUrl()` value. */
+    appLabel?: string;
+};
+/**
+ * Android key names accepted by the `press` step, mapped to KeyEvent key codes.
+ * Names are matched case-insensitively.
+ */
+declare const ANDROID_KEYCODES: Readonly<Record<string, number>>;
+/** Escape a string for embedding inside a `new UiSelector()...("...")` argument. */
+declare function escapeUiSelectorArg(value: string): string;
+/** Parse a Prowl selector string into an {@link AndroidQuery}. Bare text matches by text. */
+declare function parseAndroidSelector(selector: string): AndroidQuery;
+/**
+ * Translate an {@link AndroidQuery} into the uiautomator2 server's native
+ * locator shape. `id`/`accessibility id` are native strategies;
+ * text/role(+name)/focused compose a `-android uiautomator` `UiSelector`.
+ * `appPackage` qualifies bare `id=` names ({@link qualifyResourceId}).
+ */
+declare function androidQueryToLocator(query: AndroidQuery, options?: {
+    appPackage?: string;
+}): AndroidLocator;
+/** The literal text a `text=` selector matches, else null (mirrors the web driver). */
+declare function unwrapAndroidTextSelector(selector: string): string | null;
+/** Wrap a live {@link AndroidAgentClient} as a {@link SessionDriver}. */
+declare function createAndroidDriver(client: AndroidAgentClient, options?: AndroidDriverOptions): SessionDriver;
+
+/** Result of one adb invocation. */
+type AdbResult = {
+    stdout: string;
+    stderr: string;
+    code: number;
+};
+/** Runs one adb command to completion and resolves with its captured output. */
+type AdbRunner = (args: string[], options?: {
+    timeoutMs?: number;
+}) => Promise<AdbResult>;
+/** A handle to a spawned long-running adb process (the instrumentation server). */
+type AdbProcessHandle = {
+    kill(): void;
+};
+/** Spawns a long-running adb command (e.g. `am instrument -w`) in the background. */
+type AdbSpawner = (args: string[]) => AdbProcessHandle;
+/** One row of `adb devices -l`. */
+type AdbDevice = {
+    serial: string;
+    state: string;
+    description: Record<string, string>;
+};
+/**
+ * Parse `adb devices -l` output into structured rows. The header line
+ * (`List of devices attached`) and blank lines are skipped.
+ */
+declare function parseAdbDevices(stdout: string): AdbDevice[];
+/** Devices that are fully booted and usable (`device` state). */
+declare function bootedDevices(devices: AdbDevice[]): AdbDevice[];
+/**
+ * Choose which device to drive. With `requested` set it must be attached and
+ * booted. Otherwise exactly one booted device is required; zero or many raise an
+ * actionable error listing what was found.
+ */
+declare function selectDeviceSerial(devices: AdbDevice[], requested?: string): string;
+/** List attached devices via `adb devices -l`. */
+declare function listDevices(runner: AdbRunner): Promise<AdbDevice[]>;
+/**
+ * Parse the local port `adb forward tcp:0 tcp:<remote>` prints (dynamic port
+ * allocation). adb echoes the chosen local port on stdout.
+ */
+declare function parseForwardPort(stdout: string): number;
+/** Parse the package name out of `aapt dump badging <apk>` output. */
+declare function parseAaptPackage(stdout: string): string | null;
+
+/** The remote port the uiautomator2 server listens on inside the device. */
+declare const UIA2_REMOTE_PORT = 6790;
+/** Locations of the two prebuilt agent APKs. */
+type AgentApks = {
+    serverApk: string;
+    testApk: string;
+};
+/** Establishes a live {@link AndroidAgentClient} against a forwarded local port. */
+type AgentConnector = (options: {
+    host: string;
+    port: number;
+    requestTimeoutMs: number;
+    readyDeadlineMs: number;
+    /** Target app's package name; qualifies bare `id=` selectors on the device. */
+    appPackage?: string;
+}) => Promise<AndroidAgentClient>;
+/** Resolve a package name from an `.apk` file, or null when it can't be determined. */
+type AaptResolver = (apkPath: string) => Promise<string | null>;
+/**
+ * Resolve the two agent APKs shipped inside `appium-uiautomator2-server`. They
+ * live under the package's `apks/` folder; the server APK is version-stamped.
+ */
+declare function resolveAgentApks(requireFn?: NodeRequire): AgentApks;
+/** Default connector: builds the HTTP transport, waits for readiness, opens a session. */
+declare const defaultAgentConnector: AgentConnector;
+type AndroidSession = {
+    client: AndroidAgentClient;
+    driver: SessionDriver;
+    /** The resolved package name being driven. */
+    package: string;
+    /** The adb serial of the device being driven. */
+    serial: string;
+    /** Tear down the session, agent, port forward, and app (best effort). */
+    teardown(): Promise<void>;
+};
+type LaunchAndroidOptions = {
+    /** Package name or `.apk` path. */
+    app: string;
+    /** adb serial when more than one device is attached. */
+    deviceSerial?: string;
+    /** `pm clear` the package before launch for a deterministic cold start. */
+    coldStart?: boolean;
+    timeoutMs?: number;
+    runner?: AdbRunner;
+    spawner?: AdbSpawner;
+    agentConnector?: AgentConnector;
+    apks?: AgentApks;
+    aaptResolver?: AaptResolver;
+    /** Optional app scope guardrail from config.guardrails.allowedApps. */
+    allowedApps?: string[];
+};
+/**
+ * Preflight, install, launch, and attach the uiautomator2 agent, returning a
+ * live {@link AndroidSession}. Actionable errors cover each failure mode: adb
+ * missing / no booted device (device selection), agent unreachable (readiness).
+ */
+declare function launchAndroidSession(options: LaunchAndroidOptions): Promise<AndroidSession>;
+/** Tear down an Android session (agent session, instrumentation, forward, app). */
+declare function closeAndroidSession(session: AndroidSession): Promise<void>;
+
+/**
+ * PROWL-058 / ARCH-009 — HTTP/JSON transport for the on-device uiautomator2 agent.
+ *
+ * `appium-uiautomator2-server` exposes W3C-WebDriver-shaped endpoints over plain
+ * HTTP. This module speaks them with the global `fetch` (no heavy WebDriver SDK,
+ * per the `ai.ts` ethos), mirroring the mac-helper client's ergonomics: a
+ * per-request deadline via `AbortController`, and cleanup on
+ * every path. It exposes the semantic {@link AndroidAgentClient} the driver
+ * consumes; tests fake either the `fetch` implementation or the client itself.
+ */
+
+/** The subset of `fetch` this module uses; overridable in tests. */
+type FetchLike$1 = (url: string, init: RequestInit) => Promise<Response>;
+/** Default per-request deadline for the agent transport. */
+declare const DEFAULT_AGENT_REQUEST_TIMEOUT_MS = 30000;
+type Uia2TransportOptions = {
+    /** Base URL including the `/wd/hub` prefix, e.g. `http://127.0.0.1:6790/wd/hub`. */
+    baseUrl: string;
+    requestTimeoutMs?: number;
+    fetchImpl?: FetchLike$1;
+};
+/** An HTTP-level failure from the agent, carrying the status and parsed body. */
+declare class Uia2HttpError extends Error {
+    readonly status: number;
+    readonly webdriverError?: string | undefined;
+    constructor(message: string, status: number, webdriverError?: string | undefined);
+}
+/** Low-level request/response transport with a per-request deadline. */
+declare class Uia2Transport {
+    private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    private readonly fetchImpl;
+    constructor(options: Uia2TransportOptions);
+    /**
+     * Send one request and return the parsed `value` field. Rejects with a
+     * {@link Uia2HttpError} on a non-2xx response, or a timeout error when the
+     * per-request deadline elapses.
+     */
+    request(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<unknown>;
+}
+/** Extract an element id from a W3C element-reference object, or null. */
+declare function extractElementId(value: unknown): string | null;
+/**
+ * Create a uiautomator2 session and return its id. Uses the W3C `capabilities`
+ * envelope; the server ignores the empty match set and starts a default session.
+ */
+declare function createUia2Session(transport: Uia2Transport): Promise<string>;
+/** Poll `GET /status` until the agent reports ready or the deadline elapses. */
+declare function waitForAgentReady(transport: Uia2Transport, options?: {
+    deadlineMs: number;
+    intervalMs?: number;
+}): Promise<void>;
+/**
+ * Build the semantic {@link AndroidAgentClient} over a live session. `close`
+ * deletes the session (best effort); the transport itself is stateless.
+ */
+declare function createUia2AgentClient(transport: Uia2Transport, sessionId: string, options?: {
+    appPackage?: string;
+}): AndroidAgentClient;
+
+/**
+ * PROWL-059 / ARCH-010 — iOS simulator implementation of {@link SessionDriver}.
+ *
+ * `IosDriver` drives a native iOS app through a prebuilt WebDriverAgent (WDA)
+ * runner over its W3C-shaped HTTP/JSON API ({@link IosAgentClient}). Like the
+ * macOS and Android drivers it implements only the portable subset of the driver
+ * surface — its `capabilities` set is honest: `query`, `interact`, `wait`,
+ * `screenshot`. Web-only verbs (navigation, network, dialogs, files, downloads,
+ * script evaluation) are unsupported stubs; the runner never reaches them because
+ * both the target step-compatibility check and the runtime capability gate reject
+ * web-only steps for native targets.
+ *
+ * Screenshots are captured via `simctl` (injected as `captureScreenshot`), not
+ * WDA, so artifacts still work even if the agent wedges.
+ *
+ * Selector dialect (parsed here into an {@link IosQuery}; the agent then matches
+ * on the simulator). Semantics mirror the macOS/Android drivers so `id=`/`label=`/
+ * `text=`/`role=` mean the same thing across native targets (PROWL-060 will unify
+ * the engines later):
+ *   id=save                    → accessibility id (accessibilityIdentifier / name)
+ *   label="Submit"             → predicate `label == "Submit"` (exact)
+ *   role=XCUIElementTypeButton → element class (shorthand `Button` is accepted too)
+ *   role=Button[name="Save"]   → class + visible text (label/value substring)
+ *   text="Save" | Save         → label/value substring
+ *   :focus                     → predicate `hasKeyboardFocus == 1`
+ */
+
+/** A structured query the {@link IosAgentClient} resolves against the simulator. */
+type IosQuery = {
+    by: "accessibilityId";
+    value: string;
+} | {
+    by: "label";
+    value: string;
+} | {
+    by: "role";
+    role: string;
+    name?: string;
+} | {
+    by: "text";
+    value: string;
+} | {
+    by: "focused";
+};
+/** A WDA locator strategy ({@code using}) + its value, as the agent expects. */
+type IosLocator = {
+    using: string;
+    value: string;
+};
+/**
+ * The semantic transport `IosDriver` talks to: element lookups return opaque
+ * element ids, and interactions take those ids. The HTTP/WDA implementation lives
+ * in {@link ./ios-agent.js}; tests fake this interface.
+ */
+interface IosAgentClient {
+    /** Resolve the first element matching `query`, or null when none match. */
+    findElement(query: IosQuery): Promise<string | null>;
+    /** Resolve every element id matching `query` (empty when none match). */
+    findElements(query: IosQuery): Promise<string[]>;
+    click(elementId: string): Promise<void>;
+    /** Replace an element's text (W3C `element/value`). */
+    setValue(elementId: string, text: string): Promise<void>;
+    getText(elementId: string): Promise<string | null>;
+    /** Send raw key sequences to the focused element (WDA `/wda/keys`). */
+    sendKeys(keys: string[]): Promise<void>;
+    /** Return to the springboard home screen (WDA `/wda/homescreen`). */
+    homescreen(): Promise<void>;
+    close(): Promise<void>;
+}
+type IosDriverOptions = {
+    /** Bundle id, used only for the informational `currentUrl()` value. */
+    appLabel?: string;
+    /** Capture a PNG screenshot to `path` (injected simctl capture). */
+    captureScreenshot: (path: string) => Promise<void>;
+};
+/**
+ * Key names the `press` step supports on iOS, sorted for error messages. `enter`/
+ * `return` send a newline, `delete`/`backspace` send a backspace (both via WDA's
+ * key endpoint), and `home` returns to the springboard.
+ */
+declare const IOS_PRESS_KEYS: readonly string[];
+/** Escape a string for embedding inside a double-quoted NSPredicate string literal. */
+declare function escapePredicateArg(value: string): string;
+/** Prefix `XCUIElementType` onto a role shorthand (e.g. `Button`) when missing. */
+declare function normalizeXcuiClassName(role: string): string;
+/** Parse a Prowl selector string into an {@link IosQuery}. Bare text matches by text. */
+declare function parseIosSelector(selector: string): IosQuery;
+/**
+ * Translate an {@link IosQuery} into a WDA locator strategy. `id` uses the native
+ * `accessibility id` strategy and bare roles use `class name`; everything else
+ * composes an NSPredicate string (WDA's `predicate string` strategy).
+ */
+declare function iosQueryToLocator(query: IosQuery): IosLocator;
+/** The literal text a `text=` selector matches, else null (mirrors the web driver). */
+declare function unwrapIosTextSelector(selector: string): string | null;
+/** Wrap a live {@link IosAgentClient} as a {@link SessionDriver}. */
+declare function createIosDriver(client: IosAgentClient, options: IosDriverOptions): SessionDriver;
+
+/** Result of one `xcrun` invocation. */
+type SimctlResult = {
+    stdout: string;
+    stderr: string;
+    code: number;
+};
+/** Runs one `xcrun <args>` command to completion and resolves with its output. */
+type SimctlRunner = (args: string[], options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<SimctlResult>;
+/** One simulator device from `simctl list devices --json`. */
+type SimDevice = {
+    udid: string;
+    name: string;
+    state: string;
+    runtime: string;
+    isAvailable: boolean;
+};
+type SimulatorReservation = {
+    udid: string;
+    release(): Promise<void>;
+};
+type ReserveSimulatorOptions = {
+    /** Override the lock directory root; intended for tests. */
+    lockRoot?: string;
+};
+declare const DEFAULT_SIMULATOR_LOCK_ROOT: string;
+/**
+ * Reserve a simulator UDID across processes. The lock is held until `release` is
+ * called, preventing one session's teardown from terminating another session's
+ * WDA runner or target app on the same simulator.
+ */
+declare function reserveSimulatorUdid(udid: string, options?: ReserveSimulatorOptions): Promise<SimulatorReservation>;
+/**
+ * Allocate a free local TCP port by binding to :0 and releasing it. The returned
+ * port is advisory after release; callers that hand it to another process must
+ * handle a later bind/readiness failure.
+ */
+declare function findFreePort(): Promise<number>;
+/**
+ * Parse `simctl list devices --json` into a flat device list. The JSON maps
+ * runtime identifiers to arrays of devices; the runtime is folded into each row.
+ */
+declare function parseSimctlDevices(json: string): SimDevice[];
+/** Simulators that are currently booted. */
+declare function bootedSimulators(devices: SimDevice[]): SimDevice[];
+/**
+ * Choose which simulator to drive. With `requested` set it must exist and be
+ * booted. Otherwise exactly one booted simulator is required; zero or many raise
+ * an actionable error listing what was found.
+ */
+declare function selectSimulatorUdid(devices: SimDevice[], requested?: string): string;
+/** List all simulators via `simctl list devices --json`. */
+declare function listSimulators(runner: SimctlRunner): Promise<SimDevice[]>;
+/** Parse the `x.y[.z]` version out of `xcodebuild -version` output. */
+declare function parseXcodeVersion(stdout: string): string | null;
+
+/** Bundle id of the prebuilt WebDriverAgent runner (its xctest host app). */
+declare const WDA_RUNNER_BUNDLE_ID = "com.facebook.WebDriverAgentRunner.xctrunner";
+/** The runner `.app` produced by `xcodebuild build-for-testing`. */
+declare const WDA_RUNNER_APP_NAME = "WebDriverAgentRunner-Runner.app";
+/** Establishes a live {@link IosAgentClient} against a running WDA HTTP server. */
+type IosAgentConnector = (options: {
+    host: string;
+    port: number;
+    bundleId: string;
+    requestTimeoutMs: number;
+    readyDeadlineMs: number;
+}) => Promise<IosAgentClient>;
+/** Default connector: builds the HTTP transport, waits for readiness, opens a session. */
+declare const defaultIosAgentConnector: IosAgentConnector;
+/** Resolve the WDA Xcode project bundled inside `appium-webdriveragent`. */
+declare function resolveWdaProject(requireFn?: NodeRequire): {
+    projectPath: string;
+    version: string;
+};
+/** Cache directory for a built WDA runner, keyed on the WDA + Xcode versions. */
+declare function wdaCacheDir(wdaVersion: string, xcode: string, homeDir?: string): string;
+type ResolveWdaRunnerOptions = {
+    runner?: SimctlRunner;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    requireFn?: NodeRequire;
+    /** One-line progress notice sink (defaults to stderr). */
+    logger?: (message: string) => void;
+};
+/**
+ * Resolve a WebDriverAgent runner `.app`. Order: (a) the `PROWL_WDA_RUNNER` env
+ * override; (b) a previously built runner in the version-keyed cache; (c) a
+ * one-time `xcodebuild build-for-testing` that populates the cache. Simulators
+ * need no code signing. Throws actionable errors when Xcode is missing or the
+ * build fails.
+ */
+declare function resolveWdaRunner(options?: ResolveWdaRunnerOptions): Promise<string>;
+type IosSession = {
+    client: IosAgentClient;
+    driver: SessionDriver;
+    /** The resolved bundle id being driven. */
+    bundleId: string;
+    /** The UDID of the simulator being driven. */
+    udid: string;
+    /** Tear down the session, WDA runner, and target app (best effort). */
+    teardown(): Promise<void>;
+};
+type LaunchIosOptions = {
+    /** Bundle id or `.app` path. */
+    app: string;
+    /** Simulator UDID when more than one is booted. */
+    udid?: string;
+    /** Uninstall+reinstall the app before launch (requires a `.app` path). */
+    coldStart?: boolean;
+    timeoutMs?: number;
+    runner?: SimctlRunner;
+    portAllocator?: () => Promise<number>;
+    agentConnector?: IosAgentConnector;
+    /** Skip WDA build/resolution by supplying the runner app path directly. */
+    wdaRunnerApp?: string;
+    /** Optional app scope guardrail from config.guardrails.allowedApps. */
+    allowedApps?: string[];
+    /** Override the simulator lock root; intended for tests. */
+    simulatorLockRoot?: string;
+    logger?: (message: string) => void;
+};
+/**
+ * Preflight, install, launch, and attach WDA, returning a live {@link IosSession}.
+ * Actionable errors cover each failure mode: Xcode/simctl missing, no booted
+ * simulator (device selection), WDA build failures, agent unreachable (readiness).
+ */
+declare function launchIosSession(options: LaunchIosOptions): Promise<IosSession>;
+/** Tear down an iOS session (agent session, WDA runner, target app). */
+declare function closeIosSession(session: IosSession): Promise<void>;
+
+/**
+ * PROWL-059 / ARCH-010 — HTTP/JSON transport for the on-simulator WebDriverAgent.
+ *
+ * WebDriverAgent (WDA) exposes W3C-WebDriver-shaped endpoints over plain HTTP. On
+ * a simulator it is reachable directly at `http://127.0.0.1:<port>` (no tunnel),
+ * so this module speaks it with the global `fetch` (no heavy WebDriver SDK, per
+ * the `ai.ts` ethos), mirroring the Android agent's ergonomics: a per-request
+ * deadline via `AbortController`, unref'd timers, and W3C element-key extraction.
+ * It exposes the semantic {@link IosAgentClient} the driver consumes; tests fake
+ * either the `fetch` implementation or the client itself.
+ */
+
+/** The subset of `fetch` this module uses; overridable in tests. */
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+/** Default per-request deadline for the agent transport. */
+declare const DEFAULT_WDA_REQUEST_TIMEOUT_MS = 30000;
+type WdaTransportOptions = {
+    /** Base URL, e.g. `http://127.0.0.1:8100`. */
+    baseUrl: string;
+    requestTimeoutMs?: number;
+    fetchImpl?: FetchLike;
+};
+/** An HTTP-level failure from WDA, carrying the status and parsed body. */
+declare class WdaHttpError extends Error {
+    readonly status: number;
+    readonly webdriverError?: string | undefined;
+    constructor(message: string, status: number, webdriverError?: string | undefined);
+}
+/** Low-level request/response transport with a per-request deadline. */
+declare class WdaTransport {
+    private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    private readonly fetchImpl;
+    constructor(options: WdaTransportOptions);
+    /**
+     * Send one request and return the full parsed JSON body. Rejects with a
+     * {@link WdaHttpError} on a non-2xx response, or a timeout error when the
+     * per-request deadline elapses.
+     */
+    requestFull(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<unknown>;
+    /** Like {@link requestFull} but returns just the `value` field. */
+    request(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<unknown>;
+}
+/**
+ * Create a WDA session bound to `bundleId` and return its id. WDA activates the
+ * app under test named in `alwaysMatch.bundleId`. The session id may arrive at
+ * the envelope root or inside `value`, so both are checked.
+ */
+declare function createWdaSession(transport: WdaTransport, bundleId: string): Promise<string>;
+/** Poll `GET /status` until WDA reports ready or the deadline elapses. */
+declare function waitForWdaReady(transport: WdaTransport, options?: {
+    deadlineMs: number;
+    intervalMs?: number;
+}): Promise<void>;
+/**
+ * Build the semantic {@link IosAgentClient} over a live session. `close` deletes
+ * the session (best effort); the transport itself is stateless.
+ */
+declare function createWdaAgentClient(transport: WdaTransport, sessionId: string): IosAgentClient;
+
 /**
  * PROWL-048 / ARCH-002 — target ⇄ step compatibility.
  *
@@ -579,9 +1144,18 @@ declare function webOnlyReason(step: Step): string | null;
 /**
  * Throw if any step in `steps` (recursing into `if`/`repeat` bodies) is not
  * supported by `target`. `runHunt` references are validated when the referenced
- * hunt itself runs. No-op for the web target.
+ * hunt itself runs. No-op for the web target; every native target (macOS,
+ * Android, iOS) rejects the same web-only step vocabulary.
  */
 declare function assertStepsSupportedByTarget(steps: Step[], target: Target["type"]): void;
+/** Read the bundle id from an iOS `.app` (root `Info.plist`), or null. */
+declare function readIosBundleIdentifier(appPath: string): string | null;
+/**
+ * Accepted identities for an iOS target app. A bare bundle id matches itself; a
+ * `.app` path is authorized by its path, bundle name, or the `CFBundleIdentifier`
+ * read from the bundle's root `Info.plist`.
+ */
+declare function iosAppAllowedIdentities(app: string): string[];
 /**
  * Native scope guardrail: if `allowedApps` is non-empty it must include an
  * accepted identity for the target app: bundle id, app bundle name, or `.app`
@@ -589,6 +1163,25 @@ declare function assertStepsSupportedByTarget(steps: Step[], target: Target["typ
  * allowed — mirroring how allowedDomains auto-includes the web target's host.
  */
 declare function assertTargetAppAllowed(allowedApps: string[], app: string): void;
+/**
+ * iOS scope guardrail (PROWL-059): mirrors {@link assertTargetAppAllowed} but
+ * resolves identities via {@link iosAppAllowedIdentities} (bundle id or `.app`
+ * path with the id read from the bundle's root `Info.plist`).
+ */
+declare function assertIosAppAllowed(allowedApps: string[], app: string): void;
+/**
+ * Accepted identities for an Android target app. A bare package name matches
+ * itself. An `.apk` path is authorized only by its canonical full path; pass the
+ * resolved package name when validating an APK after `aapt` resolution so
+ * package-ID allowlists can authorize it before install.
+ */
+declare function androidAppAllowedIdentities(app: string, resolvedPackage?: string): string[];
+/**
+ * Android scope guardrail (PROWL-058): mirrors {@link assertTargetAppAllowed} but
+ * resolves identities via {@link androidAppAllowedIdentities} (package name or
+ * canonical APK path) rather than macOS bundle identities.
+ */
+declare function assertAndroidAppAllowed(allowedApps: string[], app: string, resolvedPackage?: string): void;
 
 type StepCallback = (result: StepResult, step: Step, index: number) => void;
 
@@ -606,6 +1199,10 @@ type RunOptions = {
     junit?: boolean;
     /** Inject a macOS helper client (tests / a prebuilt binary); defaults to spawning the helper. */
     macClientFactory?: () => MacHelperClient;
+    /** Inject an Android session factory (tests); defaults to {@link launchAndroidSession}. */
+    androidSessionFactory?: (options: LaunchAndroidOptions) => Promise<AndroidSession>;
+    /** Inject an iOS session factory (tests); defaults to {@link launchIosSession}. */
+    iosSessionFactory?: (options: LaunchIosOptions) => Promise<IosSession>;
 };
 declare function runHunt(options: RunOptions): Promise<{
     result: RunResult;
@@ -813,6 +1410,36 @@ declare const configSchema: z.ZodObject<{
     }, {
         app: string;
         type: "macos";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"android">;
+        app: z.ZodString;
+        deviceSerial: z.ZodOptional<z.ZodString>;
+        coldStart: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        app: string;
+        type: "android";
+        deviceSerial?: string | undefined;
+        coldStart?: boolean | undefined;
+    }, {
+        app: string;
+        type: "android";
+        deviceSerial?: string | undefined;
+        coldStart?: boolean | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"ios">;
+        app: z.ZodString;
+        udid: z.ZodOptional<z.ZodString>;
+        coldStart: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        app: string;
+        type: "ios";
+        udid?: string | undefined;
+        coldStart?: boolean | undefined;
+    }, {
+        app: string;
+        type: "ios";
+        udid?: string | undefined;
+        coldStart?: boolean | undefined;
     }>, z.ZodObject<{
         type: z.ZodOptional<z.ZodLiteral<"web">>;
         url: z.ZodString;
@@ -959,6 +1586,16 @@ declare const configSchema: z.ZodObject<{
     } | {
         app: string;
         type: "macos";
+    } | {
+        app: string;
+        type: "android";
+        deviceSerial?: string | undefined;
+        coldStart?: boolean | undefined;
+    } | {
+        app: string;
+        type: "ios";
+        udid?: string | undefined;
+        coldStart?: boolean | undefined;
     };
     browser?: {
         timeout?: number | undefined;
@@ -1014,6 +1651,16 @@ declare const configSchema: z.ZodObject<{
     } | {
         app: string;
         type: "macos";
+    } | {
+        app: string;
+        type: "android";
+        deviceSerial?: string | undefined;
+        coldStart?: boolean | undefined;
+    } | {
+        app: string;
+        type: "ios";
+        udid?: string | undefined;
+        coldStart?: boolean | undefined;
     };
     browser?: {
         timeout?: number | undefined;
@@ -1212,6 +1859,97 @@ type AnalysisResult = {
 };
 declare function analyzePage(page: DomEvaluator): Promise<AnalysisResult>;
 
+/**
+ * PROWL-055 / ARCH-007 — macOS analyzer.
+ *
+ * The native analog of {@link analyzePage}: dumps a macOS app's interactive
+ * elements with ranked selector candidates so hunt authors don't have to guess
+ * accessibility identifiers. It talks to the same `prowl-macdriver` helper the
+ * runner uses ({@link MacHelperClient}) — reading the AX tree, the window list,
+ * and (read-only) the status-item menu — and shapes the result to mirror the web
+ * analyzer's feel.
+ *
+ * Selector ranking (best → last resort), matching the driver's selector dialect
+ * so the emitted selectors are directly usable in hunts:
+ *   id=<AXIdentifier>              (best — the native `data-testid`)
+ *   label="<exact title/desc>"     (exact accessibility label)
+ *   role=<role>[name="<name>"]     (role + accessible name)
+ *   text="<substring>"             (last resort — substring match)
+ *
+ * Read-only: the ONLY state-changing interaction is opening the status-item menu
+ * to read its items (their identifiers are gold) and immediately closing it.
+ */
+
+/**
+ * The interactive AX roles the analyzer surfaces from the window tree. Menu
+ * items are collected separately via the status-item menu; windows are listed
+ * as navigable surfaces. Tuned from the roles the helper's `tree`/`openMenu`
+ * payloads actually expose for controls.
+ */
+declare const INTERACTIVE_ROLES: ReadonlySet<string>;
+/** Default AX-tree depth requested from the helper (deeper than the run default). */
+declare const DEFAULT_ANALYZE_TREE_DEPTH = 20;
+/** A single element the `axInfo` snapshot describes (tree / menu / window node). */
+type MacAxNode = {
+    role?: string;
+    title?: string;
+    description?: string;
+    value?: string;
+    identifier?: string;
+    enabled?: boolean;
+    children?: MacAxNode[];
+};
+/** An interactive element with ranked selector candidates (best first). */
+type MacAnalysisElement = {
+    role: string;
+    title?: string;
+    description?: string;
+    value?: string;
+    identifier?: string;
+    enabled?: boolean;
+    /** Where the element was discovered: the app's window tree or the status menu. */
+    source: "window" | "menu";
+    /** Ranked selector candidates, best first. Always at least one entry. */
+    selectors: string[];
+};
+/** A top-level window, exposed as a navigable surface with its best selector. */
+type MacAnalysisWindow = {
+    title?: string;
+    identifier?: string;
+    /** Best selector candidate for the window. */
+    selector: string;
+};
+type MacAnalysisResult = {
+    /** Bundle id (or the app reference) of the analyzed app. */
+    app: string;
+    elements: MacAnalysisElement[];
+    windows: MacAnalysisWindow[];
+    menuItems: MacAnalysisElement[];
+};
+/**
+ * Ranked selector candidates for an element, best first. Mirrors the driver's
+ * selector dialect (`id=` > `label=` > `role=…[name="…"]` > `text=`). Falls back
+ * to a bare `role=<role>` so every element with a role is at least addressable.
+ */
+declare function rankMacSelectors(node: MacAxNode): string[];
+type AnalyzeMacOptions = {
+    /** Bundle id / app label to report in the result. */
+    app: string;
+    /** AX-tree depth to request from the helper. */
+    treeDepth?: number;
+    /** Timeout (seconds) for opening the status-item menu. */
+    menuTimeoutSeconds?: number;
+};
+/**
+ * Analyze an already-launched macOS app through `client`, returning its
+ * interactive elements, windows, and status-menu items with ranked selectors.
+ *
+ * The caller owns the session lifecycle (launch + guardrails + teardown); this
+ * function is read-only apart from opening and immediately closing the
+ * status-item menu to read its contents.
+ */
+declare function analyzeMacApp(client: MacHelperClient, options: AnalyzeMacOptions): Promise<MacAnalysisResult>;
+
 type AiProvider = "anthropic" | "openai";
 type AiConfig = {
     provider: AiProvider;
@@ -1229,4 +1967,4 @@ type GenerateOptions = {
 };
 declare function generateHunt(options: GenerateOptions): Promise<string>;
 
-export { type AnalysisResult, type AssertScreenshotStep, type Assertion, type AssertionResult, type BrowserChannel, type BrowserEngine, type BugFailure, type BugLogSummary, type CiFailureCluster, type CiFlakyHunt, type CiHuntResult, type CiResult, type CiStatus, type Config, DEFAULT_FLAKY_THRESHOLD, DEFAULT_REQUEST_TIMEOUT_MS, type EvalScriptStep, type FailureCluster, type FlakyScore, type GenerateOptions, type HealResult, type HistoryEntry, type HistoryFile, type Hunt, type IfStep, type LaunchMacOptions, type MacDriverOptions, type MacHelperClient, type MacQuery, type MacSession, type MacosTarget, type MockRouteStep, type PageElement, type PageForm, type PageLink, type RankFlakyOptions, type ReliabilityConfig, type RepeatStep, type RunArtifacts, type RunOptions, type RunResult, type RunScriptStep, type RunSuiteHooks, type RunSuiteOptions, type RunSuiteResult, SpawnMacHelperClient, type SpawnMacHelperOptions, type Step, type StepResult, type Target, type UnmockRouteStep, type UpdateBacklogOptions, type Viewport, WEB_ONLY_STEP_TYPES, type WebTarget, analyzePage, assertStepsSupportedByTarget, assertTargetAppAllowed, buildHealCandidates, closeMacSession, clusterFailures, computeFlakeScore, configSchema, createMacDriver, extractFailures, extractSelectorIntent, generateHunt, healSelector, huntSchema, interpolateHunt, launchMacSession, listHunts, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, macdriverBuildInstructions, parseMacSelector, rankFlaky, readHistory, readHuntHistory, resolveHelperBinary, runHunt, runSuite, stepSchema, updateBacklogFromSuite, webOnlyReason };
+export { ANDROID_KEYCODES, type AdbDevice, type AdbResult, type AdbRunner, type AdbSpawner, type AgentApks, type AgentConnector, type AnalysisResult, type AnalyzeMacOptions, type AndroidAgentClient, type AndroidDriverOptions, type AndroidLocator, type AndroidQuery, type AndroidSession, type AndroidTarget, type AssertScreenshotStep, type Assertion, type AssertionResult, type BrowserChannel, type BrowserEngine, type BugFailure, type BugLogSummary, type CiFailureCluster, type CiFlakyHunt, type CiHuntResult, type CiResult, type CiStatus, type Config, DEFAULT_AGENT_REQUEST_TIMEOUT_MS, DEFAULT_ANALYZE_TREE_DEPTH, DEFAULT_FLAKY_THRESHOLD, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_SIMULATOR_LOCK_ROOT, DEFAULT_WDA_REQUEST_TIMEOUT_MS, type EvalScriptStep, type FailureCluster, type FetchLike$1 as FetchLike, type FlakyScore, type GenerateOptions, type HealResult, type HistoryEntry, type HistoryFile, type Hunt, INTERACTIVE_ROLES, IOS_PRESS_KEYS, type IfStep, type IosAgentClient, type IosAgentConnector, type IosDriverOptions, type IosLocator, type IosQuery, type IosSession, type IosTarget, type LaunchAndroidOptions, type LaunchIosOptions, type LaunchMacOptions, type MacAnalysisElement, type MacAnalysisResult, type MacAnalysisWindow, type MacAxNode, type MacDriverOptions, type MacHelperClient, type MacQuery, type MacSession, type MacosTarget, type MockRouteStep, type PageElement, type PageForm, type PageLink, type RankFlakyOptions, type ReliabilityConfig, type RepeatStep, type ReserveSimulatorOptions, type ResolveWdaRunnerOptions, type RunArtifacts, type RunOptions, type RunResult, type RunScriptStep, type RunSuiteHooks, type RunSuiteOptions, type RunSuiteResult, type SimDevice, type SimctlResult, type SimctlRunner, type SimulatorReservation, SpawnMacHelperClient, type SpawnMacHelperOptions, type Step, type StepResult, type Target, UIA2_REMOTE_PORT, Uia2HttpError, Uia2Transport, type Uia2TransportOptions, type UnmockRouteStep, type UpdateBacklogOptions, type Viewport, WDA_RUNNER_APP_NAME, WDA_RUNNER_BUNDLE_ID, WEB_ONLY_STEP_TYPES, WdaHttpError, WdaTransport, type WdaTransportOptions, type WebTarget, analyzeMacApp, analyzePage, androidAppAllowedIdentities, androidQueryToLocator, assertAndroidAppAllowed, assertIosAppAllowed, assertStepsSupportedByTarget, assertTargetAppAllowed, bootedDevices, bootedSimulators, buildHealCandidates, closeAndroidSession, closeIosSession, closeMacSession, clusterFailures, computeFlakeScore, configSchema, createAndroidDriver, createIosDriver, createMacDriver, createUia2AgentClient, createUia2Session, createWdaAgentClient, createWdaSession, defaultAgentConnector, defaultIosAgentConnector, escapePredicateArg, escapeUiSelectorArg, extractElementId, extractFailures, extractSelectorIntent, findFreePort, generateHunt, healSelector, huntSchema, interpolateHunt, iosAppAllowedIdentities, iosQueryToLocator, launchAndroidSession, launchIosSession, launchMacSession, listDevices, listHunts, listSimulators, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, macdriverBuildInstructions, normalizeXcuiClassName, parseAaptPackage, parseAdbDevices, parseAndroidSelector, parseForwardPort, parseIosSelector, parseMacSelector, parseSimctlDevices, parseXcodeVersion, rankFlaky, rankMacSelectors, readHistory, readHuntHistory, readIosBundleIdentifier, reserveSimulatorUdid, resolveAgentApks, resolveHelperBinary, resolveWdaProject, resolveWdaRunner, runHunt, runSuite, selectDeviceSerial, selectSimulatorUdid, stepSchema, unwrapAndroidTextSelector, unwrapIosTextSelector, updateBacklogFromSuite, waitForAgentReady, waitForWdaReady, wdaCacheDir, webOnlyReason };