prompttest-mobile 1.5.1

package/dist/lib/adaptive-timing.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module adaptive-timing
+ * @description Device-Aware Adaptive Dynamic Waiting & Auto-Profiling.
+ *
+ * Automatically balances test timing between ultra-fast physical devices (USB 3.0)
+ * and resource-constrained CI emulators (software-rendered VMs in GitHub Actions).
+ *
+ * Implements exponential backoff condition-driven polling with instant short-circuiting:
+ * fast devices finish immediately upon event completion, while slow emulators receive
+ * adaptive headroom without CPU exhaustion.
+ */
+import type { AndroidDriver } from './adb.js';
+export interface DeviceProfile {
+    /** Whether the target device is an emulator / virtual device */
+    isEmulator: boolean;
+    /** Whether the process is executing inside a CI / CD environment (e.g. GitHub Actions) */
+    isCI: boolean;
+    /** Calculated dynamic velocity multiplier (1.0 = real device, 1.5 = local emulator, 2.5 = CI) */
+    velocityMultiplier: number;
+    /** Default timeout ceiling for UI element detection */
+    defaultTimeoutMs: number;
+    /** Extended timeout ceiling for multi-step transitions and cold loads */
+    extendedTimeoutMs: number;
+    /** Minimum stability duration for dual-sample quiescence verification */
+    quiescenceSettleMs: number;
+    /** Initial polling interval in milliseconds */
+    initialPollMs: number;
+    /** Maximum backoff polling interval in milliseconds */
+    maxPollIntervalMs: number;
+}
+/**
+ * Probes the connected device and host runtime to construct an adaptive timing profile.
+ * Cached per session so that subsequent steps reuse the profiled characteristics.
+ *
+ * @param driver - Android driver instance
+ * @param serial - Optional target device serial
+ */
+export declare function profileDeviceEnvironment(driver: AndroidDriver, serial?: string): Promise<DeviceProfile>;
+/**
+ * Resets the cached device profile (primarily used in testing).
+ */
+export declare function resetDeviceProfile(): void;
+/**
+ * Polls an asynchronous condition using adaptive backoff with immediate short-circuiting.
+ *
+ * Fast devices short-circuit the instant the condition returns a truthy value.
+ * Slow emulators receive backoff polling that preserves CPU cycles for rendering.
+ *
+ * @param checkFn - Async callback returning a truthy value when the condition is met.
+ * @param timeoutMs - Maximum duration to wait before giving up.
+ * @param initialIntervalMs - Starting interval between checks.
+ * @param maxIntervalMs - Cap for the backoff interval.
+ * @returns The resolved value of the condition, or throws a timeout Error.
+ */
+export declare function pollWithAdaptiveBackoff<T>(checkFn: () => Promise<T | null | undefined | false>, timeoutMs: number, initialIntervalMs?: number, maxIntervalMs?: number): Promise<T>;

