@loadmill/droid-cua 2.35.0 → 2.36.0

package/README.md

@@ -173,13 +173,17 @@ 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
@@ -222,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
 {
@@ -309,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 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/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";
@@ -59,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 });
@@ -76,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.
@@ -231,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
@@ -260,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 });
@@ -285,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) {
@@ -322,7 +334,7 @@ async function main() {
         console.log(`\n${applications.length} desktop applications with visible windows.`);
         process.exit(0);
     }
-    const isHeadlessInstructionsRun = Boolean(instructionsFile);
+    const isHeadlessInstructionsRun = instructionSelectors.length > 0;
     const isBrowserTarget = targetConfig.target === "web";
     const isDesktopTarget = targetConfig.target === "desktop";
     const isLambdaTestTarget = targetConfig.deviceSource === "lambdatest";
@@ -350,19 +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;
@@ -375,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,
@@ -764,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 {

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

@@ -304,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) {
@@ -334,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,
         };
     }
@@ -399,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) {
@@ -430,6 +437,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,
             };
         }
@@ -443,7 +451,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
         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
@@ -455,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`);
     }
@@ -469,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);
@@ -518,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;
             }
@@ -528,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}`);
         }
     }
@@ -535,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,
@@ -570,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 };
+}

package/build/src/commands/help.js

@@ -15,6 +15,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Usage:' });
     addOutput({ type: 'info', text: '  droid-cua --avd <device-name> [options]' });
+    addOutput({ type: 'info', text: '  droid-cua run <file-or-directory...> [options]' });
     addOutput({ type: 'info', text: '  droid-cua --target web --instructions <file> [options]' });
     addOutput({ type: 'info', text: '  droid-cua --device-source lambdatest --instructions <file> [options]' });
     addOutput({ type: 'info', text: '' });
@@ -32,7 +33,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --app <path>           LambdaTest app package path (.apk or .ipa)' });
     addOutput({ type: 'info', text: '  --artifacts <kinds>    Loadmill Cloud: download video,deviceLog,appiumLog (or all) after the run' });
     addOutput({ type: 'info', text: '  --cloud-session-id <id> Loadmill Cloud: reconnect/retroactive-fetch by mtc_ id (implies --device-source loadmill-cloud)' });
-    addOutput({ type: 'info', text: '  --instructions <file>  Run test file in headless mode' });
+    addOutput({ type: 'info', text: '  --instructions <path>  Legacy headless test file or directory selector' });
     addOutput({ type: 'info', text: '  --scenario <prompt>    Generate and run scenario cases for headless instructions' });
     addOutput({ type: 'info', text: '  --test-data <file>     Optional test-data.md file for --scenario' });
     addOutput({ type: 'info', text: '  --secrets <pairs>      Runtime typing secrets as KEY=value,OTHER=value' });
@@ -92,6 +93,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  droid-cua --avd avd:Pixel_8_API_35       (Launch Android AVD then connect)' });
     addOutput({ type: 'info', text: '  droid-cua --avd "iPhone 16"             (iOS Simulator, auto-detected)' });
     addOutput({ type: 'info', text: '  droid-cua --platform ios --avd MySim    (Force iOS platform)' });
+    addOutput({ type: 'info', text: '  droid-cua run tests/login.dcua admin/refund.dcua --context app/context.md' });
     addOutput({ type: 'info', text: '  droid-cua --instructions tests/login.dcua --context app/context.md' });
     addOutput({ type: 'info', text: '  droid-cua --instructions tests --test-data tests/test-data.md --scenario "Run every checkout test with each buyer account"' });
     addOutput({ type: 'info', text: '  droid-cua --target web --instructions tests/search.dcua' });

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

@@ -3,6 +3,20 @@
  */
 import { extractLoadmillSessionUser } from "./session-user.js";
 const DEFAULT_BASE_URL = "https://app.loadmill.com/api";
