@loadmill/droid-cua 2.14.0 → 2.16.0

package/README.md

@@ -46,9 +46,9 @@ Under the hood, `droid-cua` uses an AI agent to explore your app, execute action
 
 Open the desktop app and choose the platform you want to test.
 
-**3. Add your credentials**
+**3. Choose your AI provider**
 
-Set your OpenAI API key in the app Settings screen, or log in with your Loadmill account.
+In Settings, choose the CUA model you want to run. `Loadmill - Smart` uses your Loadmill sign-in and usage tracking. The OpenAI models use your own OpenAI API key.
 
 **4. Connect a target device**
 
@@ -75,7 +75,7 @@ Desktop app support:
 ## Requirements
 
 **All platforms:**
-- OpenAI API key
+- Loadmill sign-in for `Loadmill - Smart`, or an OpenAI API key for the OpenAI models
 
 **Android:**
 - Android Debug Bridge (ADB)
@@ -142,6 +142,9 @@ droid-cua
 # Headless Android run
 droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua
 
+# Headless Android folder run
+droid-cua --avd adb:emulator-5554 --instructions tests
+
 # Headless iOS simulator run
 droid-cua --platform ios --avd "iPhone 16" --instructions tests/login.dcua
 

package/build/index.js

@@ -3,14 +3,12 @@ import dotenv from "dotenv";
 import path from "path";
 import { mkdir } from "fs/promises";
 import { connectToDevice, disconnect as disconnectDevice, getDeviceInfo } from "./src/device/connection.js";
-import { connectToBrowser, getBrowserInfo, getCurrentPlatform as getBrowserCurrentPlatform, getScreenshotAsBase64 as getBrowserScreenshotAsBase64, } from "./src/browser/connection.js";
-import { handleModelAction as handleBrowserModelAction } from "./src/browser/actions.js";
+import { connectToBrowser, getBrowserInfo, } from "./src/browser/connection.js";
 import { normalizeBrowserInfoForSession } from "./src/browser/normalize.js";
 import { Session } from "./src/core/session.js";
 import { ExecutionEngine } from "./src/core/execution-engine.js";
-import { buildBaseSystemPrompt, buildExecutionModePrompt } from "./src/core/prompts.js";
+import { buildBaseSystemPrompt } from "./src/core/prompts.js";
 import { startInkShell } from "./src/cli/ink-shell.js";
-import { ExecutionMode } from "./src/modes/execution-mode.js";
 import { createOpenAiExecutor } from "./src/device/openai.js";
 import { logger } from "./src/utils/logger.js";
 import { selectDevice } from "./src/cli/device-selector.js";
@@ -18,10 +16,10 @@ import { resolveExecutionAppContext } from "./src/core/app-context.js";
 import { createRunContext, resolveRuntimeConfigFromEnv, resolveRuntimeCredentialsFromEnv, } from "./src/core/runtime-config.js";
 import { resolveHeadlessExecutionConfig } from "./src/cli/headless-execution-config.js";
 import { resolveHeadlessTarget } from "./src/cli/headless-target.js";
-import { printCliOutput } from "./src/utils/console-output.js";
-import { emitDesktopDebug } from "./src/utils/desktop-debug.js";
 import { createHeadlessDebugArtifacts } from "./src/cli/headless-debug.js";
-import { loadHeadlessInstructions, resolveHeadlessInstructionsPath } from "./src/cli/headless-instructions.js";
+import { loadHeadlessInstructions } from "./src/cli/headless-instructions.js";
+import { listHeadlessInstructionFiles, resolveHeadlessInstructionsTarget } from "./src/cli/headless-instruction-target.js";
+import { runHeadlessInstructionRuns } from "./src/cli/headless-runner.js";
 import { resolveLambdaTestCredentials, uploadLambdaTestCliApp } from "./src/cli/lambdatest-app-upload.js";
 import { createLoadmillApiClient } from "./src/integrations/loadmill/client.js";
 import { getCloudProviderAdapter } from "./src/device/cloud/registry.js";
@@ -31,6 +29,7 @@ const targetConfig = resolveHeadlessTarget(args);
 let avdName = targetConfig.avdName;
 let platform = targetConfig.platform || null; // 'ios' or 'android'
 const recordScreenshots = args["record"] || false;