package/dist/lib/adb-provisioner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module adb-provisioner
+ * @description
+ * Zero-dependency hardware discovery and ADB provisioning engine.
+ * Automatically discovers, validates, and provisions Android Debug Bridge (ADB)
+ * binaries across Windows, macOS, and Linux without requiring full Android Studio installation.
+ */
+export interface AdbDiagnosticInfo {
+    binaryPath: string;
+    isAvailable: boolean;
+    version?: string;
+    source: 'PROMPTTEST_OVERRIDE' | 'BUNDLED_LOCAL' | 'SYSTEM_PATH' | 'ANDROID_HOME' | 'STANDALONE_CACHE' | 'STANDARD_SDK' | 'FALLBACK';
+}
+/**
+ * Discovers the absolute or executable path to the ADB binary on the host system.
+ * Evaluates candidate locations in strict order of reliability:
+ * 1. Environment override (`PROMPTTEST_ADB_PATH`)
+ * 2. Bundled / Adjacent platform-tools (next to executable, app bundle, or current cwd)
+ * 3. System PATH lookup
+ * 4. Android SDK environment variables (`ANDROID_HOME`, `ANDROID_SDK_ROOT`)
+ * 5. Standard platform installation paths
+ * 6. Standalone user cache (`~/.prompttest/platform-tools/adb`)
+ */
+export declare function getAdbBinary(): string;
+/**
+ * Checks whether the resolved ADB binary is executable and operational.
+ *
+ * @param customPath Optional custom binary path to verify.
+ */
+export declare function isAdbAvailable(customPath?: string): boolean;
+/**
+ * Returns full diagnostics about ADB availability and resolution origin.
+ */
+export declare function getAdbDiagnostics(): AdbDiagnosticInfo;
+/**
+ * Resets cached ADB path (useful for testing and runtime environment shifts).
+ */
+export declare function resetAdbCache(): void;
+/**
+ * Automatically downloads and provisions official platform-tools if ADB is missing.
+ */
+export declare function downloadPlatformToolsFallback(customDestDir?: string): Promise<string>;
+/**
+ * Prompts the user for explicit permission to download official platform-tools if ADB is missing.
+ * Automatically approved if --download-adb, -y, or --yes flag is present in process.argv.
+ */
+export declare function promptUserForAdbDownload(): Promise<boolean>;
+/**
+ * Asserts that ADB is available, prompting for user permission before automated provisioning if missing.
+ *
+ * @param options.skipPrompt If true, bypasses the user prompt (e.g. when --download-adb flag is passed).
+ */
+export declare function ensureAdbProvisioned(options?: {
+    skipPrompt?: boolean;
+}): Promise<string>;

package/dist/lib/adb.d.ts

