@loadmill/droid-cua 2.25.0 → 2.27.0

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

@@ -8,20 +8,35 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { renderHtmlReport } from "../core/report/render-html-report.js";
 import { buildReportFileName } from "../core/report/report-file-name.js";
 import { normalizeEvents, deriveRunStatus, computeSuccessRate, makeFailureOrError, buildRunFinishedPayload, assembleRunReportModel, } from "../core/report/run-report-model.js";
+import { droidReportScreenshotUrl } from "../integrations/loadmill/report-upload-manager.js";
 // Captures the emitted events into `sink` and forwards them to the underlying output
 // function (so console behaviour is unchanged). Maps the engine's `type` to the canonical
 // `kind`; `stepId` is intentionally not collected (the shared normalizer drops it — see R2).
-export function createCapturingAddOutput(underlying, sink) {
+export function createCapturingAddOutput(underlying, sink, { cloudSink = null, uploadManager = null, uploadSession = null } = {}) {
     return (item) => {
         if (item && typeof item === "object") {
-            sink.push({
+            const event = {
                 ts: typeof item.ts === "string" ? item.ts : null,
                 kind: typeof item.type === "string" ? item.type : "info",
                 text: typeof item.text === "string" ? item.text : "",
                 eventType: item.eventType,
                 actionType: item.actionType,
                 payload: item.payload,
-            });
+            };
+            sink?.push(event);
+            if (cloudSink) {
+                const payload = event.payload && typeof event.payload === "object"
+                    ? { ...event.payload }
+                    : event.payload;
+                if (typeof payload?.screenshotDataUrl === "string") {
+                    const screenshotObjectName = uploadManager?.enqueueScreenshot(uploadSession, payload.screenshotDataUrl);
+                    delete payload.screenshotDataUrl;
+                    if (screenshotObjectName) {
+                        payload.screenshotObjectName = screenshotObjectName;
+                    }
+                }
+                cloudSink.push({ ...event, payload });
+            }
         }
         return underlying(item);
     };
@@ -43,7 +58,7 @@ function deriveCounts(success, error, events) {
 // Builds a RunReportModel from captured CLI events plus the run's final stats. This is the
 // CLI-acquisition adapter: it knows how to capture live events + run stats, then delegates
 // ALL model assembly to the shared run-report-model.js (same code path as the XML/Desktop
-// parser). A `run_finished` event is synthesized because the CLI output stream omits one.
+// parser). A `run_finished` event is synthesized when the captured output stream omits one.
 export function buildCliRunReportModel({ suiteName, testName, startedAtIso, durationMs, success, error, instructionsTotal, stats = {}, events, }) {
     const warnings = [];
     const normalizedEvents = normalizeEvents(events, { fallbackTs: startedAtIso ?? null, warnings });
@@ -58,12 +73,15 @@ export function buildCliRunReportModel({ suiteName, testName, startedAtIso, dura
         assertionsFailed: stats.assertionsFailed,
         retries: stats.retryCount,
     });
-    // The synthetic run_finished is already in canonical shape; appended as-is (ts stays null,
-    // matching the historical CLI output) rather than through the normalizer.
-    const allEvents = [
-        ...normalizedEvents,
-        { ts: null, kind: "system", text: "Execution finished", eventType: "run_finished", payload: summaryPayload },
-    ];
+    const hasRunFinished = normalizedEvents.some((event) => event.eventType === "run_finished");
+    // The synthetic run_finished is already in canonical shape; append it as-is (ts stays
+    // null, matching the historical CLI output) only when the producer did not emit one.
+    const allEvents = hasRunFinished
+        ? normalizedEvents
+        : [
+            ...normalizedEvents,
+            { ts: null, kind: "system", text: "Execution finished", eventType: "run_finished", payload: summaryPayload },
+        ];
     const { failures, errors, stopped } = deriveCounts(success, error, allEvents);
     const status = deriveRunStatus({ tests: 1, failures, errors, stopped });
     const successRate = computeSuccessRate({ tests: 1, failures, errors, status });
@@ -97,17 +115,89 @@ export function resolveReportOutputPath({ reportPath, testName, startedAtIso, cw
     }
     return path.join(resolved, fileName);
 }
-// Renders and writes the HTML report for one run. Returns the absolute output path.
-export async function writeCliRunReport(modelInput, { reportPath, cwd = process.cwd(), isBatch = false } = {}) {
+export function createCliRunReport(modelInput) {
     const model = buildCliRunReportModel(modelInput);
+    return {
+        model,
+        html: renderHtmlReport(model),
+        fileName: buildReportFileName({
+            testName: modelInput.testName,
+            suiteName: modelInput.suiteName,
+            timestamp: modelInput.startedAtIso,
+        }),
+    };
+}
+export function createCliAggregateRunReport({ suiteName, testName, startedAtIso, durationMs, childModels, }) {
+    const childTests = childModels.map((model) => ({
+        testName: model.testName ?? "Test",
+        durationSeconds: model.durationSeconds,
+        status: model.status,
+        successRate: model.successRate,
+        failureOrError: model.failureOrError,
+        events: model.events,
+        warnings: model.warnings,
+    }));
+    const failures = childTests.filter((child) => child.status === "fail").length;
+    const errors = childTests.filter((child) => child.status === "error").length;
+    const skipped = childTests.filter((child) => child.status === "skipped").length;
+    const stopped = childTests.some((child) => child.status === "stopped");
+    const status = deriveRunStatus({
+        tests: childTests.length,
+        failures,
+        errors,
+        skipped,
+        stopped,
+    });
+    const model = assembleRunReportModel({
+        suiteName,
+        testName,
+        timestamp: startedAtIso,
+        durationSeconds: Number.isFinite(durationMs) ? durationMs / 1000 : null,
+        status,
+        testCases: childTests.length,
+        successRate: computeSuccessRate({
+            tests: childTests.length,
+            failures,
+            errors,
+            skipped,
+            status,
+        }),
+        events: [],
+        childTests,
+        warnings: [],
+    });
+    return { model, html: renderHtmlReport(model) };
+}
+export function renderCliCloudReport(model, savedRunId) {
+    const cloudModel = structuredClone(model);
+    const replaceScreenshots = (events = []) => {
+        for (const event of events) {
+            const name = event.payload?.screenshotObjectName;
+            if (typeof name === "string") {
+                event.payload.screenshotUrl = droidReportScreenshotUrl(savedRunId, name);
+                delete event.payload.screenshotObjectName;
+            }
+        }
+    };
+    replaceScreenshots(cloudModel.events);
+    for (const child of cloudModel.childTests ?? []) {
+        replaceScreenshots(child.events);
+    }
+    return renderHtmlReport(cloudModel, { includeScripts: false });
+}
+export async function writeCliRunReportArtifact(artifact, { reportPath, cwd = process.cwd(), isBatch = false } = {}) {
     const outputPath = resolveReportOutputPath({
         reportPath,
-        testName: modelInput.testName,
-        startedAtIso: modelInput.startedAtIso,
+        testName: artifact.model.testName,
+        startedAtIso: artifact.model.timestamp,
         cwd,
         isBatch,
     });
     await mkdir(path.dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, renderHtmlReport(model), "utf-8");
+    await writeFile(outputPath, artifact.html, "utf-8");
     return outputPath;
 }
+// Renders and writes the HTML report for one run. Returns the absolute output path.
+export async function writeCliRunReport(modelInput, { reportPath, cwd = process.cwd(), isBatch = false } = {}) {
+    return await writeCliRunReportArtifact(createCliRunReport(modelInput), { reportPath, cwd, isBatch });
+}

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

@@ -7,11 +7,12 @@ import { buildExecutionModePrompt } from "../core/prompts.js";
 import { addOpenAiResponseToDroidCuaRunUsage, createDroidCuaRunUsageTotals, estimateDroidCuaRunCostUsd, setDroidCuaRunUsageModel, } from "../core/droid-cua-run-usage.js";
 import { ExecutionMode } from "../modes/execution-mode.js";
 import { reportDroidRunCompletion } from "../integrations/loadmill/run-reporter.js";
+import { droidReportUploadManager } from "../integrations/loadmill/report-upload-manager.js";
 import { reportDroidCuaCiTestRunCompleted } from "../integrations/segment/droid-cua-segment.js";
 import { printCliOutput } from "../utils/console-output.js";
 import { emitDesktopDebug } from "../utils/desktop-debug.js";
 import { loadHeadlessInstructions } from "./headless-instructions.js";
-import { createCapturingAddOutput, writeCliRunReport } from "./headless-report.js";
+import { buildCliRunReportModel, createCapturingAddOutput, createCliAggregateRunReport, createCliRunReport, renderCliCloudReport, writeCliRunReportArtifact, } from "./headless-report.js";
 function sanitizePathSegment(value) {
     return String(value || "test")
         .replace(/\.dcua$/i, "")
@@ -24,6 +25,14 @@ function createHeadlessRunId(index = 0) {
     const suffix = index > 0 ? `-${index + 1}` : "";
     return `run-${Date.now()}${suffix}`;
 }
+function logPendingScreenshotUploads(uploadManager, uploadSession, subject) {
+    console.log('Verifying no pending upload exists');
+    const pendingCount = uploadManager.getPendingCount?.(uploadSession) ?? 0;
+    if (pendingCount > 0) {
+        const uploads = pendingCount === 1 ? "upload" : "uploads";
+        console.log(`${subject} finished. Waiting for ${pendingCount} screenshot ${uploads} to finish...`);
+    }
+}
 function getRecordScreenshotDirForTest(baseScreenshotDir, testName, isBatchRun) {
     if (!baseScreenshotDir || !isBatchRun) {
         return baseScreenshotDir;
@@ -122,7 +131,7 @@ function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionP
     }
     return engineOptions;
 }
-async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, secrets = null, report = null, isBatchRun = false, reportToLoadmill = true }) {
+async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, secrets = null, report = null, isBatchRun = false, reportToLoadmill = true, cloudUploadSession = null, uploadManager = droidReportUploadManager, }) {
     let executionMode = null;
     let loadmillSessionUser = null;
     let runUsageTotals = setDroidCuaRunUsageModel(createDroidCuaRunUsageTotals(), runtimeContext.config.cuaModel);
@@ -142,10 +151,17 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             ...buildSegmentUsageProperties(),
         });
     };
-    const reportEnabled = Boolean(report?.enabled);
-    const collectedEvents = [];
+    const localReportEnabled = Boolean(report?.enabled);
+    const cloudReportEnabled = Boolean(cloudUploadSession);
+    const reportEnabled = localReportEnabled || cloudReportEnabled;
+    const localEvents = [];
+    const cloudEvents = [];
     const addOutput = reportEnabled
-        ? createCapturingAddOutput(printCliOutput, collectedEvents)
+        ? createCapturingAddOutput(printCliOutput, localReportEnabled ? localEvents : null, {
+            cloudSink: cloudReportEnabled ? cloudEvents : null,
+            uploadManager,
+            uploadSession: cloudUploadSession,
+        })
         : printCliOutput;
     try {
         try {
@@ -166,7 +182,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);
@@ -176,6 +191,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             testDataContext,
             availableSecretKeys: secrets?.availableSecretKeys || [],
             cuaModel: runtimeContext.config.cuaModel,
+            explainMode: runtimeContext.config.explainMode,
         });
         session.setSystemPrompt(executionPrompt);
         const screenshotRecorder = headlessDebug.createExecutionScreenshotRecorder({
@@ -227,8 +243,9 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             durationMs,
             numOfSteps: instructions.length,
         });
