@loadmill/droid-cua 2.34.0 → 2.36.0

package/README.md

@@ -79,6 +79,7 @@ Desktop app support:
 
 **All platforms:**
 - Loadmill sign-in for the Loadmill models, or an OpenAI API key for the OpenAI models
+- Node.js 20 or newer for CLI use
 
 **Android:**
 - Android Debug Bridge (ADB)
@@ -172,13 +173,26 @@ Examples:
 droid-cua
 
 # Headless Android run
-droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua
+droid-cua run tests/login.dcua --avd adb:emulator-5554
 
 # Headless Android folder run
-droid-cua --avd adb:emulator-5554 --instructions tests
+droid-cua run tests --avd adb:emulator-5554
+
+# Select tests from different folders
+droid-cua run tests/auth/login.dcua tests/checkout/purchase.dcua admin/refund.dcua \
+  --avd adb:emulator-5554
 
 # Headless iOS simulator run
-droid-cua --platform ios --avd "iPhone 16" --instructions tests/login.dcua
+droid-cua run tests/login.dcua --platform ios --avd "iPhone 16"
+
+# List running desktop applications and their window IDs (macOS or Windows)
+droid-cua --target desktop --list-desktop-apps
+
+# Control one already-running desktop application window
+droid-cua --target desktop --desktop-app com.apple.TextEdit --desktop-window 123 --instructions tests/editor.dcua
+
+# Explicitly use cursor-free accessibility input instead of the default physical input
+droid-cua --target desktop --desktop-app com.apple.TextEdit --desktop-input accessibility --instructions tests/editor.dcua
 
 # Headless run with prompt-parity config
 droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua --config ci/droid-cua.json