+/**
+ * @typedef {{
+ *   id: string,
+ *   email: string | null,
+ *   displayName: string | null,
+ *   teamId: string | null,
+ * }} LoadmillSessionUser
+ */
+/**
+ * @typedef {
+ *   | { valid: true, user: LoadmillSessionUser, status: number, requestId?: string }
+ *   | { valid: false, reason: "missing" | "invalid" | "unavailable" | "malformed", status?: number, requestId?: string }
+ * } ApiTokenValidationResult
+ */
 function normalizeApiBaseUrl(rawBaseUrl) {
     const candidate = (rawBaseUrl || DEFAULT_BASE_URL).trim();
     if (!candidate) {
@@ -150,6 +164,7 @@ export function createLoadmillApiClient({ token = null, baseUrl = null, onUnauth
             body: JSON.stringify(payload),
         });
     }
+    /** @returns {Promise<ApiTokenValidationResult>} */
     async function validateApiToken() {
         const resolvedToken = getApiToken();
         if (!resolvedToken) {
@@ -162,20 +177,25 @@ export function createLoadmillApiClient({ token = null, baseUrl = null, onUnauth
                 Authorization: `Bearer ${resolvedToken}`,
             },
         });
+        const requestId = response.headers.get("x-request-id") || response.headers.get("request-id") || undefined;
+        const responseMetadata = {
+            status: response.status,
+            ...(requestId ? { requestId } : {}),
+        };
         if (response.status === 401 || response.status === 403) {
-            return { valid: false, reason: "invalid", status: response.status };
+            return { valid: false, reason: "invalid", ...responseMetadata };
         }
         if (!response.ok) {
-            return { valid: false, reason: "unavailable", status: response.status };
+            return { valid: false, reason: "unavailable", ...responseMetadata };
         }
         try {
             const user = extractLoadmillSessionUser(await response.json());
             return user
-                ? { valid: true, user }
-                : { valid: false, reason: "unavailable", status: response.status };
+                ? { valid: true, user, ...responseMetadata }
+                : { valid: false, reason: "malformed", ...responseMetadata };
         }
         catch {
-            return { valid: false, reason: "unavailable", status: response.status };
+            return { valid: false, reason: "malformed", ...responseMetadata };
         }
     }
     async function getCurrentUser() {

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

@@ -10,6 +10,8 @@ import { handleAssertionToolCall } from "../core/tool-handlers/assert.js";
 import { logger } from "../utils/logger.js";
 import { emitDesktopDebug } from "../utils/desktop-debug.js";
 import { printCliOutput } from "../utils/console-output.js";
+import { APIConnectionError } from "openai";
+import { findDeepestErrorCode } from "../utils/error-details.js";
 // Mirrors the quota codes emitted by the Loadmill LLM gateway (see
 // services/app/private/llm in the server repo). Free plans run on the
 // fixed-budget quota.
@@ -50,6 +52,13 @@ function isRejectedContinuationError(err) {
         "invalid_previous_response_id",
     ].includes(err.code);
 }
+function isLlmConnectionError(err) {
+    return err instanceof APIConnectionError || err?.name === "APIConnectionError" || err?.name === "APIConnectionTimeoutError";
+}
+function getLlmConnectionErrorMessage(err) {
+    const networkCode = findDeepestErrorCode(err);
+    return `Could not connect to the AI service${networkCode ? ` (${networkCode})` : ""}. Check your network, proxy, or security software and try again.`;
+}
 function getLlmUsageLimitMessage() {
     return `Execution stopped: you've reached the AI usage limit for this account. Contact the Loadmill team to upgrade: ${LOADMILL_UPGRADE_URL}`;
 }
@@ -422,6 +431,22 @@ export class ExecutionMode {
                 stack: err.stack
             });
             const addOutput = context.addOutput || printCliOutput;