@@ -0,0 +1,448 @@
+/**
+ * @module adb
+ * @description
+ * Low-level ADB native driver for the PromptTest framework.
+ * This module manages device communication, screen capture, touch input, app lifecycle,
+ * and logcat streaming using Android Debug Bridge (ADB).
+ * It acts as the bridge between the framework and the physical/emulated Android devices.
+ */
+/**
+ * Represents a connected Android device and its attributes.
+ */
+export interface AndroidDevice {
+    /** The unique serial number or IP:Port of the device */
+    serial: string;
+    /** The connection state of the device */
+    state: 'device' | 'offline' | 'unauthorized' | 'unknown';
+    /** The hardware model of the device (optional) */
+    model?: string;
+    /** The product name of the device (optional) */
+    product?: string;
+    /** Transport connection type: 'usb' | 'wifi' | 'emulator' */
+    connectionType?: 'usb' | 'wifi' | 'emulator';
+}
+export interface DeviceMetrics {
+    battery?: {
+        level?: number;
+        temperatureC?: number;
+        status?: string;
+    };
+    display?: {
+        width?: number;
+        height?: number;
+        density?: number;
+    };
+    memory?: {
+        pssKb?: number;
+        privateDirtyKb?: number;
+        nativeHeapKb?: number;
+    };
+    graphics?: {
+        framesRendered?: number;
+        jankyFrames?: number;
+        percentile90Ms?: number;
+    };
+}
+export declare function parseDeviceMetrics(batteryOutput: string, displayOutput: string, memoryOutput: string, graphicsOutput: string): DeviceMetrics;
+/**
+ * Classifies a device connection type from its serial or model properties.
+ */
+export declare function classifyDeviceConnection(serial: string): 'usb' | 'wifi' | 'emulator';
+/**
+ * Deduplicates multiple transport connections for the same physical Android hardware.
+ * Priority: USB > Wi-Fi (IP:port) > Wi-Fi (mDNS) > Emulator.
+ * Prevents simultaneous execution collisions on the same physical phone.
+ */
+export declare function deduplicateDevices(devices: AndroidDevice[]): AndroidDevice[];
+/**
+ * AndroidDriver is responsible for executing ADB commands and handling device interactions.
+ * It manages the default targeted device, executes shell commands, extracts device state,
+ * handles input events, and streams logcat output.
+ */
+export declare class AndroidDriver {
+    private defaultSerial;
+    private cachedDimensions;
+    private inFlightHierarchies;
+    /**
+     * Initializes a new AndroidDriver instance.
+     * @param serial Optional serial number to set as the default device.
+     */
+    constructor(serial?: string);
+    /**
+     * Sets the default device serial to be used for subsequent commands.
+     * @param serial The device serial number or IP:port.
+     */
+    setDefaultDevice(serial: string): void;
+    /**
+     * Gets the currently set default device serial.
+     * @returns The default serial number, or null if none is set.
+     */
+    getDefaultDevice(): string | null;
+    /**
+     * Gets the physical screen dimensions of the device.
+     * Caches the result to prevent repeated ADB calls.
+     * @param serial Optional target device serial.
+     * @returns An object containing the width and height of the screen.
+     */
+    getScreenDimensions(serial?: string): Promise<{
+        width: number;
+        height: number;
+    }>;
+    /**
+     * Invalidates cached screen dimensions for a device or all devices (e.g. after screen rotation).
+     * @param serial Optional target device serial.
+     */
+    clearScreenDimensionsCache(serial?: string): void;
+    /**
+     * Retrieves the height of the device's navigation bar.
+     * @param serial Optional target device serial.
+     * @returns The navigation bar height in pixels, or 0 if not found.
+     */
+    getNavigationBarHeight(serial?: string): Promise<number>;
+    private isGlobalAdbCommand;
+    private execAdbInternal;
+    /**
+     * Executes an ADB command and returns its standard output and error.
+     * Features an exponential backoff retry loop for transient failures (e.g., device offline).
+     * @param args The ADB command arguments.
+     * @param serial Optional target device serial.
+     * @param timeoutMs Command execution timeout in milliseconds (default: 20000).
+     * @param maxRetries Maximum number of retries upon failure (default: 2).
+     * @returns An object containing stdout and stderr as strings.
+     * @throws An Error if the command fails consistently or times out.
+     */
+    execAdb(args: readonly string[] | string[], serial?: string, timeoutMs?: number, maxRetries?: number): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /**
+     * Executes an ADB command that returns binary data, such as screen captures.
+     * @param args The ADB command arguments.
+     * @param serial Optional target device serial.
+     * @param timeoutMs Command execution timeout in milliseconds (default: 45000).
+     * @returns A Buffer containing the command's binary output.
+     * @throws An Error if the command fails or times out.
+     */
+    execAdbBinary(args: readonly string[] | string[], serial?: string, timeoutMs?: number): Promise<Buffer>;
+    /**
+    /**
+     * Retrieves all raw connected Android devices from ADB without deduplication.
+     */
+    getRawConnectedDevices(): Promise<AndroidDevice[]>;
+    /**
+     * Retrieves a list of currently connected Android devices.
+     * By default, deduplicates multiple transport channels for the same physical phone (prioritizing USB > Wi-Fi).
+     * @param options.deduplicate Set to false to return raw unfiltered endpoints.
+     * @returns A promise resolving to an array of AndroidDevice objects.
+     */
+    getConnectedDevices(options?: {
+        deduplicate?: boolean;
+    }): Promise<AndroidDevice[]>;
+    /**
+     * Helper utility to deduplicate a list of AndroidDevice items.
+     */
+    deduplicateDevices(devices: AndroidDevice[]): AndroidDevice[];
+    /**
+     * Wakes up the device screen and attempts to dismiss the keyguard.
+     * @param serial Optional target device serial.
+     */
+    wakeDevice(serial?: string): Promise<void>;
+    /**
+     * Ensures a default device is selected, waking it up in the process.
+     * If no default is set, it selects the first authorized connected device.
+     * @param serial Optional explicit serial to set and wake.
+     * @returns The determined default serial number, or undefined if no devices are available.
+     */
+    ensureDefaultDevice(serial?: string): Promise<string | undefined>;
+    /**
+     * Retrieves the hardware model name of the specified device.
+     * @param serial Optional target device serial.
+     * @returns The model string of the device, or a fallback generic string.
+     */
+    getDeviceModel(serial?: string): Promise<string>;
+    /**
+     * Captures a screenshot from the device.
+     * @param serial Optional target device serial.
+     * @returns A Buffer containing the raw PNG screenshot data.
+     */
+    captureScreenshot(serial?: string): Promise<Buffer>;
+    /**
+     * Dumps the current UI hierarchy XML from the device screen.
+     * Coalesces concurrent in-flight calls for the same device to prevent redundant ADB invocations (SP-01).
+     * @param serial Optional target device serial.
+     * @returns A string containing the UI hierarchy XML.
+     */
+    getUiHierarchy(serial?: string): Promise<string>;
+    /**
+     * Clears any active in-flight hierarchy promises (e.g. after error or teardown).
+     * @param serial Optional target device serial.
+     */
+    clearInFlightHierarchies(serial?: string): void;
+    /**
+     * Identifies the package name of the app currently running in the foreground.
+     * Uses dumpsys to inspect activities and window focus.
+     * @param serial Optional target device serial.
+     * @returns The package name of the foreground app, or null if it cannot be determined.
+     */
+    getForegroundPackage(serial?: string): Promise<string | null>;
+    /**
+     * Taps on the screen at the specified coordinates.
+     * @param x The X coordinate.
+     * @param y The Y coordinate.
+     * @param serial Optional target device serial.
+     */
+    tap(x: number, y: number, serial?: string): Promise<void>;
+    /**
+     * Inputs text into the currently focused text field on the device.
+     * Falls back to character-by-character injection if shell escaping fails.
+     * @param text The string to input.
+     * @param serial Optional target device serial.
+     */
+    inputText(text: string, serial?: string): Promise<void>;
+    /**
+     * Simulates pressing a hardware key on the device.
+     * @param keyCode The Android keycode (number or string).
+     * @param serial Optional target device serial.
+     */
+    pressKey(keyCode: number | string, serial?: string): Promise<void>;
+    /**
+     * Simulates pressing the Enter key.
+     * @param serial Optional target device serial.
+     */
+    pressEnter(serial?: string): Promise<void>;
+    /**
+     * Simulates pressing the Tab key.
+     * @param serial Optional target device serial.
+     */
+    pressTab(serial?: string): Promise<void>;
+    /**
+     * Simulates pressing the Home key.
+     * @param serial Optional target device serial.
+     */
+    pressHome(serial?: string): Promise<void>;
+    /**
+     * Simulates pressing the Back key (KEYCODE_BACK: 4).
+     * @param serial Optional target device serial.
+     */
+    pressBack(serial?: string): Promise<void>;
+    /**
+     * Enables or disables Wi-Fi connectivity on the device.
+     * @param enabled True to enable Wi-Fi, false to disable.
+     * @param serial Optional target device serial.
+     */
+    setWifiEnabled(enabled: boolean, serial?: string): Promise<void>;
+    /**
+     * Enables or disables Airplane mode on the device.
+     * @param enabled True to enable airplane mode, false to disable.
+     * @param serial Optional target device serial.
+     */
+    setAirplaneMode(enabled: boolean, serial?: string): Promise<void>;
+    /**
+     * Locks the screen orientation to portrait (0) or landscape (1).
+     * @param orientation Desired orientation ('portrait' | 'landscape').
+     * @param serial Optional target device serial.
+     */
+    setOrientation(orientation: 'portrait' | 'landscape', serial?: string): Promise<void>;
+    /**
+     * Expands the system notification shade.
+     * @param serial Optional target device serial.
+     */
+    openNotificationShade(serial?: string): Promise<void>;
+    /**
+     * Collapses the system notification shade.
+     * @param serial Optional target device serial.
+     */
+    collapseNotificationShade(serial?: string): Promise<void>;
+    /**
+     * Clears the current input field by sending multiple backspace key events.
+     * @param count The number of backspaces to send (default: 45).
+     * @param serial Optional target device serial.
+     */
+    clearInput(count?: number, serial?: string): Promise<void>;
+    /**
+     * Aggressively clears a text field by moving the cursor to both ends and deleting.
+     * @param serial Optional target device serial.
+     * @param fieldLength Estimated length of the field to clear (default: 80).
+     */
+    clearField(serial?: string, fieldLength?: number): Promise<void>;
+    /**
+     * Performs a swipe gesture on the device screen.
+     * @param x1 The starting X coordinate.
+     * @param y1 The starting Y coordinate.
+     * @param x2 The ending X coordinate.
+     * @param y2 The ending Y coordinate.
+     * @param durationMs The duration of the swipe in milliseconds (default: 300).
+     * @param serial Optional target device serial.
+     */
+    swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number, serial?: string): Promise<void>;
+    /**
+     * Launches an application by its package name.
+     * @param packageName The package name of the app to launch.
+     * @param serial Optional target device serial.
+     */
+    launchApp(packageName: string, serial?: string): Promise<void>;
+    /**
+     * Force stops an application.
+     * @param packageName The package name of the app to stop.
+     * @param serial Optional target device serial.
+     */
+    forceStop(packageName: string, serial?: string): Promise<void>;
+    /**
+     * Clears the user data and cache of an application.
+     * @param packageName The package name of the app to clear.
+     * @param serial Optional target device serial.
+     */
+    clearAppData(packageName: string, serial?: string): Promise<void>;
+    /**
+     * Restarts an application by force stopping and then launching it again.
+     * @param packageName The package name of the app to restart.
+     * @param serial Optional target device serial.
+     */
+    restartApp(packageName: string, serial?: string): Promise<void>;
+    /**
+     * Grants a specific runtime permission to an application.
+     * @param packageName The package name of the app.
+     * @param permission The Android permission string (e.g., android.permission.CAMERA).
+     * @param serial Optional target device serial.
+     */
+    grantPermission(packageName: string, permission: string, serial?: string): Promise<void>;
+    /**
+     * Checks if an application is installed on the device.
+     * @param packageName The package name to check.
+     * @param serial Optional target device serial.
+     * @returns True if the app is installed, false otherwise.
+     */
+    isAppInstalled(packageName: string, serial?: string): Promise<boolean>;
+    /**
+     * Installs an APK onto the device.
+     * @param apkPath The local file path to the APK.
+     * @param serial Optional target device serial.
+     */
+    installApk(apkPath: string, serial?: string): Promise<void>;
+    /**
+     * Uninstalls an application from the device.
+     * @param packageName The package name of the app to uninstall.
+     * @param serial Optional target device serial.
+     */
+    uninstallApp(packageName: string, serial?: string): Promise<void>;
+    /**
+     * Opens a deep link URI on the device.
+     * @param uri The deep link URI string.
+     * @param serial Optional target device serial.
+     */
+    openDeepLink(uri: string, serial?: string): Promise<void>;
+    /**
+     * Checks the logcat buffer for fatal crashes related to a specific package.
+     * @param packageName The package name to check for crashes.
+     * @param serial Optional target device serial.
+     * @returns The crash log string if found, otherwise null.
+     */
+    checkCrashes(packageName: string, serial?: string): Promise<string | null>;
+    /**
+     * Clears historical crash logs from the logcat buffer.
+     * @param serial Optional target device serial.
+     */
+    clearCrashLogs(serial?: string): Promise<void>;
+    /**
+     * Auto-detects the device's local Wi-Fi IPv4 address on the active wlan0 interface.
+     * @param serial Optional target device serial.
+     * @returns The detected IPv4 address, or null if not found.
+     */
+    getDeviceIp(serial?: string): Promise<string | null>;
+    /**
+     * Switches device to TCP/IP mode and establishes a wireless ADB connection.
+     * @param customTarget Optional IP or IP:Port to connect to.
+     * @param port The port to use for the TCP connection (default: 5555).
+     * @param serial Optional target device serial.
+     * @returns An object detailing the connection success, target, and message.
+     * @throws An Error if the device IP cannot be detected.
+     */
+    connectWifi(customTarget?: string, port?: number, serial?: string): Promise<{
+        success: boolean;
+        target: string;
+        message: string;
+    }>;
+    /**
+     * Disconnects wireless Wi-Fi ADB connection.
+     * @param customTarget Optional IP or IP:Port to connect to.
+     * @param port The port to use for the TCP connection (default: 5555).
+     * @param serial Optional target device serial.
+     * @returns An object detailing the connection success, target, and message.
+     * @throws An Error if the device IP cannot be detected.
+     */
+    disconnectWifi(target?: string): Promise<string>;
+    pairWifi(target: string, pairingCode: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    getDeviceMetrics(serial?: string): Promise<DeviceMetrics>;
+    /**
+     * Streams the Android events logcat buffer in real-time.
+     * Used for detecting screen transitions via wm_on_resume_called events.
+     * Non-blocking: fires onLine callback for each log line received.
+     * @param serial The target device serial.
+     * @param onLine Callback function invoked for each log line.
+     * @returns The spawned child process running the logcat command.
+     */
+    streamLogcatEvents(serial: string, onLine: (line: string) => void): import('child_process').ChildProcess;
+    /**
+     * Streams the main logcat buffer filtered for crash and ANR signals.
+     * Non-blocking: fires onLine callback whenever AndroidRuntime or ANR logs appear.
+     * @param serial The target device serial.
+     * @param onLine Callback function invoked for each crash log line.
+     * @returns The spawned child process running the logcat command.
+     */
+    streamLogcatCrashes(serial: string, onLine: (line: string) => void): import('child_process').ChildProcess;
+    /**
+     * Streams logcat filtered for Toast and Snackbar signals.
+     * Non-blocking: fires onLine callback for UI feedback messages.
+     * @param serial The target device serial.
+     * @param onLine Callback function invoked for each toast/snackbar log line.
+     * @returns The spawned child process running the logcat command.
+     */
+    streamLogcatToasts(serial: string, onLine: (line: string) => void): import('child_process').ChildProcess;
+    /**
+     * Retrieves the last N lines of device logcat for triage and diagnostic reporting.
+     * @param lines Number of logcat lines to capture (default: 150).
+     * @param serial Optional target device serial.
+     * @returns The captured logcat output as a string.
+     */
+    getLogcatTail(lines?: number, serial?: string): Promise<string>;
+    /**
+     * Starts a non-blocking background screen recording via ADB shell screenrecord.
+     * @param remotePath Device path to store the temporary MP4 recording (default: '/sdcard/prompttest_temp.mp4').
+     * @param serial Optional target device serial.
+     * @returns An object containing the remote file path and the spawned ChildProcess.
+     */
+    startScreenRecording(remotePath?: string, serial?: string): Promise<{
+        remotePath: string;
+        process: import('child_process').ChildProcess;
+    }>;
+    /**
+     * Stops an active screen recording, pulls the MP4 file to host, and cleans up device storage.
+     * @param recording The recording object returned by startScreenRecording.
+     * @param localDestPath Local path where the MP4 video will be saved.
+     * @param serial Optional target device serial.
+     * @returns The local path to the saved MP4 recording.
+     */
+    stopScreenRecording(recording: {
+        remotePath: string;
+        process: import('child_process').ChildProcess;
+    }, localDestPath: string, serial?: string): Promise<string>;
+    /**
+     * Checks if the virtual software keyboard (IME) is currently active and visible on screen.
+     * Uses fast shell grep filtering across Android IME & Window properties with resilient fallbacks.
+     * @param serial Optional target device serial.
+     * @returns Promise resolving to true if virtual keyboard is displayed.
+     */
+    isKeyboardVisible(serial?: string): Promise<boolean>;
+    /**
+     * Enables Android accessibility settings to assist WebView node extraction.
+     * @param serial Optional target device serial.
+     */
+    ensureAccessibilityServices(serial?: string): Promise<void>;
+}
+/**
+ * Singleton instance of AndroidDriver exported for application-wide use.
+ */
+export declare const androidDriver: AndroidDriver;