+        let reportedRun = null;
         if (reportToLoadmill) {
-            await reportDroidRunCompletion({
+            reportedRun = await reportDroidRunCompletion({
                 loadmillClient: runtimeContext.loadmillClient,
                 source: "ci",
                 runId,
@@ -256,19 +273,19 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         if (!result.success) {
             console.error(`\nTest failed: ${result.error}`);
         }
-        if (reportEnabled) {
+        const reportInput = {
+            suiteName: path.basename(path.dirname(testPath)) || null,
+            testName,
+            startedAtIso: stats.startTime ? new Date(stats.startTime).toISOString() : null,
+            durationMs,
+            success: Boolean(result.success),
+            error: result.error ?? null,
+            instructionsTotal: instructions.length,
+            stats,
+        };
+        if (localReportEnabled) {
             try {
-                const outputPath = await writeCliRunReport({
-                    suiteName: path.basename(path.dirname(testPath)) || null,
-                    testName,
-                    startedAtIso: stats.startTime ? new Date(stats.startTime).toISOString() : null,
-                    durationMs,
-                    success: Boolean(result.success),
-                    error: result.error ?? null,
-                    instructionsTotal: instructions.length,
-                    stats,
-                    events: collectedEvents,
-                }, { reportPath: report?.path ?? null, isBatch: isBatchRun });
+                const outputPath = await writeCliRunReportArtifact(createCliRunReport({ ...reportInput, events: localEvents }), { reportPath: report?.path ?? null, isBatch: isBatchRun });
                 console.log(`HTML report saved: ${outputPath}`);
             }
             catch (reportError) {
@@ -276,6 +293,16 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
                 console.warn(`Warning: failed to write HTML report: ${message}`);
             }
         }
+        const cloudModel = cloudReportEnabled
+            ? buildCliRunReportModel({ ...reportInput, events: cloudEvents })
+            : null;
+        if (cloudModel && reportToLoadmill && reportedRun?.savedRunId) {
+            logPendingScreenshotUploads(uploadManager, cloudUploadSession, "Test");
+            await uploadManager.finish(cloudUploadSession, {
+                savedRunId: reportedRun.savedRunId,
+                html: renderCliCloudReport(cloudModel, reportedRun.savedRunId),
+            });
+        }
         return {
             success: Boolean(result.success),
             error: result.error ?? null,
@@ -285,7 +312,8 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             actionsTotal: stats.actionCount ?? 0,
             assertionsPassed: stats.assertionsPassed ?? 0,
             assertionsFailed: stats.assertionsFailed ?? 0,
-            retries: stats.retryCount ?? 0
+            retries: stats.retryCount ?? 0,
+            reportModel: cloudModel,
         };
     }
     catch (error) {
@@ -312,8 +340,9 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             durationMs,
             numOfSteps: instructions.length,
         });
+        let reportedRun = null;
         if (reportToLoadmill) {
-            await reportDroidRunCompletion({
+            reportedRun = await reportDroidRunCompletion({
                 loadmillClient: runtimeContext.loadmillClient,
                 source: "ci",
                 runId,
@@ -338,11 +367,63 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
                 onWarning: (warningMessage) => console.warn(`Warning: ${warningMessage}`),
             });
         }
+        const failedReportInput = {
+            suiteName: path.basename(path.dirname(testPath)) || null,
+            testName,
+            startedAtIso: stats.startTime ? new Date(stats.startTime).toISOString() : null,
+            durationMs,
+            success: false,
+            error: message,
+            instructionsTotal: instructions.length,
+            stats,
+        };
+        if (localReportEnabled) {
+            try {
+                const outputPath = await writeCliRunReportArtifact(createCliRunReport({ ...failedReportInput, events: localEvents }), { reportPath: report?.path ?? null, isBatch: isBatchRun });
+                console.log(`HTML report saved: ${outputPath}`);
+            }
+            catch (reportError) {
+                console.warn(`Warning: failed to write HTML report: ${reportError instanceof Error ? reportError.message : String(reportError)}`);
+            }
+        }
+        const cloudModel = cloudReportEnabled
+            ? buildCliRunReportModel({ ...failedReportInput, events: cloudEvents })
+            : null;
+        if (cloudModel && reportToLoadmill && reportedRun?.savedRunId) {
+            logPendingScreenshotUploads(uploadManager, cloudUploadSession, "Test");
+            await uploadManager.finish(cloudUploadSession, {
+                savedRunId: reportedRun.savedRunId,
+                html: renderCliCloudReport(cloudModel, reportedRun.savedRunId),
+            });
+        }
+        if (!reportToLoadmill) {
+            console.error(`\nTest failed: ${testName}: ${message}`);
+            return {
+                success: false,
+                error: message,
+                durationMs,
+                instructionsTotal: instructions.length,
+                instructionsCompleted: stats.instructionsCompleted ?? 0,
+                actionsTotal: stats.actionCount ?? 0,
+                assertionsPassed: stats.assertionsPassed ?? 0,
+                assertionsFailed: stats.assertionsFailed ?? 0,
+                retries: stats.retryCount ?? 0,
+                reportModel: cloudModel,
+            };
+        }
         throw error;
     }
 }
-export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, secrets = null, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, report = null, runHeadlessTestImpl = runHeadlessTest }) {
+export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, secrets = null, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, report = null, runHeadlessTestImpl = runHeadlessTest, uploadManager = droidReportUploadManager, }) {
     const isBatchRun = instructionsTarget?.type === "directory" || instructionsTarget?.type === "scenario";
+    const cloudReportEnabled = report?.cloudEnabled !== false &&
+        Boolean(runtimeContext.loadmillClient?.getApiToken?.());
+    const cloudUploadSession = cloudReportEnabled
+        ? uploadManager.startSession({
+            loadmillClient: runtimeContext.loadmillClient,
+            onWarning: (message) => console.warn(`Warning: ${message}`),
+        })
+        : null;
     if (instructionsTarget?.type === "scenario") {
         console.log(`\nRunning ${runs.length} scenario case${runs.length === 1 ? "" : "s"}\n`);
     }
@@ -360,6 +441,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
         assertionsFailed: 0,
         retries: 0
     };
+    const aggregateReportModels = [];
     for (const [index, run] of runs.entries()) {
         const runId = createHeadlessRunId(index);
         const testScreenshotDir = getRecordScreenshotDirForTest(screenshotDir, run.testName, isBatchRun);
@@ -390,7 +472,9 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
                 isCloudTarget,
                 report,
                 isBatchRun,
-                reportToLoadmill: !isBatchRun
+                reportToLoadmill: !isBatchRun,
+                cloudUploadSession,
+                uploadManager,
             });
             aggregateStats.durationMs += result.durationMs ?? 0;
             aggregateStats.instructionsTotal += result.instructionsTotal ?? 0;