+            if (isLlmConnectionError(err)) {
+                const stopMessage = getLlmConnectionErrorMessage(err);
+                logger.debug('Stopping execution after an LLM connection failure', {
+                    instruction,
+                    message: err.message,
+                    code: findDeepestErrorCode(err),
+                });
+                this.emit(addOutput, 'error', stopMessage, context, stepContext, {
+                    eventType: 'error',
+                    payload: {
+                        message: stopMessage,
+                        code: findDeepestErrorCode(err),
+                    }
+                });
+                return { success: false, error: stopMessage };
+            }
             if (this.session.previousResponseId && isRejectedContinuationError(err)) {
                 this.emit(addOutput, 'error', err.message, context, stepContext, {
                     eventType: 'error',

package/build/src/utils/cua-debug-tracer.js

@@ -1,5 +1,6 @@
 import crypto from "crypto";
 import { emitDesktopDebug, truncateForDebug } from "./desktop-debug.js";
+import { summarizeError } from "./error-details.js";
 function safeHeadersSnapshot(headers) {
     if (!headers || typeof headers !== "object")
         return {};
@@ -23,17 +24,6 @@ function safeHeadersSnapshot(headers) {
     }
     return out;
 }
-function summarizeErrorCause(error) {
-    const cause = error?.cause;
-    if (!cause || typeof cause !== "object") {
-        return null;
-    }
-    return {
-        name: typeof cause.name === "string" ? cause.name : null,
-        message: typeof cause.message === "string" ? cause.message : String(cause),
-        code: typeof cause.code === "string" ? cause.code : null,
-    };
-}
 function summarizeContent(content) {
     if (typeof content === "string") {
         return truncateForDebug(content, 1600);
@@ -462,7 +452,7 @@ export class CuaDebugTracer {
             requestId,
             headers,
             endpoint: trace.endpoint || null,
-            cause: summarizeErrorCause(err),
+            cause: summarizeError(err?.cause),
             chain: {
                 lastResponseId: trace.lastResponseMeta?.id ?? null,
                 lastResponseOutputTypes: trace.lastResponseMeta?.outputTypes ?? [],

package/build/src/utils/error-details.js

@@ -0,0 +1,56 @@
+const ERROR_FIELDS = [
+    "name",
+    "message",
+    "code",
+    "errno",
+    "syscall",
+    "hostname",
+    "address",
+    "port",
+];
+export function summarizeError(error, maxCauseDepth = 5) {
+    if (error == null) {
+        return null;
+    }
+    if (typeof error !== "object") {
+        return { message: String(error) };
+    }
+    const seen = new Set();
+    function visit(current, depth) {
+        if (!current || typeof current !== "object" || seen.has(current)) {
+            return null;
+        }
+        seen.add(current);
+        const summary = {};
+        for (const field of ERROR_FIELDS) {
+            const value = current[field];
+            if (typeof value === "string" || typeof value === "number") {
+                summary[field] = value;
+            }
+        }
+        if (!summary.message) {
+            summary.message = String(current);
+        }
+        if (depth < maxCauseDepth) {
+            const cause = visit(current.cause, depth + 1);
+            if (cause) {
+                summary.cause = cause;
+            }
+        }
+        return summary;
+    }
+    return visit(error, 0);
+}
+export function findDeepestErrorCode(error) {
+    let current = error;
+    let code = null;
+    const seen = new Set();
+    while (current && typeof current === "object" && !seen.has(current)) {
+        seen.add(current);
+        if (typeof current.code === "string" || typeof current.code === "number") {
+            code = String(current.code);
+        }
+        current = current.cause;
+    }
+    return code;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.35.0",
+  "version": "2.36.0",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",

package/skill/droid-cua/references/running-and-healing.md

@@ -2,7 +2,11 @@
 
 ## Construct the run
 
-Prefer a single test before a directory or scenario run. Preserve an existing provider/model choice in `ci/droid-cua.json`; otherwise use the Loadmill provider with Loadmill Pulse as the recommended model for daily authoring, local runs, and CI. Escalate to Loadmill Smart when stability is a demonstrated problem and run evidence shows Smart improves it:
+Prefer a single test before a directory, multi-path selection, or scenario run. Use `droid-cua run <paths...>` for saved tests. It accepts one or more `.dcua` files or directories, including files from different folders. `run` must be the first argument. Keep all selected paths contiguous and place options after the complete path list. Inputs retain command-line order, directories use natural test-name ordering, and overlapping files run only once. The legacy `--instructions <file-or-directory>` form remains supported, but prefer `run` for new commands.
+
+A single target, config, context, test-data file, and secrets source applies to the entire command. Combine tests only when they share those run-level settings; otherwise use separate commands. Multi-path runs execute sequentially and produce an aggregate **Selected tests** report in addition to individual test reports.
+
+Preserve an existing provider/model choice in `ci/droid-cua.json`; otherwise use the Loadmill provider with Loadmill Pulse as the recommended model for daily authoring, local runs, and CI. Escalate to Loadmill Smart when stability is a demonstrated problem and run evidence shows Smart improves it:
 
 ```sh
 # Recommended daily model
@@ -18,25 +22,28 @@ Include `--report reports/<test-name>.html` for normal test runs unless the user
 
 ```sh
 # Attached Android device or running emulator
-droid-cua --llm-provider loadmill --cua-model loadmill-pulse --avd adb:<serial> --instructions tests/example.dcua --context tests/context.md --debug --report reports/example.html
+droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --avd adb:<serial> --context tests/context.md --debug --report reports/example.html
 
 # Launchable Android AVD
-droid-cua --avd avd:<avd-name> --instructions tests/example.dcua --config ci/droid-cua.json --debug --report reports/example.html
+droid-cua run tests/example.dcua --avd avd:<avd-name> --config ci/droid-cua.json --debug --report reports/example.html
 
 # iOS Simulator
-droid-cua --llm-provider loadmill --cua-model loadmill-pulse --platform ios --avd "<simulator-name>" --instructions tests/example.dcua --debug --report reports/example.html
+droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --platform ios --avd "<simulator-name>" --debug --report reports/example.html
 
 # Local web
-droid-cua --llm-provider loadmill --cua-model loadmill-pulse --target web --browser chrome --session-mode fresh --instructions tests/example.dcua --debug --report reports/example.html
+droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --target web --browser chrome --session-mode fresh --debug --report reports/example.html
 
 # LambdaTest
-droid-cua --llm-provider loadmill --cua-model loadmill-pulse --device-source lambdatest --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --instructions tests/example.dcua --debug --report reports/example.html
+droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --device-source lambdatest --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --debug --report reports/example.html
 
 # AWS Device Farm
-droid-cua --llm-provider loadmill --cua-model loadmill-pulse --device-source aws-device-farm --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --instructions tests/example.dcua --debug --report reports/example.html
+droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --device-source aws-device-farm --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --debug --report reports/example.html
 
 # Direct OpenAI alternative
-droid-cua --llm-provider openai --cua-model gpt-5.4 --avd adb:<serial> --instructions tests/example.dcua --context tests/context.md --debug --report reports/example.html
+droid-cua run tests/example.dcua --llm-provider openai --cua-model gpt-5.4 --avd adb:<serial> --context tests/context.md --debug --report reports/example.html
+
+# Selected tests from different folders
+droid-cua run tests/auth/login.dcua tests/checkout/purchase.dcua admin/refund.dcua --avd adb:<serial> --config ci/droid-cua.json --debug --report reports/selected-tests.html
 ```
 
 Use `.ipa` and `--platform ios` for supported cloud iOS runs. Preserve existing config flags rather than replacing them with defaults.