@loadmill/droid-cua 2.13.0 → 2.15.1

package/build/src/device/ios/connection.js

@@ -82,12 +82,13 @@ async function findAnySimulator() {
  * @param {string} simulatorName
  * @returns {Promise<string>} UDID of the simulator
  */
-async function bootSimulator(simulatorName) {
+async function bootSimulator(simulatorName, options = {}) {
+    const log = options.log || console.log;
     const udid = await getSimulatorUDID(simulatorName);
     if (!udid) {
         throw new Error(`Simulator "${simulatorName}" not found. Run "xcrun simctl list devices" to see available simulators.`);
     }
-    console.log(`Found simulator "${simulatorName}" with UDID: ${udid}`);
+    log(`Found simulator "${simulatorName}" with UDID: ${udid}`);
     // Check if already booted
     const { stdout } = await execAsync("xcrun simctl list devices --json");
     const data = JSON.parse(stdout);
@@ -95,20 +96,20 @@ async function bootSimulator(simulatorName) {
         for (const device of runtime) {
             if (device.udid === udid) {
                 if (device.state === "Booted") {
-                    console.log(`Simulator "${simulatorName}" is already booted`);
+                    log(`Simulator "${simulatorName}" is already booted`);
                     return udid;
                 }
                 break;
             }
         }
     }
-    console.log(`Booting simulator "${simulatorName}"...`);
+    log(`Booting simulator "${simulatorName}"...`);
     await execAsync(`xcrun simctl boot ${udid}`);
     // Open Simulator app to show the device
     await execAsync("open -a Simulator");
     // Wait for boot to complete
     await waitForSimulatorBoot(udid);
-    console.log(`Simulator "${simulatorName}" is fully booted`);
+    log(`Simulator "${simulatorName}" is fully booted`);
     return udid;
 }
 /**
@@ -142,27 +143,29 @@ async function waitForSimulatorBoot(udid, timeoutMs = 60000) {
  * @param {string} simulatorName - Name of the simulator (e.g., "iPhone 16"), or null to auto-detect
  * @returns {Promise<string>} Simulator ID for use with other functions
  */
-export async function connectToDevice(simulatorName) {
+export async function connectToDevice(simulatorName, options = {}) {
+    const log = options.log || console.log;
+    const errorLog = options.errorLog || console.error;
     emitDesktopDebug("device.connect", "device", {}, { platform: "ios", stage: "start", simulatorName: simulatorName || null });
     // Setup cleanup handlers
     setupAppiumCleanup();
     // Start Appium if not running
-    await startAppium();
+    await startAppium({ log });
     // If no simulator specified, auto-detect
     if (!simulatorName) {
         const found = await findAnySimulator();
         if (!found) {
-            console.error("No iOS Simulators found. Create one with Xcode or run:");
-            console.error("  xcrun simctl create 'iPhone 16' 'com.apple.CoreSimulator.SimDeviceType.iPhone-16'");
+            errorLog("No iOS Simulators found. Create one with Xcode or run:");
+            errorLog("  xcrun simctl create 'iPhone 16' 'com.apple.CoreSimulator.SimDeviceType.iPhone-16'");
             process.exit(1);
         }
         simulatorName = found.name;
-        console.log(`No simulator specified, using: ${simulatorName}`);
+        log(`No simulator specified, using: ${simulatorName}`);
     }
     // Boot simulator
-    const udid = await bootSimulator(simulatorName);
+    const udid = await bootSimulator(simulatorName, { log });
     // Create Appium session
-    console.log("Creating Appium session...");
+    log("Creating Appium session...");
     const session = await appium.createSession({
         platformName: "iOS",
         "appium:automationName": "XCUITest",
@@ -176,7 +179,7 @@ export async function connectToDevice(simulatorName) {
         udid,
         simulatorName,
     };
-    console.log(`Connected to simulator "${simulatorName}" (${udid})`);
+    log(`Connected to simulator "${simulatorName}" (${udid})`);
     emitDesktopDebug("device.connect", "device", {}, {
         platform: "ios",
         stage: "success",
@@ -190,7 +193,8 @@ export async function connectToDevice(simulatorName) {
  * @param {string} simulatorId - The UDID returned from connectToDevice
  * @returns {Promise<object>}
  */
-export async function getDeviceInfo(simulatorId) {
+export async function getDeviceInfo(simulatorId, options = {}) {
+    const log = options.log || console.log;
     await ensureSessionAlive();
     // Get logical window size (points)
     const windowSize = await appium.getWindowSize(activeSession.sessionId);
@@ -203,7 +207,7 @@ export async function getDeviceInfo(simulatorId) {
     const pixelHeight = metadata.height;
     // Calculate the iOS device scale factor (typically 2 or 3)
     const devicePixelRatio = Math.round(pixelWidth / windowSize.width);
-    console.log(`Device pixel ratio: ${devicePixelRatio}x (${pixelWidth}x${pixelHeight} pixels, ${windowSize.width}x${windowSize.height} points)`);
+    log(`Device pixel ratio: ${devicePixelRatio}x (${pixelWidth}x${pixelHeight} pixels, ${windowSize.width}x${windowSize.height} points)`);
     // Store the pixel ratio for coordinate conversion
     activeSession.devicePixelRatio = devicePixelRatio;
     // Use pixel dimensions as the "real" resolution (like Android does)

package/build/src/device/loadmill.js

@@ -8,34 +8,6 @@ function getLoadmillSiteBaseUrl(loadmillClient = null) {
     const rawBaseUrl = loadmillClient?.getBaseUrl?.() || "https://app.loadmill.com/api";
     return rawBaseUrl.replace(/\/api\/?$/, "");
 }
-/**
- * Check if an instruction is a Loadmill command
- * @param {string} userInput - The instruction text
- * @returns {boolean}
- */
-export function isLoadmillInstruction(userInput) {
-    const trimmed = userInput.trim();
-    const lower = trimmed.toLowerCase();
-    return lower.startsWith("loadmill:") || lower.startsWith("loadmill ");
-}
-/**
- * Extract the Loadmill command from an instruction
- * @param {string} userInput - The instruction text
- * @returns {string} - The extracted command
- */
-export function extractLoadmillCommand(userInput) {
-    const trimmed = userInput.trim();
-    const lower = trimmed.toLowerCase();
-    // Handle "loadmill:" or "Loadmill:"
-    if (lower.startsWith("loadmill:")) {
-        return trimmed.substring("loadmill:".length).trim();
-    }
-    // Handle "loadmill " or "Loadmill "
-    if (lower.startsWith("loadmill ")) {
-        return trimmed.substring("loadmill".length).trim();
-    }
-    return trimmed;
-}
 /**
  * Execute a Loadmill instruction and handle the result
  * @param {string} command - The Loadmill command to execute
@@ -163,57 +135,48 @@ export function handleLoadmillSuccess(command, result, context, stepContext = nu
     const payload = result.runId
         ? { loadmillSuiteRunId: result.runId, loadmillCommand: command, loadmillBaseUrl: getLoadmillSiteBaseUrl(loadmillClient) }
         : { loadmillCommand: command, loadmillBaseUrl: getLoadmillSiteBaseUrl(loadmillClient) };
-    if (result.action === "search") {
-        addOutput({ type: 'success', text: `[Loadmill] Found ${result.result.flows.length} flow(s)`, eventType: 'system_message', payload, ...meta });
-        result.result.flows.forEach((flow, i) => {
-            const name = flow.description || flow.name || "Unknown";
-            addOutput({ type: 'info', text: `  ${i + 1}. ${name} (ID: ${flow.id})`, eventType: 'system_message', payload, ...meta });
+    addOutput({ type: 'success', text: `[Loadmill] Flow "${result.flowName}" passed`, eventType: 'system_message', payload, ...meta });
+    if (result.runId) {
+        addOutput({ type: 'info', text: `  Run ID: ${result.runId}`, eventType: 'system_message', payload, ...meta });
+    }
+    const note = result.runtimeParameterContext?.note;
+    if (result.runtimeParameterContext) {
+        emitDesktopDebug("loadmill.runtime_parameters", "execution", {
+            runId: context?.runId,
+            stepId: stepContext?.stepId,
+            instructionIndex: stepContext?.instructionIndex,
+        }, {
+            command,
+            flowName: result.flowName,
+            flowRunId: result.runtimeParameterContext.flowRunId,
+            parameterNames: result.runtimeParameterContext.parameterNames,
+            selectedParameterNames: result.runtimeParameterContext.selectedParameterNames,
+            futureInstructions: result.runtimeParameterContext.futureInstructions,
+            noteAdded: typeof note === "string" && note.trim().length > 0,
         });
     }
-    else {
-        addOutput({ type: 'success', text: `[Loadmill] Flow "${result.flowName}" passed`, eventType: 'system_message', payload, ...meta });
-        if (result.runId) {
-            addOutput({ type: 'info', text: `  Run ID: ${result.runId}`, eventType: 'system_message', payload, ...meta });
-        }
-        const note = result.runtimeParameterContext?.note;
-        if (result.runtimeParameterContext) {
-            emitDesktopDebug("loadmill.runtime_parameters", "execution", {
-                runId: context?.runId,
-                stepId: stepContext?.stepId,
-                instructionIndex: stepContext?.instructionIndex,
-            }, {
-                command,
-                flowName: result.flowName,
-                flowRunId: result.runtimeParameterContext.flowRunId,
-                parameterNames: result.runtimeParameterContext.parameterNames,
-                selectedParameterNames: result.runtimeParameterContext.selectedParameterNames,
-                futureInstructions: result.runtimeParameterContext.futureInstructions,
-                noteAdded: typeof note === "string" && note.trim().length > 0,
-            });
-        }
-        if (typeof note === "string" && note.trim()) {
-            const selectedNames = Array.isArray(result.runtimeParameterContext.selectedParameterNames)
-                ? result.runtimeParameterContext.selectedParameterNames.filter((name) => typeof name === "string" && name.trim())
-                : [];
-            const selectedNamesText = selectedNames.length > 0
-                ? ` (${selectedNames.join(", ")})`
-                : "";
-            context?.session?.addMessage?.("system", note);
-            context?.session?.addToTranscript?.(`[Loadmill Context] ${note}`);
-            addOutput({
-                type: 'info',
-                text: `[Loadmill] Added ${result.runtimeParameterContext.selectedCount} parameter(s)${selectedNamesText} to agent context`,
-                eventType: 'system_message',
-                payload: {
-                    ...payload,
-                    loadmillFlowRunId: result.runtimeParameterContext.flowRunId,
-                    loadmillRuntimeParameterCount: result.runtimeParameterContext.selectedCount,
-                    loadmillRuntimeParameterNames: result.runtimeParameterContext.parameterNames,
-                    loadmillSelectedRuntimeParameterNames: result.runtimeParameterContext.selectedParameterNames,
-                    loadmillParameterSelectionFutureInstructions: result.runtimeParameterContext.futureInstructions,
-                },
-                ...meta
-            });
-        }
+    if (typeof note === "string" && note.trim()) {
+        const selectedNames = Array.isArray(result.runtimeParameterContext.selectedParameterNames)
+            ? result.runtimeParameterContext.selectedParameterNames.filter((name) => typeof name === "string" && name.trim())
+            : [];
+        const selectedNamesText = selectedNames.length > 0
+            ? ` (${selectedNames.join(", ")})`
+            : "";
+        context?.session?.addMessage?.("system", note);
+        context?.session?.addToTranscript?.(`[Loadmill Context] ${note}`);
+        addOutput({
+            type: 'info',
+            text: `[Loadmill] Added ${result.runtimeParameterContext.selectedCount} parameter(s)${selectedNamesText} to agent context`,
+            eventType: 'system_message',
+            payload: {
+                ...payload,
+                loadmillFlowRunId: result.runtimeParameterContext.flowRunId,
+                loadmillRuntimeParameterCount: result.runtimeParameterContext.selectedCount,
+                loadmillRuntimeParameterNames: result.runtimeParameterContext.parameterNames,
+                loadmillSelectedRuntimeParameterNames: result.runtimeParameterContext.selectedParameterNames,
+                loadmillParameterSelectionFutureInstructions: result.runtimeParameterContext.futureInstructions,
+            },
+            ...meta
+        });
     }
 }

package/build/src/device/openai.js

@@ -66,10 +66,22 @@ const navigateTool = {
         additionalProperties: false,
     },
 };
+const closeCurrentTabTool = {
+    type: "function",
+    name: "close_current_tab",
+    description: "Close the current child tab and return to the previous browser tab. Use this only when the current screen is a temporary tab or popup detour.",
+    strict: true,
+    parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        additionalProperties: false,
+    },
+};
 const loadmillTool = {
     type: "function",
     name: "loadmill",
-    description: "Run an explicit Loadmill command. Use this only when the instruction explicitly mentions Loadmill and asks for a Loadmill-specific action.",
+    description: "Search Loadmill for the requested flow, run the best match, and wait for completion. Use this when the instruction explicitly mentions running or using a Loadmill flow.",
     strict: true,
     parameters: {
         type: "object",
@@ -123,6 +135,9 @@ export function buildFunctionTools({ aimAssistMode = DEFAULT_AIM_ASSIST_MODE, to
     if (toolCapabilities.navigate) {
         tools.push(navigateTool);
     }
+    if (toolCapabilities.closeCurrentTab) {
+        tools.push(closeCurrentTabTool);
+    }
     if (toolCapabilities.loadmill) {
         tools.push(loadmillTool);
     }

package/build/src/integrations/loadmill/executor.js

@@ -6,7 +6,27 @@ import { interpretLoadmillCommand, selectBestFlow } from "./interpreter.js";
 import { extractLoadmillRuntimeParameters, renderLoadmillParameterContextNote, selectLoadmillParameterCandidates, } from "./parameters.js";
 import { logger } from "../../utils/logger.js";
 const POLL_INTERVAL_MS = 5000; // 5 seconds
-const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
+function readTimeoutMsFromEnv() {
+    const raw = process.env.LOADMILL_RUN_TIMEOUT_MS;
+    if (!raw) {
+        return DEFAULT_TIMEOUT_MS;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+        return parsed;
+    }
+    logger.debug("Ignoring invalid LOADMILL_RUN_TIMEOUT_MS value", { value: raw });
+    return DEFAULT_TIMEOUT_MS;
+}
+function formatDuration(ms) {
+    const totalSeconds = Math.ceil(ms / 1000);
+    if (totalSeconds >= 60 && totalSeconds % 60 === 0) {
+        const minutes = totalSeconds / 60;
+        return `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+    }
+    return `${totalSeconds} ${totalSeconds === 1 ? "second" : "seconds"}`;
+}
 function buildParameterSelectionMessages({ command, flowName, futureInstructions, parameters, }) {
     const parameterList = parameters
         .map((param) => `- ${param.key}`)
@@ -127,9 +147,10 @@ function sleep(ms) {
  * @param {Function} onStatusUpdate - Callback for status updates
  * @returns {Promise<Object>} - Final run status
  */
-async function pollForCompletion(runId, loadmillClient, onStatusUpdate = () => { }) {
-    const startTime = Date.now();
-    while (Date.now() - startTime < TIMEOUT_MS) {
+async function pollForCompletion(runId, loadmillClient, options = {}) {
+    const { onStatusUpdate = () => { }, timeoutMs = readTimeoutMsFromEnv(), pollIntervalMs = POLL_INTERVAL_MS, now = Date.now, sleepFn = sleep, } = options;
+    const startTime = now();
+    while (now() - startTime < timeoutMs) {
         try {
             const status = await loadmillClient.getTestRunStatus(runId);
             onStatusUpdate(status);
@@ -158,7 +179,7 @@ async function pollForCompletion(runId, loadmillClient, onStatusUpdate = () => {
                 return { success: false, status: "stopped", result: status, error: "Test flow was stopped" };
             }
             // Still running, wait and poll again
-            await sleep(POLL_INTERVAL_MS);
+            await sleepFn(pollIntervalMs);
         }
         catch (err) {
             logger.error("Error polling Loadmill run status", { runId, error: err.message });
@@ -166,7 +187,7 @@ async function pollForCompletion(runId, loadmillClient, onStatusUpdate = () => {
         }
     }
     // Timeout
-    return { success: false, status: "timeout", error: "Test run timed out after 5 minutes" };
+    return { success: false, status: "timeout", error: `Test run timed out after ${formatDuration(timeoutMs)}` };
 }
 /**
  * Execute a Loadmill command from natural language input
@@ -176,7 +197,7 @@ async function pollForCompletion(runId, loadmillClient, onStatusUpdate = () => {
  * @returns {Promise<{success: boolean, error?: string, result?: Object}>}
  */
 export async function executeLoadmillCommand(userInput, options = {}) {
-    const { onProgress = () => { }, loadmillClient = createLoadmillApiClient(), openAiClient = null, futureInstructions = [], } = options;
+    const { onProgress = () => { }, loadmillClient = createLoadmillApiClient(), openAiClient = null, futureInstructions = [], pollTimeoutMs, pollIntervalMs, now, sleepFn, } = options;
     // Check for API token
     if (!loadmillClient.getApiToken()) {
         return {
@@ -214,18 +235,6 @@ export async function executeLoadmillCommand(userInput, options = {}) {
                 error: "Could not select a matching flow"
             };
         }
-        // If action is "search", just return the results
-        if (interpreted.action === "search") {
-            return {
-                success: true,
-                action: "search",
-                result: {
-                    flows,
-                    selectedFlow,
-                    confidence
-                }
-            };
-        }
         // Step 4: Run the flow
         const flowName = selectedFlow.description || selectedFlow.name || "Unknown";
         onProgress({
@@ -244,8 +253,14 @@ export async function executeLoadmillCommand(userInput, options = {}) {
         }
         // Step 5: Poll for completion
         onProgress({ step: "polling", message: `Test started (ID: ${runId}). Waiting for completion...`, runId });
-        const finalResult = await pollForCompletion(runId, loadmillClient, (status) => {
-            onProgress({ step: "polling", message: `Status: ${status.status}...`, runId });
+        const finalResult = await pollForCompletion(runId, loadmillClient, {
+            timeoutMs: pollTimeoutMs,
+            pollIntervalMs,
+            now,
+            sleepFn,
+            onStatusUpdate: (status) => {
+                onProgress({ step: "polling", message: `Status: ${status.status}...`, runId });
+            },
         });
         const runtimeParameterContext = finalResult.success
             ? await buildRuntimeParameterContext({

package/build/src/integrations/loadmill/interpreter.js

@@ -5,7 +5,7 @@ import { buildLoadmillCommandInterpretationMessages, buildLoadmillFlowSelectionM
 /**
  * Interpret a natural language Loadmill command into structured data
  * @param {string} userInput - Natural language command
- * @returns {Promise<{searchQuery: string, parameters: Object, action: 'run'|'search'}>}
+ * @returns {Promise<{searchQuery: string, parameters: Object}>}
  */
 export async function interpretLoadmillCommand(userInput, { client }) {
     const response = await client.chat.completions.create({
@@ -18,7 +18,6 @@ export async function interpretLoadmillCommand(userInput, { client }) {
     return {
         searchQuery: parsed.searchQuery || userInput,
         parameters: parsed.parameters || {},
-        action: parsed.action || "run"
     };
 }
 /**

package/build/src/modes/design-mode-ink.js

@@ -39,6 +39,7 @@ export class DesignModeInk {
         this.engine.toolCapabilities = {
             assert: true,
             navigate: this.session?.deviceInfo?.platform === "browser",
+            closeCurrentTab: this.session?.deviceInfo?.platform === "browser",
             loadmill: false,
             testDesignComplete: true,
         };

package/build/src/modes/design-mode.js

@@ -36,6 +36,7 @@ export class DesignMode {
         this.engine.toolCapabilities = {
             assert: true,
             navigate: this.session?.deviceInfo?.platform === "browser",
+            closeCurrentTab: this.session?.deviceInfo?.platform === "browser",
             loadmill: false,
             testDesignComplete: true,
         };

package/build/src/modes/execution-mode.js

@@ -43,6 +43,7 @@ export class ExecutionMode {
         this.engine.toolCapabilities = {
             assert: true,
             navigate: this.isBrowserSession,
+            closeCurrentTab: this.isBrowserSession,
             loadmill: true,
         };
         this.engine.baseSystemPrompt = this.initialSystemText;

package/build/src/prompts/base.js

@@ -141,6 +141,7 @@ function buildBrowserBaseSystemPrompt(deviceInfo, options = {}) {
   Browser-Specific Notes:
   - You are operating a desktop browser, not a phone UI
   - Use the \`navigate\` tool for direct URL changes when available; do not try to reach the browser address bar or fake URL entry with keyboard shortcuts
+  - Clicks or page actions that open a new tab automatically switch control to that tab; closing the current tab returns control to the previous tab
   - ESC dismisses many overlays and dialogs
   - Cookie or consent banners may block the main task and may need dismissal first
   - Vertical scrolling is the default way to discover content below the fold

package/build/src/prompts/execution.js

@@ -44,7 +44,7 @@ Your process:
    - Before calling \`assert\`, make sure the current screen contains the evidence needed to validate the condition. If needed, perform only minimal preparation first, such as taking a screenshot, waiting briefly, closing the keyboard, scrolling within the relevant view, or opening the relevant menu.
    - Once you call \`assert\`, validation is read-only. The assertion tool will not click, type, wait, scroll, request screenshots, or change the device state.
    - Use \`navigate\` for direct browser navigation instead of trying to manipulate the address bar
-   - Use \`loadmill\` only when the instruction explicitly references the word "loadmill"
+   - Use the \`loadmill\` tool whenever the instruction explicitly references running or using a Loadmill flow. Pass the requested flow name/intent and parameters as the command; the tool will search Loadmill, select the best matching flow, run it, and wait for completion. Do not handle Loadmill by typing in the app UI.
 3. Execute the required actions
 4. Before tapping a mutating action, dismiss the keyboard if it is open and not needed
 5. After a mutating action, inspect the resulting screen for success cues such as cleared fields, reset buttons, changed status, refreshed content, or navigation

package/build/src/prompts/loadmill.js

@@ -7,25 +7,21 @@ export function buildLoadmillCommandInterpretationMessages(userInput) {
 Extract the following from the user's input:
 1. searchQuery: The flow name or description to search for (required). FIX any obvious typos or misspellings.
 2. parameters: Any key=value pairs mentioned (as an object)
-3. action: Either "run" (if user wants to execute) or "search" (if user just wants to find flows)
 
 Output JSON only, no markdown or explanation.
 
 Examples:
 Input: "run the checkout flow with user=test123"
-Output: {"searchQuery": "checkout flow", "parameters": {"user": "test123"}, "action": "run"}
-
-Input: "search for login test"
-Output: {"searchQuery": "login test", "parameters": {}, "action": "search"}
+Output: {"searchQuery": "checkout flow", "parameters": {"user": "test123"}}
 
 Input: "run user authentication with email=test@example.com password=secret123"
-Output: {"searchQuery": "user authentication", "parameters": {"email": "test@example.com", "password": "secret123"}, "action": "run"}
+Output: {"searchQuery": "user authentication", "parameters": {"email": "test@example.com", "password": "secret123"}}
 
 Input: "execute payment flow"
-Output: {"searchQuery": "payment flow", "parameters": {}, "action": "run"}
+Output: {"searchQuery": "payment flow", "parameters": {}}
 
 Input: "create a transction with amount=200"
-Output: {"searchQuery": "transaction", "parameters": {"amount": "200"}, "action": "run"}`
+Output: {"searchQuery": "transaction", "parameters": {"amount": "200"}}`
         },
         {
             role: "user",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.13.0",
+  "version": "2.15.1",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",
@@ -24,6 +24,9 @@
     "build": "tsc",
     "clean": "rm -rf build",
     "typecheck": "tsc --noEmit",
+    "typecheck:desktop": "npm --prefix desktop-app run typecheck",
+    "typecheck:all": "npm run typecheck && npm run typecheck:desktop",
+    "prepare": "node scripts/install-git-hooks.mjs",
     "prepublishOnly": "npm run build"
   },
   "repository": {