@@ -212,6 +226,16 @@ droid-cua \
   --instructions tests/login.dcua
 ```
 
+`droid-cua run` accepts one or more `.dcua` files or directories. Inputs are
+expanded in the order provided, files inside each directory retain their natural
+name ordering, and overlapping paths are run only once. A single config, target,
+context, test-data file, and secrets source applies to the entire invocation.
+The `run` command must be the first argument. Keep all selected paths contiguous
+and place options after the complete path list. Arbitrary option/path
+interleaving is not supported.
+The existing `--instructions <file-or-directory>` form remains supported for
+backward compatibility.
+
 Example headless config:
 ```json
 {
@@ -246,6 +270,11 @@ Supported CLI options include:
 - `--app`
 - `--list-devices`
 - `--browser`
+- `--target` (`mobile`, `web`, or `desktop`)
+- `--desktop-app` (desktop application ID or exact name)
+- `--desktop-window` (required when the application has multiple visible windows)
+- `--desktop-input` (`physical` by default; use `accessibility` for cursor-free input)
+- `--list-desktop-apps`
 - `--instructions`
 - `--config`
 - `--cua-model`
@@ -268,6 +297,8 @@ Supported CLI options include:
 `gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.4`. OpenAI models use direct OpenAI
 mode and require `OPENAI_API_KEY`.
 
+Desktop control supports macOS and Windows. In the desktop app, enable **Experimental desktop control** at the bottom of Settings to show Desktop in the platform picker. Desktop runs use visual input by default: they capture the selected window and send physical pointer and keyboard input at the model's coordinates. Use `--desktop-input accessibility` for cursor-free CLI input instead. macOS requires Screen & System Audio Recording and Accessibility permissions for Droid or the terminal running the CLI. Windows targets must run at the same integrity level as Droid; a non-elevated Droid process cannot inject input into an elevated application.
+
 Config and precedence rules:
 - Use `--config <file>` to supply prompt-affecting settings for headless runs.
 - CLI flags override config file values.
@@ -292,12 +323,13 @@ Secret typing:
 HTML report (`--report`):
 - Writes a self-contained HTML report of the run — the same Run Details view the desktop app shows, with screenshots inlined — that you can share and open in any browser.
 - With no value it saves `<test>--<date>--<time>.html` (e.g. `login--2026-06-03--16-09-20.html`) in the current directory; pass `--report <file>` to pick a filename or `--report <dir>` to pick a folder.
+- A multi-path selection writes the individual test reports plus one aggregate `Selected tests` report with a child result and timeline for every selected test. When `--report <file.html>` is used, that exact path is used for the aggregate report.
 - In the desktop app the same report is available from a run's **Share → Download HTML report** button.
-- Runs with captured screenshots also expose **Share → Generate video**. The desktop app renders a square mobile replay or 16:9 browser replay locally, then prompts for a save location using `<test>--<date>--<time>--test-replay.mp4` as the suggested filename. While rendering, a compact **Background tasks** card shows progress for **Generating test replay**; it can be minimized to a task-count card or canceled without opening the save dialog.
+- Runs with captured screenshots also expose **Share → Generate video**. The desktop app renders a square mobile replay or 16:9 web and desktop replay locally, then prompts for a save location using `<test>--<date>--<time>--test-replay.mp4` as the suggested filename. While rendering, a compact **Background tasks** card shows progress for **Generating test replay**; it can be minimized to a task-count card or canceled without opening the save dialog.
 - Authenticated headless runs upload their HTML report and screenshots to Loadmill by default. The Loadmill run record also includes the resolved Droid version, model, provider, Agent Pace, Aim Assist, Context Optimization, and target environment. Use `--no-cloud-report` to disable artifact upload; the Droid run record is still reported.
 
 ```sh
-droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua --report ./reports
+droid-cua run tests/login.dcua --avd adb:emulator-5554 --report ./reports
 ```
 
 LambdaTest CLI runs:

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,5 @@
+# Third-Party Notices
+
+Desktop control uses `@zavora-ai/computer-use-mcp` version 7.1.0.
+
+Copyright (c) Zavora AI contributors. Licensed under the MIT License. The dependency's complete license text is distributed with its npm package.

package/build/index.js

@@ -22,7 +22,7 @@ import { resolveHeadlessExecutionConfig } from "./src/cli/headless-execution-con
 import { artifactKindsForPool, resolveHeadlessTarget, scopeArtifactKindsToPool, shouldWaitForLoadmillCloudCompletion, } from "./src/cli/headless-target.js";
 import { createHeadlessDebugArtifacts } from "./src/cli/headless-debug.js";
 import { loadHeadlessInstructions } from "./src/cli/headless-instructions.js";
-import { listHeadlessInstructionFiles, resolveHeadlessInstructionsTarget } from "./src/cli/headless-instruction-target.js";
+import { assertRunCommandPosition, getHeadlessInstructionSelectors, resolveHeadlessInstructionSelection, } from "./src/cli/headless-selection.js";
 import { runHeadlessInstructionRuns } from "./src/cli/headless-runner.js";
 import { buildLoadmillCloudDeviceConnectSummaryLines } from "./src/cli/loadmill-cloud-device-connect-summary.js";
 import { planScenarioRuns } from "./src/cli/scenario-planner.js";
@@ -43,6 +43,7 @@ import { resolveRunPool } from "./src/device/cloud/loadmill-cloud/run-pool.js";
 import { ARTIFACT_READY_STATUSES } from "./src/device/cloud/loadmill-cloud/run-status.js";
 import { formatDuration } from "./src/core/report/run-log-model.js";
 import { createBrowserSessionTeardown, withLoadmillCloudSession } from "./src/cli/loadmill-cloud-session.js";
+import { createDesktopController, listDesktopApplications } from "./src/desktop/computer-use.js";
 dotenv.config();
 process.once("SIGTERM", async () => {
     process.exitCode = 143;
@@ -58,7 +59,8 @@ process.once("SIGTERM", async () => {
 process.once("beforeExit", () => {
     loadmillCloudAdapter.releaseActiveSession();
 });
-const args = minimist(process.argv.slice(2));
+const cliArgs = process.argv.slice(2);
+const args = minimist(cliArgs);
 if (args._[0] === "skill") {
     try {
         await runSkillCommand({ args });
@@ -75,7 +77,18 @@ 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;
+let instructionSelectors;
+try {
+    if (args.instructions == null && args.i == null) {
+        assertRunCommandPosition(cliArgs);
+    }
+    instructionSelectors = getHeadlessInstructionSelectors(args);
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`\nTest failed: ${message}`);
+    process.exit(1);
+}
 const appContextPath = typeof args.context === "string" ? args.context : null;
 const debugMode = args["debug"] || false;
 // --report [path]: generate a self-contained HTML report at the end of the run.
@@ -230,7 +243,7 @@ async function main() {
         targetConfig.cloudSessionId &&
         Array.isArray(targetConfig.artifacts) &&
         targetConfig.artifacts.length > 0 &&
-        !instructionsFile) {
+        instructionSelectors.length === 0) {
         const credentials = resolveLoadmillCloudCredentials(process.env);
         // Share the exact same rendering the normal run command uses — install
         // the progress listener before touching the adapter, since prepareSession
@@ -259,7 +272,7 @@ async function main() {
             if (pool === "web") {
                 if (!ARTIFACT_READY_STATUSES.has(state.status)) {
                     retroactiveStatusLine.stop();
-                    console.error(`Loadmill Cloud session ${targetConfig.cloudSessionId} is not terminal yet; add --instructions to drive it, or wait until it finishes and re-run this same command to fetch artifacts.`);
+                    console.error(`Loadmill Cloud session ${targetConfig.cloudSessionId} is not terminal yet; use \`droid-cua run <path>\` or add --instructions to drive it, or wait until it finishes and re-run this same command to fetch artifacts.`);
                     process.exit(1);
                 }
                 await fetchAndDownloadArtifacts({ client, sessionId: targetConfig.cloudSessionId, kinds });
@@ -284,7 +297,7 @@ async function main() {
             // exiting via the terminal/artifacts branch above — there's nothing to
             // drive without --instructions, so release the slot and say so.
             await loadmillCloudAdapter.releaseSession(credentials, { waitForCompletion: false });
-            console.error(`Loadmill Cloud session ${targetConfig.cloudSessionId} is not terminal yet; add --instructions to drive it, or wait until it finishes and re-run this same command to fetch artifacts.`);
+            console.error(`Loadmill Cloud session ${targetConfig.cloudSessionId} is not terminal yet; use \`droid-cua run <path>\` or add --instructions to drive it, or wait until it finishes and re-run this same command to fetch artifacts.`);
             process.exit(1);
         }
         catch (error) {
@@ -310,8 +323,20 @@ async function main() {
         console.log(`Run with: --device-name "<name>" --os-version "<osVersion>"`);
         process.exit(0);
     }
-    const isHeadlessInstructionsRun = Boolean(instructionsFile);
+    if (targetConfig.listDesktopApps) {
+        const applications = await listDesktopApplications({ excludePids: [process.pid] });
+        for (const application of applications) {
+            console.log(`${application.displayName} — ${application.bundleId} (pid ${application.pid})`);
+            for (const window of application.windows) {
+                console.log(`  ${window.windowId}: ${window.title || "Untitled"}`);
+            }
+        }
+        console.log(`\n${applications.length} desktop applications with visible windows.`);
+        process.exit(0);
+    }
+    const isHeadlessInstructionsRun = instructionSelectors.length > 0;
     const isBrowserTarget = targetConfig.target === "web";
+    const isDesktopTarget = targetConfig.target === "desktop";
     const isLambdaTestTarget = targetConfig.deviceSource === "lambdatest";
     const isAwsDeviceFarmTarget = targetConfig.deviceSource === "aws-device-farm";
     const isLoadmillCloudTarget = targetConfig.deviceSource === "loadmill-cloud";
@@ -326,6 +351,7 @@ async function main() {
     let loadmillCloudBrowserSessionConnected = false;
     let loadmillCloudBrowserTeardown = null;
     let loadmillCloudStatusLine = null;
+    let desktopController = null;
     const headlessDebug = createHeadlessDebugArtifacts({
         cwd: process.cwd(),
         enabled: isHeadlessInstructionsRun && debugMode
@@ -336,16 +362,19 @@ async function main() {
     // Initialize legacy plain-text debug logging only for non-headless flows.
     await logger.init(debugMode && !isHeadlessInstructionsRun);
     if (isBrowserTarget && !isHeadlessInstructionsRun) {
-        throw new Error("--target web is only supported with --instructions headless execution.");
+        throw new Error("--target web requires `droid-cua run <path>` or --instructions headless execution.");
+    }
+    if (isDesktopTarget && !isHeadlessInstructionsRun) {
+        throw new Error("--target desktop is only supported with --instructions headless execution.");
     }
     if (isCloudTarget && !isHeadlessInstructionsRun) {
-        throw new Error(`--device-source ${targetConfig.deviceSource} is only supported with --instructions headless execution.`);
+        throw new Error(`--device-source ${targetConfig.deviceSource} requires \`droid-cua run <path>\` or --instructions headless execution.`);
     }
     if (!isHeadlessInstructionsRun && args.scenario != null) {
-        throw new Error("--scenario can only be used with --instructions headless execution.");
+        throw new Error("--scenario requires `droid-cua run <path>` or --instructions headless execution.");
     }
     if (!isHeadlessInstructionsRun && args["test-data"] != null) {
-        throw new Error("--test-data can only be used with --instructions headless execution.");
+        throw new Error("--test-data requires `droid-cua run <path>` or --instructions headless execution.");
     }
     let preloadedHeadlessConfig = null;
     let preloadedHeadlessTarget = null;
@@ -358,28 +387,15 @@ async function main() {
         await assertCliRuntimeCredentials({
             llmProviderMode: preloadedHeadlessConfig.llmProviderMode,
         });
-        preloadedHeadlessTarget = await resolveHeadlessInstructionsTarget(instructionsFile);
+        const selection = await resolveHeadlessInstructionSelection(instructionSelectors);
+        preloadedHeadlessTarget = selection.target;
+        headlessInstructionRuns = selection.runs;
         preloadedSecrets = await resolveExecutionSecrets({
             secretsPath: getDefaultSecretsPath(process.cwd()),
             cliSecrets: preloadedHeadlessConfig.secretsOverride,
         });
-        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)
-                }];
+        if (preloadedHeadlessTarget.type === "file") {
+            headlessInstructionRuns[0].instructions = await loadHeadlessInstructions(headlessInstructionRuns[0].testPath);
         }
         preloadedAppContext = await resolveExecutionAppContext({
             enabled: preloadedHeadlessConfig.appContextEnabled,
@@ -398,7 +414,7 @@ async function main() {
         }
     }
     // If no device specified, show interactive selection menu
-    if (!isBrowserTarget && !isCloudTarget && !avdName && !platform) {
+    if (!isBrowserTarget && !isDesktopTarget && !isCloudTarget && !avdName && !platform) {
         const selection = await selectDevice();
         platform = selection.platform;
         avdName = selection.deviceName;
@@ -506,6 +522,24 @@ async function main() {
             console.log(`Starting URL: ${deviceInfo.currentUrl}`);
         }
     }
+    else if (isDesktopTarget) {
+        desktopController = await createDesktopController({
+            app: targetConfig.desktopApp,
+            windowId: targetConfig.desktopWindow,
+            inputMode: targetConfig.desktopInput,
+            excludePids: [process.pid],
+        });
+        targetId = desktopController.deviceId;
+        deviceInfo = desktopController.deviceInfo;
+        console.log(`Attached to desktop window: ${deviceInfo.device_name}`);
+        console.log(`Model sees window: ${deviceInfo.scaled_width}x${deviceInfo.scaled_height}`);
+        console.log(`Desktop input: ${deviceInfo.desktopInputMode === "physical" ? "physical OS pointer" : "cursor-free accessibility"}`);
+        process.once("SIGINT", async () => {
+            console.log("\nStopping desktop run...");
+            await desktopController?.close().catch(() => { });
+            process.exit(130);
+        });
+    }
     else if (isLambdaTestTarget) {
         lambdaTestCredentials = resolveLambdaTestCredentials(process.env);
         const lambdaTestBuildName = createLambdaTestCliBuildName();
@@ -729,8 +763,8 @@ async function main() {
     const session = new Session(targetId, deviceInfo);
     const initialSystemText = buildBaseSystemPrompt(deviceInfo);
     session.setSystemPrompt(initialSystemText);
-    // If --instructions provided, run in headless mode
-    if (instructionsFile) {
+    // If tests were selected, run in headless mode.
+    if (isHeadlessInstructionsRun) {
         let exitCode = null;
         let succeeded = false;
         try {
@@ -787,8 +821,10 @@ async function main() {
                 recordScreenshots,
                 screenshotDir,
                 isBrowserTarget,
+                isDesktopTarget,
+                desktopController,
                 isCloudTarget,
-                runTarget: { isBrowserTarget, isCloudTarget },
+                runTarget: { isBrowserTarget, isDesktopTarget, isCloudTarget },
                 report: reportConfig
             });
             exitCode = result.exitCode;
@@ -845,6 +881,10 @@ async function main() {
                     console.log(`Done in ${formatDuration(Date.now() - processStartTime)}.`);
                 }
             }
+            if (desktopController) {
+                await desktopController.close();
+                desktopController = null;
+            }
         }
         if (exitCode !== null) {
             process.exit(exitCode);

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

@@ -83,9 +83,10 @@ function emitCliAppContextDebug(runId, appContext, appContextText) {
         });
     }
 }
-export function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionPrompt, screenshotRecorder, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, runTarget = null, onCuaResponse = null, secrets = null }) {
-    const resolvedRunTarget = runTarget ?? { isBrowserTarget, isCloudTarget };
+export function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionPrompt, screenshotRecorder, recordScreenshots, screenshotDir, isBrowserTarget, isDesktopTarget, desktopController, isCloudTarget, runTarget = null, onCuaResponse = null, secrets = null }) {
+    const resolvedRunTarget = runTarget ?? { isBrowserTarget, isDesktopTarget, isCloudTarget };
     const isBrowserRunTarget = Boolean(resolvedRunTarget.isBrowserTarget);
+    const isDesktopRunTarget = Boolean(resolvedRunTarget.isDesktopTarget);
     const isCloudRunTarget = Boolean(resolvedRunTarget.isCloudTarget);
     const sendCUARequest = async (requestArgs) => {
         const response = await runtimeContext.openAi.sendCUARequest({
@@ -101,7 +102,7 @@ export function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, exe
         toolCapabilities: {
             assert: true,
             navigate: isBrowserRunTarget,
-            closeKeyboard: !isBrowserRunTarget,
+            closeKeyboard: !isBrowserRunTarget && !isDesktopRunTarget,
             loadmill: true,
         },
         secretsByKey: secrets?.secretsByKey || {},
@@ -130,6 +131,11 @@ export function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, exe
         engineOptions.handleModelAction = (browserSessionId, action, scale, actionContext) => handleBrowserModelAction(browserSessionId, action, scale, actionContext);
         engineOptions.getCurrentPlatform = getBrowserCurrentPlatform;
     }
+    else if (isDesktopRunTarget) {
+        engineOptions.getScreenshotAsBase64 = desktopController.getScreenshotAsBase64;
+        engineOptions.handleModelAction = desktopController.handleModelAction;
+        engineOptions.getCurrentPlatform = () => "desktop";
+    }
     if (isCloudRunTarget) {
         if (isBrowserRunTarget) {
             engineOptions.connectToBrowser = createRefuseReconnectConnectToBrowser();
@@ -142,7 +148,7 @@ export function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, exe
     }
     return engineOptions;
 }
-async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, runTarget = null, secrets = null, report = null, isBatchRun = false, reportToLoadmill = true, runConfiguration = {}, cloudUploadSession = null, uploadManager = droidReportUploadManager, }) {
+async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isDesktopTarget, desktopController, isCloudTarget, runTarget = null, secrets = null, report = null, isBatchRun = false, reportToLoadmill = true, runConfiguration = {}, cloudUploadSession = null, uploadManager = droidReportUploadManager, }) {
     let executionMode = null;
     let loadmillSessionUser = null;
     let runUsageTotals = setDroidCuaRunUsageModel(createDroidCuaRunUsageTotals(), runtimeContext.config.cuaModel);
@@ -218,6 +224,8 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             recordScreenshots,
             screenshotDir,
             isBrowserTarget,
+            isDesktopTarget,
+            desktopController,
             isCloudTarget,
             runTarget,
             onCuaResponse: (response) => {
@@ -296,9 +304,12 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             instructionsTotal: instructions.length,
             stats,
         };
-        if (localReportEnabled) {
+        const localReport = localReportEnabled
+            ? createCliRunReport({ ...reportInput, events: localEvents })
+            : null;
+        if (localReport) {
             try {
-                const outputPath = await writeCliRunReportArtifact(createCliRunReport({ ...reportInput, events: localEvents }), { reportPath: report?.path ?? null, isBatch: isBatchRun });
+                const outputPath = await writeCliRunReportArtifact(localReport, { reportPath: report?.path ?? null, isBatch: isBatchRun });
                 console.log(`HTML report saved: ${outputPath}`);
             }
             catch (reportError) {
@@ -326,6 +337,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             assertionsPassed: stats.assertionsPassed ?? 0,
             assertionsFailed: stats.assertionsFailed ?? 0,
             retries: stats.retryCount ?? 0,
+            localReportModel: localReport?.model ?? null,
             reportModel: cloudModel,
         };
     }
@@ -391,9 +403,12 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             instructionsTotal: instructions.length,
             stats,
         };
-        if (localReportEnabled) {
+        const localReport = localReportEnabled
+            ? createCliRunReport({ ...failedReportInput, events: localEvents })
+            : null;
+        if (localReport) {
             try {
-                const outputPath = await writeCliRunReportArtifact(createCliRunReport({ ...failedReportInput, events: localEvents }), { reportPath: report?.path ?? null, isBatch: isBatchRun });
+                const outputPath = await writeCliRunReportArtifact(localReport, { reportPath: report?.path ?? null, isBatch: isBatchRun });
                 console.log(`HTML report saved: ${outputPath}`);
             }
             catch (reportError) {
@@ -422,20 +437,21 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
                 assertionsPassed: stats.assertionsPassed ?? 0,
                 assertionsFailed: stats.assertionsFailed ?? 0,
                 retries: stats.retryCount ?? 0,
+                localReportModel: localReport?.model ?? null,
                 reportModel: cloudModel,
             };
         }
         throw error;
     }
 }
-export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, secrets = null, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, runTarget = null, report = null, droidVersion = getDroidVersion(), runHeadlessTestImpl = runHeadlessTest, uploadManager = droidReportUploadManager, }) {
-    const resolvedRunTarget = runTarget ?? { isBrowserTarget, isCloudTarget };
+export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, secrets = null, recordScreenshots, screenshotDir, isBrowserTarget, isDesktopTarget = false, desktopController = null, isCloudTarget, runTarget = null, report = null, droidVersion = getDroidVersion(), runHeadlessTestImpl = runHeadlessTest, uploadManager = droidReportUploadManager, }) {
+    const resolvedRunTarget = runTarget ?? { isBrowserTarget, isDesktopTarget, isCloudTarget };
     const runConfiguration = buildDroidRunConfiguration({
         droidVersion,
         runtimeConfig: runtimeContext.config,
         aimAssistMode: headlessConfig.aimAssistMode,
     });
-    const isBatchRun = instructionsTarget?.type === "directory" || instructionsTarget?.type === "scenario";
+    const isBatchRun = ["directory", "selection", "scenario"].includes(instructionsTarget?.type);
     const cloudReportEnabled = report?.cloudEnabled !== false &&
         Boolean(runtimeContext.loadmillClient?.getApiToken?.());
     const cloudUploadSession = cloudReportEnabled
@@ -447,6 +463,9 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
     if (instructionsTarget?.type === "scenario") {
         console.log(`\nRunning ${runs.length} scenario case${runs.length === 1 ? "" : "s"}\n`);
     }
+    else if (instructionsTarget?.type === "selection") {
+        console.log(`\nRunning ${runs.length} selected test${runs.length === 1 ? "" : "s"}\n`);
+    }
     else if (isBatchRun) {
         console.log(`\nRunning ${runs.length} tests from: ${instructionsTarget.path}\n`);
     }
@@ -461,6 +480,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
         assertionsFailed: 0,
         retries: 0
     };
+    const aggregateLocalReportModels = [];
     const aggregateReportModels = [];
     for (const [index, run] of runs.entries()) {
         const runId = createHeadlessRunId(index);
@@ -489,6 +509,8 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
                 recordScreenshots,
                 screenshotDir: testScreenshotDir,
                 isBrowserTarget: resolvedRunTarget.isBrowserTarget,
+                isDesktopTarget: resolvedRunTarget.isDesktopTarget,
+                desktopController,
                 isCloudTarget: resolvedRunTarget.isCloudTarget,
                 runTarget: resolvedRunTarget,
                 report,
@@ -508,6 +530,9 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             if (result.reportModel) {
                 aggregateReportModels.push(result.reportModel);
             }
+            if (result.localReportModel) {
+                aggregateLocalReportModels.push(result.localReportModel);
+            }
             if (!result.success) {
                 failures += 1;
             }
@@ -518,6 +543,25 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
                 throw error;
             }
             const message = error instanceof Error ? error.message : String(error);
+            if (instructionsTarget?.type === "selection" && (report?.enabled || cloudReportEnabled)) {
+                const failedReportModel = buildCliRunReportModel({
+                    suiteName: path.basename(path.dirname(run.testPath)) || null,
+                    testName: run.testName,
+                    startedAtIso: new Date().toISOString(),
+                    durationMs: 0,
+                    success: false,
+                    error: message,
+                    instructionsTotal: 0,
+                    stats: {},
+                    events: [],
+                });
+                if (report?.enabled) {
+                    aggregateLocalReportModels.push(failedReportModel);
+                }
+                if (cloudReportEnabled) {
+                    aggregateReportModels.push(failedReportModel);
+                }
+            }
             console.error(`\nTest failed: ${run.testName}: ${message}`);
         }
     }
@@ -525,19 +569,50 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
         const passed = runs.length - failures;
         console.log(`\nScenario run complete: ${passed}/${runs.length} passed`);
     }
+    else if (instructionsTarget?.type === "selection") {
+        const passed = runs.length - failures;
+        console.log(`\nSelected tests run complete: ${passed}/${runs.length} passed`);
+    }
     else if (isBatchRun) {
         const passed = runs.length - failures;
         console.log(`\nFolder run complete: ${passed}/${runs.length} passed`);
     }
     if (isBatchRun) {
         const isScenario = instructionsTarget?.type === "scenario";
-        const testName = isScenario ? "Scenario run" : path.basename(instructionsTarget.path);
+        const isSelection = instructionsTarget?.type === "selection";
+        const projectName = isScenario || isSelection
+            ? path.basename(process.cwd())
+            : path.basename(instructionsTarget.path);
+        const testName = isScenario
+            ? "Scenario run"
+            : isSelection
+                ? instructionsTarget.label
+                : path.basename(instructionsTarget.path);
+        if (isSelection && report?.enabled && aggregateLocalReportModels.length > 0) {
+            const aggregateReport = createCliAggregateRunReport({
+                suiteName: projectName,
+                testName,
+                startedAtIso: new Date(batchStartedAt).toISOString(),
+                durationMs: Math.max(aggregateStats.durationMs, Date.now() - batchStartedAt),
+                childModels: aggregateLocalReportModels,
+            });
+            try {
+                const outputPath = await writeCliRunReportArtifact(aggregateReport, {
+                    reportPath: report?.path ?? null,
+                });
+                console.log(`Aggregate HTML report saved: ${outputPath}`);
+            }
+            catch (reportError) {
+                const message = reportError instanceof Error ? reportError.message : String(reportError);
+                console.warn(`Warning: failed to write aggregate HTML report: ${message}`);
+            }
+        }
         const reportedRun = await reportDroidRunCompletion({
             ...runConfiguration,
             loadmillClient: runtimeContext.loadmillClient,
             source: "ci",
             runId: createHeadlessRunId(),
-            projectName: isScenario ? path.basename(process.cwd()) : path.basename(instructionsTarget.path),
+            projectName,
             testName,
             runType: "project",
             testCases: runs.length,
@@ -560,7 +635,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
         });
         if (cloudUploadSession && reportedRun.savedRunId) {
             const aggregateReport = createCliAggregateRunReport({
-                suiteName: isScenario ? path.basename(process.cwd()) : path.basename(instructionsTarget.path),
+                suiteName: projectName,
                 testName,
                 startedAtIso: new Date(batchStartedAt).toISOString(),
                 durationMs: Math.max(aggregateStats.durationMs, Date.now() - batchStartedAt),

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

@@ -0,0 +1,80 @@
+import path from "path";
+import { listHeadlessInstructionFiles, resolveHeadlessInstructionsTarget, } from "./headless-instruction-target.js";
+function normalizeOptionValues(value, optionName) {
+    if (value == null) {
+        return [];
+    }
+    const values = Array.isArray(value) ? value : [value];
+    if (values.some((entry) => typeof entry !== "string" || !entry.trim())) {
+        throw new Error(`${optionName} requires a file or directory path.`);
+    }
+    return values.map((entry) => entry.trim());
+}
+export function assertRunCommandPosition(argv) {
+    const runIndex = Array.isArray(argv) ? argv.indexOf("run") : -1;
+    if (runIndex > 0) {
+        throw new Error("`run` must be the first argument. Use `droid-cua run <paths...> [options]`.");
+    }
+}
+export function getHeadlessInstructionSelectors(args) {
+    const positional = Array.isArray(args?._) ? args._ : [];
+    const instructionSelectors = [
+        ...normalizeOptionValues(args?.instructions, "--instructions"),
+        ...normalizeOptionValues(args?.i, "-i"),
+    ];
+    if (positional[0] !== "run") {
+        return instructionSelectors;
+    }
+    if (instructionSelectors.length > 0) {
+        throw new Error("Do not combine `droid-cua run <paths...>` with --instructions or -i.");
+    }
+    const runSelectors = positional.slice(1);
+    if (runSelectors.length === 0) {
+        throw new Error("`droid-cua run` requires at least one test file or directory.");
+    }
+    return runSelectors;
+}
+function displayPath(filePath, cwd) {
+    const relativePath = path.relative(cwd, path.resolve(cwd, filePath));
+    return relativePath || path.basename(filePath);
+}
+export async function resolveHeadlessInstructionSelection(selectors, { cwd = process.cwd() } = {}) {
+    if (!Array.isArray(selectors) || selectors.length === 0) {
+        throw new Error("At least one test file or directory is required.");
+    }
+    const targets = [];
+    const selectedFiles = [];
+    const seenPaths = new Set();
+    for (const selector of selectors) {
+        const target = await resolveHeadlessInstructionsTarget(selector);
+        targets.push(target);
+        const files = target.type === "directory"
+            ? await listHeadlessInstructionFiles(target.path)
+            : [{ filename: path.basename(target.path), path: target.path }];
+        if (target.type === "directory" && files.length === 0) {
+            throw new Error(`No .dcua tests found in instructions directory ${target.path}.`);
+        }
+        for (const file of files) {
+            const dedupeKey = path.resolve(cwd, file.path);
+            if (seenPaths.has(dedupeKey)) {
+                continue;
+            }
+            seenPaths.add(dedupeKey);
+            selectedFiles.push(file);
+        }
+    }
+    const isSelection = selectors.length > 1;
+    const target = isSelection
+        ? {
+            type: "selection",
+            paths: targets.map((entry) => entry.path),
+            label: "Selected tests",
+        }
+        : targets[0];
+    const runs = selectedFiles.map((file) => ({
+        testPath: file.path,
+        testName: isSelection ? displayPath(file.path, cwd) : file.filename,
+        instructions: null,
+    }));
+    return { target, runs };
+}