package/dist/lib/ai/heuristic-resolver.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module ai/heuristic-resolver
+ * @description Fully offline heuristic resolver utilizing Levenshtein distance,
+ * synonym dictionaries, and spatial/structural rules. Requires zero network calls or API keys.
+ */
+import { UiNode } from '../crawler.js';
+import { PromptStep } from '../prompt-runner.js';
+import { SemanticResolver, Suggestion, SemanticContext } from './types.js';
+export declare class HeuristicResolver implements SemanticResolver {
+    readonly providerName = "heuristic";
+    /**
+     * Expands recognized standard macro intents offline.
+     */
+    resolveIntent(intent: string, _ctx?: SemanticContext): Promise<PromptStep[] | null>;
+    /**
+     * Discovers matching replacement elements when a target locator is broken or missing.
+     */
+    findSuggestions(missingTarget: string, flat: UiNode[], _ctx?: SemanticContext): Promise<Suggestion[]>;
+}

package/dist/lib/ai/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module ai
+ * @description Semantic resolution, AI provider integration, and self-healing engine.
+ */
+import { SemanticResolver } from './types.js';
+import { PromptTestConfig } from '../config-loader.js';
+export * from './types.js';
+export * from './heuristic-resolver.js';
+export * from './llm-provider.js';
+/**
+ * Creates and returns the appropriate SemanticResolver based on configuration.
+ *
+ * @param config - Optional configuration overrides.
+ * @returns An initialized SemanticResolver instance.
+ */
+export declare function createSemanticResolver(config?: Partial<PromptTestConfig['ai']>): SemanticResolver;