@@ -399,6 +483,9 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             aggregateStats.assertionsPassed += result.assertionsPassed ?? 0;
             aggregateStats.assertionsFailed += result.assertionsFailed ?? 0;
             aggregateStats.retries += result.retries ?? 0;
+            if (result.reportModel) {
+                aggregateReportModels.push(result.reportModel);
+            }
             if (!result.success) {
                 failures += 1;
             }
@@ -423,7 +510,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
     if (isBatchRun) {
         const isScenario = instructionsTarget?.type === "scenario";
         const testName = isScenario ? "Scenario run" : path.basename(instructionsTarget.path);
-        await reportDroidRunCompletion({
+        const reportedRun = await reportDroidRunCompletion({
             loadmillClient: runtimeContext.loadmillClient,
             source: "ci",
             runId: createHeadlessRunId(),
@@ -448,6 +535,20 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             retries: aggregateStats.retries,
             onWarning: (message) => console.warn(`Warning: ${message}`),
         });
+        if (cloudUploadSession && reportedRun.savedRunId) {
+            const aggregateReport = createCliAggregateRunReport({
+                suiteName: isScenario ? path.basename(process.cwd()) : path.basename(instructionsTarget.path),
+                testName,
+                startedAtIso: new Date(batchStartedAt).toISOString(),
+                durationMs: Math.max(aggregateStats.durationMs, Date.now() - batchStartedAt),
+                childModels: aggregateReportModels,
+            });
+            logPendingScreenshotUploads(uploadManager, cloudUploadSession, "Run");
+            await uploadManager.finish(cloudUploadSession, {
+                savedRunId: reportedRun.savedRunId,
+                html: renderCliCloudReport(aggregateReport.model, reportedRun.savedRunId),
+            });
+        }
     }
     return {
         exitCode: failures === 0 ? 0 : 1,

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' });
@@ -44,6 +46,9 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --base-prompt-file     Headless base prompt customization file' });
     addOutput({ type: 'info', text: '  --execution-prompt-file Headless execution prompt customization file' });
     addOutput({ type: 'info', text: '  --record               Record screenshots during execution' });
+    addOutput({ type: 'info', text: '  --explain              Explain non-obvious decisions and completion evidence' });
+    addOutput({ type: 'info', text: '  --report [path]        Save a self-contained HTML report locally' });
+    addOutput({ type: 'info', text: '  --no-cloud-report      Skip uploading the HTML report and screenshots to Loadmill' });
     addOutput({ type: 'info', text: '  --debug                Enable structured JSONL debug artifacts' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Interactive commands:' });

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",