@loadmill/droid-cua 2.25.0 → 2.26.0

package/README.md

@@ -48,7 +48,10 @@ Open the desktop app and choose the platform you want to test.
 
 **3. Choose your AI provider**
 
-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.
+In Settings, choose the CUA model you want to run. Loadmill Smart is the
+recommended option, Pulse is fast and efficient, and Beacon is experimental.
+The Loadmill models use your Loadmill sign-in and usage tracking. The OpenAI
+models use your own OpenAI API key.
 
 **4. Connect a target device**
 
@@ -75,7 +78,7 @@ Desktop app support:
 ## Requirements
 
 **All platforms:**
-- Loadmill sign-in for `Loadmill - Smart`, or an OpenAI API key for the OpenAI models
+- Loadmill sign-in for the Loadmill models, or an OpenAI API key for the OpenAI models
 
 **Android:**
 - Android Debug Bridge (ADB)
@@ -256,9 +259,9 @@ Supported CLI options include:
 - `--report`
 - `--debug`
 
-`--cua-model` accepts `loadmill-smart`, `loadmill-beacon`, `gpt-5.6-terra`,
-`gpt-5.6-luna`, and `gpt-5.4`. OpenAI models use direct OpenAI mode and require
-`OPENAI_API_KEY`.
+`--cua-model` accepts `loadmill-smart`, `loadmill-pulse`, `loadmill-beacon`,
+`gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.4`. OpenAI models use direct OpenAI
+mode and require `OPENAI_API_KEY`.
 
 Config and precedence rules:
 - Use `--config <file>` to supply prompt-affecting settings for headless runs.

package/build/index.js

@@ -1,3 +1,4 @@
+const processStartTime = Date.now();
 import minimist from "minimist";
 import dotenv from "dotenv";
 import path from "path";