package/dist/lib/ai/llm-provider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module ai/llm-provider
+ * @description Cloud and local LLM semantic resolver implementations supporting
+ * OpenAI, Anthropic, Ollama, and Mock providers for automated intent expansion and self-healing.
+ */
+import { UiNode } from '../crawler.js';
+import { PromptStep } from '../prompt-runner.js';
+import { SemanticResolver, Suggestion, SemanticContext } from './types.js';
+export interface LLMConfig {
+    provider: 'openai' | 'anthropic' | 'ollama' | 'mock';
+    model?: string;
+    apiKey?: string;
+    endpoint?: string;
+    timeoutMs?: number;
+}
+/**
+ * Mock resolver for deterministic unit tests and headless CI environments.
+ */
+export declare class MockAIProvider implements SemanticResolver {
+    readonly providerName = "mock";
+    private mockIntents;
+    private mockSuggestions;
+    constructor();
+    setMockIntent(intent: string, steps: PromptStep[]): void;
+    setMockSuggestion(target: string, suggestions: Suggestion[]): void;
+    resolveIntent(intent: string, _ctx?: SemanticContext): Promise<PromptStep[] | null>;
+    findSuggestions(missingTarget: string, flat: UiNode[], _ctx?: SemanticContext): Promise<Suggestion[]>;
+}
+/**
+ * Production LLM resolver communicating with OpenAI, Anthropic, or Ollama.
+ */
+export declare class LLMResolver implements SemanticResolver {
+    readonly providerName: string;
+    private config;
+    private heuristicFallback;
+    constructor(config: LLMConfig);
+    resolveIntent(intent: string, ctx?: SemanticContext): Promise<PromptStep[] | null>;
+    findSuggestions(missingTarget: string, flat: UiNode[], ctx?: SemanticContext): Promise<Suggestion[]>;
+    private callLlm;
+}