+const startupUrl = typeof args.url === "string" && args.url.trim().length > 0 ? args.url.trim() : null;
 const instructionsFile = args.instructions || args.i || null;
 const appContextPath = typeof args.context === "string" ? args.context : null;
 const debugMode = args["debug"] || false;
@@ -109,13 +108,30 @@ async function main() {
         throw new Error("--device-source lambdatest is only supported with --instructions headless execution.");
     }
     let preloadedHeadlessConfig = null;
-    let preloadedHeadlessInstructions = null;
-    let resolvedInstructionsFile = instructionsFile;
+    let preloadedHeadlessTarget = null;
+    let headlessInstructionRuns = [];
     let preloadedAppContext = null;
     if (isHeadlessInstructionsRun) {
         preloadedHeadlessConfig = await resolveHeadlessExecutionConfig(args);
-        resolvedInstructionsFile = await resolveHeadlessInstructionsPath(instructionsFile);
-        preloadedHeadlessInstructions = await loadHeadlessInstructions(resolvedInstructionsFile);
+        preloadedHeadlessTarget = await resolveHeadlessInstructionsTarget(instructionsFile);
+        if (preloadedHeadlessTarget.type === "directory") {
+            const files = await listHeadlessInstructionFiles(preloadedHeadlessTarget.path);
+            if (files.length === 0) {
+                throw new Error(`No .dcua tests found in instructions directory ${preloadedHeadlessTarget.path}.`);
+            }
+            headlessInstructionRuns = files.map((file) => ({
+                testPath: file.path,
+                testName: file.filename,
+                instructions: null
+            }));
+        }
+        else {
+            headlessInstructionRuns = [{
+                    testPath: preloadedHeadlessTarget.path,
+                    testName: path.basename(preloadedHeadlessTarget.path),
+                    instructions: await loadHeadlessInstructions(preloadedHeadlessTarget.path)
+                }];
+        }
         preloadedAppContext = await resolveExecutionAppContext({
             enabled: preloadedHeadlessConfig.appContextEnabled,
             contextPath: preloadedHeadlessConfig.appContextPath,
@@ -134,6 +150,7 @@ async function main() {
     let deviceInfo;
     if (isBrowserTarget) {
         targetId = await connectToBrowser({
+            url: startupUrl,
             headless: true,
             browserFamily: targetConfig.browserFamily,
             sessionMode: targetConfig.sessionMode
@@ -198,28 +215,13 @@ async function main() {
     session.setSystemPrompt(initialSystemText);
     // If --instructions provided, run in headless mode
     if (instructionsFile) {
-        const runId = `run-${Date.now()}`;
-        const testName = path.basename(resolvedInstructionsFile);
-        let instructions = [];
-        let executionMode = null;
         let exitCode = null;
         try {
             const headlessConfig = preloadedHeadlessConfig;
-            await headlessDebug.startExecutionSession(runId, {
-                testName,
-                platform: deviceInfo.platform,
-                deviceName: deviceInfo.device_name,
-                aimAssistMode: headlessConfig.aimAssistMode
-            });
-            const currentLogFilePath = await headlessDebug.getCurrentLogFilePath();
-            if (currentLogFilePath) {
-                console.log(`Debug logging enabled: ${currentLogFilePath}`);
-            }
-            console.log(`\nRunning test from: ${resolvedInstructionsFile}\n`);
-            instructions = preloadedHeadlessInstructions;
             const appContext = preloadedAppContext;
             const appContextText = appContext.text;
             const runtimeContext = createCliRuntimeContext({
+                llmProviderMode: headlessConfig.llmProviderMode,
                 cuaModel: headlessConfig.cuaModel,
                 promptCustomizations: headlessConfig.promptCustomizations,
                 contextOptimizationEnabled: headlessConfig.contextOptimizationEnabled,
@@ -232,130 +234,23 @@ async function main() {
                     message: appContext.message,
                 },
             });
+            console.log(`Using AI provider: ${runtimeContext.config.llmProviderMode}`);
             console.log(`Using CUA model: ${runtimeContext.config.cuaModel}`);
-            if (appContext.status === "loaded" || appContext.status === "empty") {
-                emitDesktopDebug("app_context.loaded", "execution", { runId }, {
-                    source: "cli_context_flag",
-                    contextPath: appContext.contextPath,
-                    status: appContext.status,
-                    text: appContextText
-                });
-                if (appContextText) {
-                    console.log(`Using app context from: ${appContext.contextPath}`);
-                }
-            }
-            else if (appContext.status === "failed") {
-                emitDesktopDebug("app_context.loaded", "execution", { runId }, {
-                    source: "cli_context_flag",
-                    contextPath: appContext.contextPath,
-                    status: "failed",
-                    message: appContext.message
-                });
-                console.warn(`Warning: could not load app context from ${appContext.contextPath}. Running without it.`);
-            }
-            else {
-                emitDesktopDebug("app_context.loaded", "execution", { runId }, {
-                    source: "cli_context_flag",
-                    contextPath: appContext.contextPath,
-                    status: appContext.status
-                });
-            }
-            const executionPrompt = buildExecutionModePrompt(deviceInfo, headlessConfig.promptCustomizations, appContextText, { aimAssistMode: headlessConfig.aimAssistMode });
-            session.setSystemPrompt(executionPrompt);
-            const screenshotRecorder = headlessDebug.createExecutionScreenshotRecorder({
-                runId,
+            const result = await runHeadlessInstructionRuns({
+                runs: headlessInstructionRuns,
+                instructionsTarget: preloadedHeadlessTarget,
+                session,
+                deviceInfo,
+                headlessConfig,
+                appContext,
+                runtimeContext,
+                headlessDebug,
                 recordScreenshots,
-                screenshotDir
-            });
-            const executionEngineOptions = {
-                toolCapabilities: {
-                    assert: true,
-                    navigate: isBrowserTarget,
-                    loadmill: true,
-                },
-                baseSystemPrompt: executionPrompt,
-                isHeadlessMode: true,
-            };
-            const engineOptions = screenshotRecorder
-                ? {
-                    recordScreenshots: true,
-                    screenshotRecorder,
-                    stepDelayMs: runtimeContext.config.stepDelayMs,
-                    sendCUARequest: (requestArgs) => runtimeContext.openAi.sendCUARequest({
-                        ...requestArgs,
-                        aimAssistMode: headlessConfig.aimAssistMode,
-                    }),
-                    reviseTestScript: runtimeContext.openAi.reviseTestScript,
-                    ...executionEngineOptions,
-                }
-                : {
-                    recordScreenshots,
-                    screenshotDir,
-                    stepDelayMs: runtimeContext.config.stepDelayMs,
-                    sendCUARequest: (requestArgs) => runtimeContext.openAi.sendCUARequest({
-                        ...requestArgs,
-                        aimAssistMode: headlessConfig.aimAssistMode,
-                    }),
-                    reviseTestScript: runtimeContext.openAi.reviseTestScript,
-                    ...executionEngineOptions,
-                };
-            if (isBrowserTarget) {
-                engineOptions.getScreenshotAsBase64 = (browserSessionId, browserInfo) => getBrowserScreenshotAsBase64(browserSessionId, browserInfo);
-                engineOptions.handleModelAction = (browserSessionId, action, scale, actionContext) => handleBrowserModelAction(browserSessionId, action, scale, actionContext);
-                engineOptions.getCurrentPlatform = getBrowserCurrentPlatform;
-            }
-            else if (isLambdaTestTarget) {
-                engineOptions.connectToDevice = async () => {
-                    throw new Error("LambdaTest cloud session disconnected; automatic CLI reconnect is not supported yet.");
-                };
-            }
-            const engine = new ExecutionEngine(session, engineOptions);
-            executionMode = new ExecutionMode(session, engine, instructions, true);
-            const result = await executionMode.execute({
-                runId,
-                addOutput: printCliOutput,
-                openAiClient: runtimeContext.openAiClient,
-                loadmillClient: runtimeContext.loadmillClient,
-                runtimeCredentials: runtimeContext.credentials,
-            });
-            const stats = executionMode.stats || {};
-            const durationMs = stats.startTime ? Math.max(0, Date.now() - stats.startTime) : 0;
-            await headlessDebug.endExecutionSession(runId, {
-                success: Boolean(result.success),
-                error: result.error ?? null,
-                durationMs,
-                instructionsTotal: instructions.length,
-                instructionsCompleted: stats.instructionsCompleted ?? 0,
-                actionsTotal: stats.actionCount ?? 0,
-                assertionsPassed: stats.assertionsPassed ?? 0,
-                assertionsFailed: stats.assertionsFailed ?? 0,
-                retries: stats.retryCount ?? 0
+                screenshotDir,
+                isBrowserTarget,
+                isLambdaTestTarget
             });
-            if (!result.success) {
-                console.error(`\nTest failed: ${result.error}`);
-            }
-            exitCode = result.success ? 0 : 1;
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : "Failed to start execution.";
-            const stats = executionMode?.stats || {};
-            const durationMs = stats.startTime ? Math.max(0, Date.now() - stats.startTime) : 0;
-            await headlessDebug.endExecutionSession(runId, {
-                success: false,
-                error: message,
-                ...(stats.startTime
-                    ? {
-                        durationMs,
-                        instructionsTotal: instructions.length,
-                        instructionsCompleted: stats.instructionsCompleted ?? 0,
-                        actionsTotal: stats.actionCount ?? 0,
-                        assertionsPassed: stats.assertionsPassed ?? 0,
-                        assertionsFailed: stats.assertionsFailed ?? 0,
-                        retries: stats.retryCount ?? 0
-                    }
-                    : { reason: "start_failed" })
-            });
-            throw error;
+            exitCode = result.exitCode;
         }
         finally {
             if (lambdaTestSessionConnected) {

package/build/src/cli/headless-execution-config.js

@@ -2,7 +2,8 @@ import path from "path";
 import { readFile } from "fs/promises";
 import { DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD, MAX_CONTEXT_OPTIMIZATION_THRESHOLD, MIN_CONTEXT_OPTIMIZATION_THRESHOLD, } from "../core/context-optimization.js";
 import { AIM_ASSIST_MODES, DEFAULT_AIM_ASSIST_MODE } from "../core/aim-assist.js";
-import { CUA_MODELS, isValidCuaModel, resolveCuaModel } from "../core/cua-models.js";
+import { CUA_MODELS, DEFAULT_OPENAI_CUA_MODEL, isOpenAiCuaModel, isValidCuaModel, resolveCuaModel } from "../core/cua-models.js";
+import { LLM_PROVIDER_MODES, isValidLlmProviderMode, resolveLlmProviderMode } from "../core/runtime-config.js";
 function createEmptyPromptCustomizations() {
     return {
         basePromptInstructions: "",
@@ -30,8 +31,25 @@ function validateAimAssistMode(value, label) {
     }
     return value;
 }
+function validateLlmProviderMode(value, label) {
+    if (typeof value !== "string" || !isValidLlmProviderMode(value)) {
+        throw new Error(`${label} must be one of: ${LLM_PROVIDER_MODES.join(", ")}.`);
+    }
+    return value;
+}
 function readEnvDefaultCuaModel() {
-    return resolveCuaModel(process.env.OPENAI_CUA_MODEL);
+    const envValue = process.env.OPENAI_CUA_MODEL;
+    // OPENAI_CUA_MODEL only selects OpenAI models. If it is set but not a valid
+    // OpenAI model, stay on the OpenAI default rather than crossing over to the
+    // global (Loadmill) default.
+    if (typeof envValue === "string" && envValue.trim()) {
+        const trimmed = envValue.trim();
+        return isOpenAiCuaModel(trimmed) ? trimmed : DEFAULT_OPENAI_CUA_MODEL;
+    }
+    return resolveCuaModel(envValue);
+}
+function readEnvDefaultLlmProviderMode() {
+    return resolveLlmProviderMode(process.env.DROID_CUA_LLM_PROVIDER);
 }
 function parseContextOptimizationThreshold(rawValue, label) {
     const numericValue = (() => {
@@ -107,6 +125,7 @@ async function loadConfigFromFile(configPath) {
     const configDir = path.dirname(absoluteConfigPath);
     const normalized = {
         configPath: absoluteConfigPath,
+        llmProviderMode: undefined,
         cuaModel: undefined,
         aimAssistMode: undefined,
         promptCustomizations: createEmptyPromptCustomizations(),
@@ -115,6 +134,9 @@ async function loadConfigFromFile(configPath) {
         contextOptimizationEnabled: undefined,
         contextOptimizationThreshold: undefined,
     };
+    if ("llmProviderMode" in rawConfig) {
+        normalized.llmProviderMode = validateLlmProviderMode(rawConfig.llmProviderMode, "config.llmProviderMode");
+    }
     if ("cuaModel" in rawConfig) {
         normalized.cuaModel = validateCuaModel(rawConfig.cuaModel, "config.cuaModel");
     }
@@ -174,6 +196,7 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     };
     const resolved = {
         configPath: fileConfig?.configPath || null,
+        llmProviderMode: fileConfig?.llmProviderMode || readEnvDefaultLlmProviderMode(),
         cuaModel: fileConfig?.cuaModel || readEnvDefaultCuaModel(),
         aimAssistMode: fileConfig?.aimAssistMode || DEFAULT_AIM_ASSIST_MODE,
         promptCustomizations,
@@ -182,6 +205,9 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         contextOptimizationEnabled: fileConfig?.contextOptimizationEnabled ?? true,
         contextOptimizationThreshold: fileConfig?.contextOptimizationThreshold ?? DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD,
     };
+    if (typeof args["llm-provider"] === "string") {
+        resolved.llmProviderMode = validateLlmProviderMode(args["llm-provider"], "--llm-provider");
+    }
     if (typeof args["cua-model"] === "string") {
         resolved.cuaModel = validateCuaModel(args["cua-model"], "--cua-model");
     }

package/build/src/cli/headless-instruction-target.js

@@ -0,0 +1,64 @@
+import path from "path";
+import { readdir, stat } from "fs/promises";
+import { resolveHeadlessInstructionsPath } from "./headless-instructions.js";
+const testNameCollator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
+const filenameCollator = new Intl.Collator(undefined, { sensitivity: "base" });
+function compareInstructionFiles(left, right) {
+    const byName = testNameCollator.compare(left.name, right.name);
+    if (byName !== 0) {
+        return byName;
+    }
+    const byModified = right.modified.localeCompare(left.modified);
+    if (byModified !== 0) {
+        return byModified;
+    }
+    return filenameCollator.compare(left.filename, right.filename);
+}
+/**
+ * Resolve a CLI instructions target as either a single .dcua file or a directory
+ * containing .dcua files.
+ *
+ * @param {string} instructionsPath
+ * @returns {Promise<{type: 'file'|'directory', path: string}>}
+ */
+export async function resolveHeadlessInstructionsTarget(instructionsPath) {
+    const resolvedPath = await resolveHeadlessInstructionsPath(instructionsPath);
+    try {
+        const pathStat = await stat(resolvedPath);
+        if (pathStat.isDirectory()) {
+            return { type: "directory", path: resolvedPath };
+        }
+    }
+    catch {
+        // Missing paths stay as file targets so the existing read error remains clear.
+    }
+    return { type: "file", path: resolvedPath };
+}
+/**
+ * List runnable .dcua files from a headless instructions directory.
+ *
+ * @param {string} instructionsDirectory
+ * @returns {Promise<Array<{name: string, filename: string, path: string, modified: string}>>}
+ */
+export async function listHeadlessInstructionFiles(instructionsDirectory) {
+    let entries;
+    try {
+        entries = await readdir(instructionsDirectory);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown directory read error.";
+        throw new Error(`Could not read instructions directory ${instructionsDirectory}: ${message}`);
+    }
+    const dcuaFiles = entries.filter((entry) => entry.toLowerCase().endsWith(".dcua"));
+    const tests = await Promise.all(dcuaFiles.map(async (filename) => {
+        const fullPath = path.join(instructionsDirectory, filename);
+        const fileStat = await stat(fullPath);
+        return {
+            name: filename.replace(/\.dcua$/i, ""),
+            filename,
+            path: fullPath,
+            modified: fileStat.mtime.toISOString()
+        };
+    }));
+    return tests.sort(compareInstructionFiles);
+}

package/build/src/cli/headless-runner.js

@@ -0,0 +1,245 @@
+import path from "path";
+import { mkdir } from "fs/promises";
+import { getCurrentPlatform as getBrowserCurrentPlatform, getScreenshotAsBase64 as getBrowserScreenshotAsBase64, } from "../browser/connection.js";
+import { handleModelAction as handleBrowserModelAction } from "../browser/actions.js";
+import { ExecutionEngine } from "../core/execution-engine.js";
+import { buildExecutionModePrompt } from "../core/prompts.js";
+import { ExecutionMode } from "../modes/execution-mode.js";
+import { printCliOutput } from "../utils/console-output.js";
+import { emitDesktopDebug } from "../utils/desktop-debug.js";
+import { loadHeadlessInstructions } from "./headless-instructions.js";
+function sanitizePathSegment(value) {
+    return String(value || "test")
+        .replace(/\.dcua$/i, "")
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^[-_.]+|[-_.]+$/g, "") || "test";
+}
+function createHeadlessRunId(index = 0) {
+    const suffix = index > 0 ? `-${index + 1}` : "";
+    return `run-${Date.now()}${suffix}`;
+}
+function getRecordScreenshotDirForTest(baseScreenshotDir, testName, isBatchRun) {
+    if (!baseScreenshotDir || !isBatchRun) {
+        return baseScreenshotDir;
+    }
+    return path.join(baseScreenshotDir, sanitizePathSegment(testName));
+}
+function emitCliAppContextDebug(runId, appContext, appContextText) {
+    if (appContext.status === "loaded" || appContext.status === "empty") {
+        emitDesktopDebug("app_context.loaded", "execution", { runId }, {
+            source: "cli_context_flag",
+            contextPath: appContext.contextPath,
+            status: appContext.status,
+            text: appContextText
+        });
+        if (appContextText) {
+            console.log(`Using app context from: ${appContext.contextPath}`);
+        }
+    }
+    else if (appContext.status === "failed") {
+        emitDesktopDebug("app_context.loaded", "execution", { runId }, {
+            source: "cli_context_flag",
+            contextPath: appContext.contextPath,
+            status: "failed",
+            message: appContext.message
+        });
+        console.warn(`Warning: could not load app context from ${appContext.contextPath}. Running without it.`);
+    }
+    else {
+        emitDesktopDebug("app_context.loaded", "execution", { runId }, {
+            source: "cli_context_flag",
+            contextPath: appContext.contextPath,
+            status: appContext.status
+        });
+    }
+}
+function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionPrompt, screenshotRecorder, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
+    const executionEngineOptions = {
+        toolCapabilities: {
+            assert: true,
+            navigate: isBrowserTarget,
+            loadmill: true,
+        },
+        baseSystemPrompt: executionPrompt,
+        isHeadlessMode: true,
+    };
+    const engineOptions = screenshotRecorder
+        ? {
+            recordScreenshots: true,
+            screenshotRecorder,
+            stepDelayMs: runtimeContext.config.stepDelayMs,
+            sendCUARequest: (requestArgs) => runtimeContext.openAi.sendCUARequest({
+                ...requestArgs,
+                aimAssistMode: headlessConfig.aimAssistMode,
+            }),
+            reviseTestScript: runtimeContext.openAi.reviseTestScript,
+            ...executionEngineOptions,
+        }
+        : {
+            recordScreenshots,
+            screenshotDir,
+            stepDelayMs: runtimeContext.config.stepDelayMs,
+            sendCUARequest: (requestArgs) => runtimeContext.openAi.sendCUARequest({
+                ...requestArgs,
+                aimAssistMode: headlessConfig.aimAssistMode,
+            }),
+            reviseTestScript: runtimeContext.openAi.reviseTestScript,
+            ...executionEngineOptions,
+        };
+    if (isBrowserTarget) {
+        engineOptions.getScreenshotAsBase64 = (browserSessionId, browserInfo) => getBrowserScreenshotAsBase64(browserSessionId, browserInfo);
+        engineOptions.handleModelAction = (browserSessionId, action, scale, actionContext) => handleBrowserModelAction(browserSessionId, action, scale, actionContext);
+        engineOptions.getCurrentPlatform = getBrowserCurrentPlatform;
+    }
+    else if (isLambdaTestTarget) {
+        engineOptions.connectToDevice = async () => {
+            throw new Error("LambdaTest cloud session disconnected; automatic CLI reconnect is not supported yet.");
+        };
+    }
+    return engineOptions;
+}
+async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
+    let executionMode = null;
+    try {
+        await headlessDebug.startExecutionSession(runId, {
+            testName,
+            platform: deviceInfo.platform,
+            deviceName: deviceInfo.device_name,
+            aimAssistMode: headlessConfig.aimAssistMode
+        });
+        const currentLogFilePath = await headlessDebug.getCurrentLogFilePath();
+        if (currentLogFilePath) {
+            console.log(`Debug logging enabled: ${currentLogFilePath}`);
+        }
+        console.log(`\nRunning test from: ${testPath}\n`);
+        console.log(`Using CUA model: ${runtimeContext.config.cuaModel}`);
+        const appContextText = appContext.text;
+        emitCliAppContextDebug(runId, appContext, appContextText);
+        session.updateResponseId(undefined);
+        session.clearMessages();
+        const executionPrompt = buildExecutionModePrompt(deviceInfo, headlessConfig.promptCustomizations, appContextText, { aimAssistMode: headlessConfig.aimAssistMode });
+        session.setSystemPrompt(executionPrompt);
+        const screenshotRecorder = headlessDebug.createExecutionScreenshotRecorder({
+            runId,
+            recordScreenshots,
+            screenshotDir
+        });
+        const engineOptions = buildHeadlessEngineOptions({
+            runtimeContext,
+            headlessConfig,
+            executionPrompt,
+            screenshotRecorder,
+            recordScreenshots,
+            screenshotDir,
+            isBrowserTarget,
+            isLambdaTestTarget
+        });
+        const engine = new ExecutionEngine(session, engineOptions);
+        executionMode = new ExecutionMode(session, engine, instructions, true);
+        const result = await executionMode.execute({
+            runId,
+            addOutput: printCliOutput,
+            openAiClient: runtimeContext.openAiClient,
+            loadmillClient: runtimeContext.loadmillClient,
+            runtimeCredentials: runtimeContext.credentials,
+        });
+        const stats = executionMode.stats || {};
+        const durationMs = stats.startTime ? Math.max(0, Date.now() - stats.startTime) : 0;
+        await headlessDebug.endExecutionSession(runId, {
+            success: Boolean(result.success),
+            error: result.error ?? null,
+            durationMs,
+            instructionsTotal: instructions.length,
+            instructionsCompleted: stats.instructionsCompleted ?? 0,
+            actionsTotal: stats.actionCount ?? 0,
+            assertionsPassed: stats.assertionsPassed ?? 0,
+            assertionsFailed: stats.assertionsFailed ?? 0,
+            retries: stats.retryCount ?? 0
+        });
+        if (!result.success) {
+            console.error(`\nTest failed: ${result.error}`);
+        }
+        return {
+            success: Boolean(result.success),
+            error: result.error ?? null
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to start execution.";
+        const stats = executionMode?.stats || {};
+        const durationMs = stats.startTime ? Math.max(0, Date.now() - stats.startTime) : 0;
+        await headlessDebug.endExecutionSession(runId, {
+            success: false,
+            error: message,
+            ...(stats.startTime
+                ? {
+                    durationMs,
+                    instructionsTotal: instructions.length,
+                    instructionsCompleted: stats.instructionsCompleted ?? 0,
+                    actionsTotal: stats.actionCount ?? 0,
+                    assertionsPassed: stats.assertionsPassed ?? 0,
+                    assertionsFailed: stats.assertionsFailed ?? 0,
+                    retries: stats.retryCount ?? 0
+                }
+                : { reason: "start_failed" })
+        });
+        throw error;
+    }
+}
+export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
+    const isBatchRun = instructionsTarget?.type === "directory";
+    if (isBatchRun) {
+        console.log(`\nRunning ${runs.length} tests from: ${instructionsTarget.path}\n`);
+    }
+    let failures = 0;
+    for (const [index, run] of runs.entries()) {
+        const runId = createHeadlessRunId(index);
+        const testScreenshotDir = getRecordScreenshotDirForTest(screenshotDir, run.testName, isBatchRun);
+        if (isBatchRun) {
+            console.log(`\n[${index + 1}/${runs.length}] ${run.testName}`);
+        }
+        try {
+            const instructions = run.instructions ?? await loadHeadlessInstructions(run.testPath);
+            if (recordScreenshots && testScreenshotDir) {
+                await mkdir(testScreenshotDir, { recursive: true });
+            }
+            const result = await runHeadlessTest({
+                runId,
+                testPath: run.testPath,
+                testName: run.testName,
+                instructions,
+                session,
+                deviceInfo,
+                headlessConfig,
+                appContext,
+                runtimeContext,
+                headlessDebug,
+                recordScreenshots,
+                screenshotDir: testScreenshotDir,
+                isBrowserTarget,
+                isLambdaTestTarget
+            });
+            if (!result.success) {
+                failures += 1;
+            }
+        }
+        catch (error) {
+            failures += 1;
+            if (!isBatchRun) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`\nTest failed: ${run.testName}: ${message}`);
+        }
+    }
+    if (isBatchRun) {
+        const passed = runs.length - failures;
+        console.log(`\nFolder run complete: ${passed}/${runs.length} passed`);
+    }
+    return {
+        exitCode: failures === 0 ? 0 : 1,
+        failures
+    };
+}