@@ -17,7 +18,7 @@ import { resolveExecutionTestData } from "./src/core/test-data.js";
 import { getDefaultSecretsPath, resolveExecutionSecrets } from "./src/core/secrets.js";
 import { assertRuntimeCredentialsForProvider, 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 { resolveHeadlessTarget, 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";
@@ -25,12 +26,32 @@ import { runHeadlessInstructionRuns } from "./src/cli/headless-runner.js";
 import { planScenarioRuns } from "./src/cli/scenario-planner.js";
 import { resolveLambdaTestCredentials, uploadLambdaTestCliApp } from "./src/cli/lambdatest-app-upload.js";
 import { resolveAwsDeviceFarmCredentials, uploadAwsDeviceFarmCliApp } from "./src/cli/aws-device-farm-app-upload.js";
+import { resolveLoadmillCloudCredentials } from "./src/cli/loadmill-cloud-credentials.js";
+import { formatCloudUsageReport } from "./src/cli/loadmill-cloud-usage.js";
+import { LoadmillCloudControlPlaneClient } from "./src/device/cloud/loadmill-cloud/control-plane-client.js";
 import { createStatusLine } from "./src/cli/cloud-status-line.js";
 import { createLoadmillApiClient } from "./src/integrations/loadmill/client.js";
 import { getCloudProviderAdapter } from "./src/device/cloud/registry.js";
 import { setCloudProgressListener } from "./src/device/cloud/progress.js";
 import { runSkillCommand } from "./src/cli/skill-command.js";
+import { isLoadmillCloudUsageLimitError } from "./src/device/cloud/loadmill-cloud/errors.js";
+import { loadmillCloudAdapter } from "./src/device/cloud/loadmill-cloud/adapter.js";
+import { formatDuration } from "./src/core/report/run-log-model.js";
 dotenv.config();
+process.once("SIGTERM", async () => {
+    process.exitCode = 143;
+    // Registering a SIGTERM listener cancels Node's default terminate, so exit
+    // explicitly; await the /stop because a bare fire-and-forget fetch may not
+    // dispatch before exit. Capped so a slow server can't hang the exit.
+    await Promise.race([
+        loadmillCloudAdapter.releaseActiveSession(),
+        new Promise((resolve) => setTimeout(resolve, 1_500)),
+    ]);
+    process.exit(143);
+});
+process.once("beforeExit", () => {
+    loadmillCloudAdapter.releaseActiveSession();
+});
 const args = minimist(process.argv.slice(2));
 if (args._[0] === "skill") {
     try {
@@ -173,6 +194,84 @@ async function resolveLambdaTestDashboardUrl(credentials, sessionId, { attempts
     return null;
 }
 async function main() {
+    if (args["cloud-usage"] != null) {
+        try {
+            const credentials = resolveLoadmillCloudCredentials(process.env);
+            const client = new LoadmillCloudControlPlaneClient({
+                bearerToken: credentials.bearerToken,
+                baseUrl: credentials.baseUrl,
+            });
+            const usage = await client.getUsage();
+            for (const line of formatCloudUsageReport(usage)) {
+                console.log(line);
+            }
+            process.exit(0);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const code = error?.code ? ` [${error.code}]` : "";
+            console.error(`Failed to fetch Loadmill Cloud usage: ${message}${code}`);
+            process.exit(1);
+        }
+    }
+    // Pure retroactive artifact fetch: `--cloud-session-id <sid> --artifacts <kinds>`
+    // with no --instructions. Reattaching to a terminal run and downloading its
+    // recordings/logs doesn't require driving anything, so it doesn't need the
+    // full headless-instructions machinery below (which requires --instructions
+    // for every cloud device-source run).
+    if (targetConfig.deviceSource === "loadmill-cloud" &&
+        targetConfig.cloudSessionId &&
+        Array.isArray(targetConfig.artifacts) &&
+        targetConfig.artifacts.length > 0 &&
+        !instructionsFile) {
+        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
+        // reports poll/download progress unconditionally and would otherwise be
+        // silently dropped (no listener installed => no output for 10-20s).
+        const retroactiveStatusLine = createStatusLine();
+        setCloudProgressListener((event) => {
+            // The run may still be finishing up on the cloud device when this
+            // starts — only switch the umbrella label to "fetching" once the
+            // artifact list is actually in hand and downloads are starting.
+            if (event.kind === "note" && event.message === "Fetching artifacts") {
+                retroactiveStatusLine.rename("Fetching Loadmill Cloud artifacts");
+            }
+            retroactiveStatusLine.handleEvent(event);
+        });
+        try {
+            retroactiveStatusLine.start("Waiting for Loadmill Cloud artifacts");
+            await connectToDevice({
+                source: "loadmill-cloud",
+                providerId: "loadmill-cloud",
+                platform: targetConfig.platform,
+                deviceName: targetConfig.deviceName,
+                osVersion: targetConfig.osVersion,
+                appRef: targetConfig.appPath,
+                credentials,
+                cloudSessionId: targetConfig.cloudSessionId,
+                artifacts: targetConfig.artifacts,
+            }, null, { log: () => { } });
+            retroactiveStatusLine.stop();
+            // A resumable (non-terminal) session reconnected successfully instead of
+            // 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.`);
+            process.exit(1);
+        }
+        catch (error) {
+            retroactiveStatusLine.stop();
+            if (error?.artifactsOnlyExit) {
+                console.log(error.message);
+                console.log(`Done in ${formatDuration(Date.now() - processStartTime)}.`);
+                process.exit(0);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Loadmill Cloud artifact fetch failed: ${message}`);
+            process.exit(1);
+        }
+    }
     if (targetConfig.listDevices) {
         const credentials = resolveAwsDeviceFarmCredentials(process.env);
         const adapter = getCloudProviderAdapter("aws-device-farm");
@@ -188,12 +287,15 @@ async function main() {
     const isBrowserTarget = targetConfig.target === "web";
     const isLambdaTestTarget = targetConfig.deviceSource === "lambdatest";
     const isAwsDeviceFarmTarget = targetConfig.deviceSource === "aws-device-farm";
-    const isCloudTarget = isLambdaTestTarget || isAwsDeviceFarmTarget;
+    const isLoadmillCloudTarget = targetConfig.deviceSource === "loadmill-cloud";
+    const isCloudTarget = isLambdaTestTarget || isAwsDeviceFarmTarget || isLoadmillCloudTarget;
     let lambdaTestSessionConnected = false;
     let lambdaTestSessionUrl = null;
     let lambdaTestCredentials = null;
     let awsSessionConnected = false;
     let awsDeviceFarmStatusLine = null;
+    let loadmillCloudSessionConnected = false;
+    let loadmillCloudStatusLine = null;
     const headlessDebug = createHeadlessDebugArtifacts({
         cwd: process.cwd(),
         enabled: isHeadlessInstructionsRun && debugMode
@@ -407,6 +509,94 @@ async function main() {
         console.log(`Using real resolution: ${deviceInfo.device_width}x${deviceInfo.device_height}`);
         console.log(`Model sees resolution: ${deviceInfo.scaled_width}x${deviceInfo.scaled_height}`);
     }
+    else if (isLoadmillCloudTarget) {
+        const loadmillCloudCredentials = resolveLoadmillCloudCredentials(process.env);
+        loadmillCloudStatusLine = createStatusLine();
+        const statusLine = loadmillCloudStatusLine;
+        setCloudProgressListener((event) => statusLine.handleEvent(event));
+        const provisioningAbortController = new AbortController();
+        let loadmillCloudSigintHandled = false;
+        let loadmillCloudInterruptRequested = false;
+        process.once("SIGINT", async () => {
+            if (loadmillCloudSigintHandled)
+                return;
+            loadmillCloudSigintHandled = true;
+            loadmillCloudInterruptRequested = true;
+            console.log("\nStopping Loadmill Cloud session...");
+            provisioningAbortController.abort(new Error("Stopped by user"));
+            if (!loadmillCloudSessionConnected) {
+                process.exitCode = 130;
+                return;
+            }
+            await disconnectDevice({ waitForCompletion: false });
+            loadmillCloudAdapter.releaseActiveSession();
+            process.exit(130);
+        });
+        try {
+            statusLine.start("Starting Loadmill Cloud session");
+            targetId = await connectToDevice({
+                source: "loadmill-cloud",
+                providerId: "loadmill-cloud",
+                platform: targetConfig.platform,
+                deviceName: targetConfig.deviceName,
+                osVersion: targetConfig.osVersion,
+                appRef: targetConfig.appPath,
+                credentials: loadmillCloudCredentials,
+                sessionName: `droid-cua-cli-${new Date().toISOString()}`,
+                cloudSessionId: targetConfig.cloudSessionId,
+                artifacts: targetConfig.artifacts,
+                signal: provisioningAbortController.signal,
+            }, null, 
+            // These are one-off descriptive messages (not the name of the
+            // in-progress step), so they must render as persistent ℹ lines —
+            // never painted into the volatile detail slot, where a stray message
+            // like "Connected to ..." would linger after its moment has passed
+            // and contradict an already-closed "✔ <phase>" line above it.
+            { log: (message) => statusLine.handleEvent({ kind: "note", message }) });
+            loadmillCloudSessionConnected = true;
+            if (loadmillCloudInterruptRequested) {
+                try {
+                    await disconnectDevice({ waitForCompletion: false });
+                    loadmillCloudAdapter.releaseActiveSession();
+                }
+                finally {
+                    statusLine.stop();
+                    loadmillCloudSessionConnected = false;
+                    process.exitCode = 130;
+                }
+                return;
+            }
+            deviceInfo = await getDeviceInfo(targetId);
+            statusLine.stop();
+        }
+        catch (error) {
+            statusLine.stop();
+            if (error?.artifactsOnlyExit) {
+                console.log(error.message);
+                process.exitCode = 0;
+                return;
+            }
+            if (loadmillCloudSessionConnected) {
+                await disconnectDevice({ waitForCompletion: false });
+                loadmillCloudAdapter.releaseActiveSession();
+                loadmillCloudSessionConnected = false;
+            }
+            if (loadmillCloudInterruptRequested) {
+                process.exitCode = 130;
+                return;
+            }
+            if (isLoadmillCloudUsageLimitError(error)) {
+                const suffix = error.code ? ` (${error.code})` : "";
+                console.error(`\n${error.message}${suffix}`);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        console.log(`Connected to Loadmill Cloud device "${targetConfig.deviceName}" (${targetId})`);
+        console.log(`Using real resolution: ${deviceInfo.device_width}x${deviceInfo.device_height}`);
+        console.log(`Model sees resolution: ${deviceInfo.scaled_width}x${deviceInfo.scaled_height}`);
+    }
     else {
         targetId = await connectToDevice(avdName, platform);
         deviceInfo = await getDeviceInfo(targetId);
@@ -420,6 +610,7 @@ async function main() {
     // If --instructions provided, run in headless mode
     if (instructionsFile) {
         let exitCode = null;
+        let succeeded = false;
         try {
             const headlessConfig = preloadedHeadlessConfig;
             const appContext = preloadedAppContext;
@@ -477,6 +668,7 @@ async function main() {
                 report: reportConfig
             });
             exitCode = result.exitCode;
+            succeeded = true;
         }
         finally {
             if (lambdaTestSessionConnected) {
@@ -505,6 +697,18 @@ async function main() {
                 awsSessionConnected = false;
                 console.log("AWS Device Farm session ended.");
             }
+            if (loadmillCloudSessionConnected) {
+                console.log("Ending Loadmill Cloud session...");
+                loadmillCloudStatusLine.start("Ending Loadmill Cloud session");
+                await disconnectDevice({ waitForCompletion: shouldWaitForLoadmillCloudCompletion(targetConfig) });
+                loadmillCloudAdapter.releaseActiveSession();
+                loadmillCloudStatusLine.stop();
+                loadmillCloudSessionConnected = false;
+                console.log("Loadmill Cloud session ended.");
+                if (succeeded) {
+                    console.log(`Done in ${formatDuration(Date.now() - processStartTime)}.`);
+                }
+            }
         }
         if (exitCode !== null) {
             process.exit(exitCode);

package/build/src/cli/cloud-status-line.js

@@ -1,14 +1,5 @@
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-/**
- * Heroku-style volatile status line for long-running cloud-provider steps.
- * On a TTY each progress update overwrites the previous one (spinner + step
- * name + elapsed + latest detail) and the whole line is cleared when the step
- * finishes. On a non-TTY (CI, piped output) it degrades to plain log lines,
- * printed only when the detail changes. Feed it cloud progress events via
- * handleEvent: "phase" events time named sub-steps and "note" events keep
- * persistent info; both are printed (prefixed with `indent`) when the step
- * finishes.
- */
+const HEARTBEAT_INTERVAL_MS = 10_000;
 export function createStatusLine({ stream = process.stderr, indent = "" } = {}) {
     const tty = stream.isTTY;
     let active = false;
@@ -18,7 +9,6 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
     let detail = "";
     let startedAt = 0;
     let lastPrintedDetail = "";
-    let entries = [];
     let currentPhase = null;
     const render = () => {
         frame = (frame + 1) % SPINNER_FRAMES.length;
@@ -26,19 +16,45 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
         const line = `${SPINNER_FRAMES[frame]} ${stepName} (${seconds}s)${detail ? ` — ${detail}` : ""}`;
         stream.write(`\r\x1b[2K${line}`);
     };
+    const heartbeat = () => {
+        const seconds = Math.floor((Date.now() - startedAt) / 1000);
+        console.log(`… ${stepName}: still waiting (${seconds}s)${detail ? ` — ${detail}` : ""}`);
+    };
+    const printPersistent = (text) => {
+        if (tty) {
+            stream.write(`\r\x1b[2K${text}\n`);
+        }
+        else {
+            console.log(text);
+        }
+    };
     const closePhase = () => {
         if (currentPhase) {
-            currentPhase.ms = Date.now() - currentPhase.startedAt;
+            if (currentPhase.closeText != null) {
+                printPersistent(`${indent}\x1b[32m✔\x1b[0m ${currentPhase.closeText}`);
+            }
+            else {
+                const ms = Date.now() - currentPhase.startedAt;
+                printPersistent(`${indent}\x1b[32m✔\x1b[0m ${currentPhase.name} \x1b[90m(${ms}ms)\x1b[0m`);
+            }
             currentPhase = null;
         }
     };
     return {
+        rename(name) {
+            if (!active) {
+                return;
+            }
+            stepName = name;
+            if (tty) {
+                render();
+            }
+        },
         start(name) {
             active = true;
             stepName = name;
             detail = "";
             lastPrintedDetail = "";
-            entries = [];
             currentPhase = null;
             startedAt = Date.now();
             if (tty) {
@@ -46,6 +62,12 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
                 // on its own row before this step starts drawing.
                 timer = setInterval(render, 120);
             }
+            else {
+                timer = setInterval(heartbeat, HEARTBEAT_INTERVAL_MS);
+                if (typeof timer.unref === "function") {
+                    timer.unref();
+                }
+            }
         },
         update(message) {
             if (!active) {
@@ -66,11 +88,30 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
             }
             if (event.kind === "phase") {
                 closePhase();
-                currentPhase = { kind: "phase", name: event.message, startedAt: Date.now(), ms: 0 };
-                entries.push(currentPhase);
+                currentPhase = { name: event.message, startedAt: Date.now(), closeText: null };
             }
             else if (event.kind === "note") {
-                entries.push({ kind: "note", text: event.message });
+                printPersistent(`${indent}\x1b[34mℹ\x1b[0m ${event.message}`);
+                return;
+            }
+            else if (event.kind === "phase-close-text") {
+                if (currentPhase) {
+                    currentPhase.closeText = event.message;
+                }
+                return;
+            }
+            else if (event.kind === "phase-flush") {
+                closePhase();
+                return;
+            }
+            else if (event.kind === "print") {
+                // Closes any still-open phase first (flushing its "✔ ..." line)
+                // before printing the caller-supplied text verbatim, so a final
+                // summary can never race ahead of / glue onto the last phase's
+                // close line or the live spinner.
+                closePhase();
+                printPersistent(event.message);
+                return;
             }
             this.update(event.message);
         },
@@ -80,19 +121,10 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
                 clearInterval(timer);
                 timer = null;
             }
+            closePhase();
             if (tty) {
                 stream.write("\r\x1b[2K");
             }
-            closePhase();
-            for (const entry of entries) {
-                if (entry.kind === "phase") {
-                    stream.write(`${indent}\x1b[32m✔\x1b[0m ${entry.name} \x1b[90m(${entry.ms}ms)\x1b[0m\n`);
-                }
-                else {
-                    stream.write(`${indent}\x1b[34mℹ\x1b[0m ${entry.text}\n`);
-                }
-            }
-            entries = [];
         }
     };
 }

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

@@ -166,7 +166,6 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             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);

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

@@ -40,6 +40,7 @@ function normalizeBrowser(value) {
 const CLOUD_SOURCE_DISPLAY_NAMES = {
     lambdatest: "LambdaTest",
     "aws-device-farm": "AWS Device Farm",
+    "loadmill-cloud": "Loadmill Cloud",
 };
 function isCloudDeviceSource(deviceSource) {
     return Object.hasOwn(CLOUD_SOURCE_DISPLAY_NAMES, deviceSource);
@@ -49,13 +50,13 @@ function normalizeDeviceSource(value) {
         return "local";
     }
     if (typeof value !== "string") {
-        throw new Error("--device-source must be one of: local, lambdatest, aws-device-farm.");
+        throw new Error("--device-source must be one of: local, lambdatest, aws-device-farm, loadmill-cloud.");
     }
     const normalized = value.trim().toLowerCase();
     if (normalized === "local" || isCloudDeviceSource(normalized)) {
         return normalized;
     }
-    throw new Error("--device-source must be one of: local, lambdatest, aws-device-farm.");
+    throw new Error("--device-source must be one of: local, lambdatest, aws-device-farm, loadmill-cloud.");
 }
 function normalizeMobilePlatform(value, label) {
     if (!hasNonEmptyString(value)) {
@@ -79,11 +80,35 @@ function readNonEmptyCliValue(value) {
     }
     return null;
 }
+const ARTIFACT_KINDS = ["video", "deviceLog", "appiumLog"];
+function normalizeArtifactKinds(value) {
+    if (value == null || value === "") {
+        return null;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`--artifacts must be a comma-separated list of: ${ARTIFACT_KINDS.join(", ")}, or all.`);
+    }
+    const raw = value.trim();
+    if (!raw) {
+        return null;
+    }
+    if (raw.toLowerCase() === "all") {
+        return [...ARTIFACT_KINDS];
+    }
+    const kinds = [...new Set(raw.split(",").map((kind) => kind.trim()).filter(Boolean))];
+    const invalid = kinds.filter((kind) => !ARTIFACT_KINDS.includes(kind));
+    if (invalid.length > 0) {
+        throw new Error(`--artifacts has invalid kind(s): ${invalid.join(", ")}. Must be one of: ${ARTIFACT_KINDS.join(", ")}, or all.`);
+    }
+    return kinds;
+}
 function assertNoCloudFlags(args) {
     const cloudFlags = [
         ["device-name", "--device-name"],
         ["os-version", "--os-version"],
         ["app", "--app"],
+        ["cloud-session-id", "--cloud-session-id"],
+        ["artifacts", "--artifacts"],
     ];
     for (const [key, label] of cloudFlags) {
         if (args[key] != null) {
@@ -112,12 +137,26 @@ function normalizeCloudAppPath(value, platform, deviceSource) {
     }
     return appPath;
 }
+// Loadmill Cloud end-of-run disconnect must wait for the run to reach a
+// terminal status (and then poll/download artifacts) whenever --artifacts
+// was requested; otherwise the CLI exits immediately after "stop run" and
+// silently drops the artifact fetch entirely.
+export function shouldWaitForLoadmillCloudCompletion(targetConfig) {
+    return Array.isArray(targetConfig?.artifacts) && targetConfig.artifacts.length > 0;
+}
 export function resolveHeadlessTarget(args = {}) {
     const target = normalizeTarget(args.target);
     const sessionMode = normalizeSessionMode(args["session-mode"]);
     const avdName = hasNonEmptyString(args.avd) ? args.avd.trim() : null;
     const platform = normalizeMobilePlatform(args.platform, "--platform");
-    const deviceSource = normalizeDeviceSource(args["device-source"]);
+    // The mtc_ prefix on --cloud-session-id is loadmill-cloud's; when no
+    // --device-source was given, default to it so a bare retroactive-fetch
+    // command (e.g. `droid-cua --cloud-session-id mtc_... --artifacts all`)
+    // doesn't need --device-source spelled out. An explicit --device-source
+    // (cloud or not) is left untouched and still validated normally.
+    const cloudSessionIdGiven = readNonEmptyCliValue(args["cloud-session-id"]) != null;
+    const deviceSourceGiven = hasNonEmptyString(args["device-source"]);
+    const deviceSource = normalizeDeviceSource(!deviceSourceGiven && cloudSessionIdGiven ? "loadmill-cloud" : args["device-source"]);
     if (args["list-devices"] != null && deviceSource !== "aws-device-farm") {
         throw new Error("--list-devices can only be used with --device-source aws-device-farm.");
     }
@@ -139,6 +178,8 @@ export function resolveHeadlessTarget(args = {}) {
             deviceName: null,
             osVersion: null,
             appPath: null,
+            cloudSessionId: null,
+            artifacts: null,
             listDevices: false,
         };
     }
@@ -160,6 +201,8 @@ export function resolveHeadlessTarget(args = {}) {
             deviceName: null,
             osVersion: null,
             appPath: null,
+            cloudSessionId: null,
+            artifacts: null,
             listDevices: true,
         };
     }
@@ -169,20 +212,29 @@ export function resolveHeadlessTarget(args = {}) {
     if (isCloudDeviceSource(deviceSource)) {
         const deviceName = hasNonEmptyString(args["device-name"]) ? args["device-name"].trim() : null;
         const osVersion = readNonEmptyCliValue(args["os-version"]);
+        const cloudSessionId = readNonEmptyCliValue(args["cloud-session-id"]);
+        const isReconnect = deviceSource === "loadmill-cloud" && Boolean(cloudSessionId);
         const appPath = normalizeCloudAppPath(args.app, platform, deviceSource);
+        const artifacts = normalizeArtifactKinds(args.artifacts);
+        if (artifacts && deviceSource !== "loadmill-cloud") {
+            throw new Error("--artifacts can only be used with --device-source loadmill-cloud.");
+        }
         if (avdName) {
             throw new Error(`--avd cannot be used with --device-source ${deviceSource}.`);
         }
-        if (!platform) {
+        // A --cloud-session-id reconnect (including a pure retroactive artifact
+        // fetch) doesn't need --platform/--device-name/--os-version — those only
+        // describe a fresh device request. See the --app skip below (same reasoning).
+        if (!platform && !isReconnect) {
             throw new Error(`--platform is required with --device-source ${deviceSource}.`);
         }
-        if (!deviceName) {
+        if (!deviceName && !isReconnect) {
             throw new Error(`--device-name is required with --device-source ${deviceSource}.`);
         }
-        if (!osVersion) {
+        if (!osVersion && !isReconnect) {
             throw new Error(`--os-version is required with --device-source ${deviceSource}.`);
         }
-        if (!appPath) {
+        if (!appPath && !isReconnect) {
             throw new Error(`--app is required with --device-source ${deviceSource}.`);
         }
         return {
@@ -195,6 +247,8 @@ export function resolveHeadlessTarget(args = {}) {
             deviceName,
             osVersion,
             appPath,
+            cloudSessionId,
+            artifacts,
             listDevices: false,
         };
     }
@@ -208,6 +262,8 @@ export function resolveHeadlessTarget(args = {}) {
         deviceName: null,
         osVersion: null,
         appPath: null,
+        cloudSessionId: null,
+        artifacts: null,
         listDevices: false,
     };
 }

package/build/src/cli/loadmill-cloud-credentials.js

@@ -0,0 +1,11 @@
+import { createLoadmillApiClient } from "../integrations/loadmill/client.js";
+export function resolveLoadmillCloudCredentials(env = process.env) {
+    const bearerToken = createLoadmillApiClient({
+        token: env.LOADMILL_API_TOKEN,
+        baseUrl: env.LOADMILL_BASE_URL,
+    }).getApiToken();
+    if (!bearerToken) {
+        throw new Error("LOADMILL_API_TOKEN environment variable is not set. It is required for --device-source loadmill-cloud.");
+    }
+    return { bearerToken, baseUrl: env.LOADMILL_BASE_URL || null };
+}

package/build/src/cli/loadmill-cloud-usage.js

@@ -0,0 +1,18 @@
+const NO_USAGE_MESSAGE = "No usage quota configured for your team.";
+function formatMeterLine(meter) {
+    const period = meter?.period ?? "unknown";
+    const minutes = meter?.minutes ?? {};
+    const used = minutes.used;
+    const limit = minutes.limit;
+    const left = minutes.left;
+    const percentageLeft = minutes.percentageLeft ?? meter?.percentageLeft;
+    const percentageLeftLabel = Number.isFinite(percentageLeft) ? `${Math.round(percentageLeft)}%` : "?%";
+    return `Loadmill Cloud usage: ${used} of ${limit} minutes used (${left} left, ${percentageLeftLabel} remaining) [${period}]`;
+}
+export function formatCloudUsageReport(usage) {
+    const meters = Array.isArray(usage?.meters) ? usage.meters : [];
+    if (meters.length === 0) {
+        return [NO_USAGE_MESSAGE];
+    }
+    return meters.map(formatMeterLine);
+}

package/build/src/commands/help.js

@@ -26,6 +26,8 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --device-name <name>   LambdaTest real device name' });
     addOutput({ type: 'info', text: '  --os-version <version> LambdaTest OS version' });
     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: '  --scenario <prompt>    Generate and run scenario cases for headless instructions' });
     addOutput({ type: 'info', text: '  --test-data <file>     Optional test-data.md file for --scenario' });

package/build/src/core/cua-models.js

@@ -13,6 +13,13 @@ export const CUA_MODEL_OPTIONS = Object.freeze([
         name: "Loadmill - Smart",
         label: "Loadmill - Smart (recommended)",
     }),
+    Object.freeze({
+        id: "loadmill-pulse",
+        providerMode: "loadmill",
+        providerLabel: "Loadmill",
+        name: "Loadmill - Pulse",
+        label: "Loadmill - Pulse",
+    }),
     Object.freeze({
         id: "loadmill-beacon",
         providerMode: "loadmill",