@loadmill/droid-cua 2.26.0 → 2.28.0

package/README.md

@@ -101,6 +101,7 @@ Desktop app support:
 - **Live execution logs** - Watch actions and progress as tests run
 - **Reports and history** - Review past runs from a project results folder inside the desktop app
 - **JUnit XML output** - Write standard test reports for CI systems and external tooling
+- **Run video export** - Generate and download a polished MP4 replay from a desktop run's screenshots and instruction timeline
 - **Headless support** - Reuse scripts in CLI and automation workflows
 
 ---
@@ -250,6 +251,7 @@ Supported CLI options include:
 - `--no-context`
 - `--context-optimization-threshold`
 - `--no-context-optimization`
+- `--explain`
 - `--base-prompt`
 - `--execution-prompt`
 - `--base-prompt-file`
@@ -257,6 +259,7 @@ Supported CLI options include:
 - `--secrets`
 - `--record`
 - `--report`
+- `--no-cloud-report`
 - `--debug`
 
 `--cua-model` accepts `loadmill-smart`, `loadmill-pulse`, `loadmill-beacon`,
@@ -271,6 +274,8 @@ Config and precedence rules:
 - Context Optimization is enabled by default with a `30000` input-token threshold.
 - `--context-optimization-threshold <tokens>` sets the threshold and enables Context Optimization.
 - `--no-context-optimization` disables Context Optimization.
+- `--explain` enables Explain Mode for the run. Explain Mode asks the agent for concise explanations of non-obvious decisions, skipped actions, and completion evidence; explanations appear in terminal output and reports.
+- Set `"explainMode": true` in the JSON config to enable the same behavior without a flag. Explain Mode is off by default, and `--explain` enables it when the config leaves it off.
 - `--base-prompt` and `--execution-prompt` let you pass prompt customizations inline on the command line.
 - `--base-prompt-file` and `--execution-prompt-file` override the corresponding prompt customizations from config.
 - If both inline and file-based prompt overrides are provided, the inline prompt flags win.
@@ -286,6 +291,8 @@ 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.
 - In the desktop app the same report is available from a run's **Share → Download HTML report** button.
+- Runs with captured screenshots also expose **Share → Generate video**. The desktop app renders a square mobile replay or 16:9 browser replay locally, then prompts for a save location using `<test>--<date>--<time>--test-replay.mp4` as the suggested filename.
+- Authenticated headless runs upload their HTML report and screenshots to Loadmill by default. Use `--no-cloud-report` to disable that artifact upload. The basic Droid run row is still reported to Loadmill.
 
 ```sh
 droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua --report ./reports

package/build/index.js

@@ -31,6 +31,7 @@ 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 { droidReportUploadManager } from "./src/integrations/loadmill/report-upload-manager.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";
@@ -78,6 +79,7 @@ const debugMode = args["debug"] || false;
 const reportConfig = {
     enabled: args.report === true || (typeof args.report === "string" && args.report.trim().length > 0),
     path: typeof args.report === "string" && args.report.trim().length > 0 ? args.report.trim() : null,
+    cloudEnabled: args["no-cloud-report"] !== true,
 };
 const screenshotDir = path.join("droid-cua-recording-" + Date.now());
 if (recordScreenshots)
@@ -618,6 +620,7 @@ async function main() {
             const runtimeContext = createCliRuntimeContext({
                 llmProviderMode: headlessConfig.llmProviderMode,
                 cuaModel: headlessConfig.cuaModel,
+                explainMode: headlessConfig.explainMode,
                 promptCustomizations: headlessConfig.promptCustomizations,
                 contextOptimizationEnabled: headlessConfig.contextOptimizationEnabled,
                 contextOptimizationThreshold: headlessConfig.contextOptimizationThreshold,
@@ -671,6 +674,7 @@ async function main() {
             succeeded = true;
         }
         finally {
+            await droidReportUploadManager.drain();
             if (lambdaTestSessionConnected) {
                 console.log("Ending LambdaTest session...");
                 await disconnectDevice();

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

@@ -129,6 +129,7 @@ async function loadConfigFromFile(configPath) {
         llmProviderMode: undefined,
         cuaModel: undefined,
         aimAssistMode: undefined,
+        explainMode: undefined,
         promptCustomizations: createEmptyPromptCustomizations(),
         appContextEnabled: undefined,
         appContextPath: undefined,
@@ -144,6 +145,12 @@ async function loadConfigFromFile(configPath) {
     if ("aimAssistMode" in rawConfig) {
         normalized.aimAssistMode = validateAimAssistMode(rawConfig.aimAssistMode, "config.aimAssistMode");
     }
+    if ("explainMode" in rawConfig) {
+        if (typeof rawConfig.explainMode !== "boolean") {
+            throw new Error("config.explainMode must be a boolean.");
+        }
+        normalized.explainMode = rawConfig.explainMode;
+    }
     if ("promptCustomizations" in rawConfig) {
         normalized.promptCustomizations = normalizePromptCustomizations(rawConfig.promptCustomizations, "config.promptCustomizations");
     }
@@ -217,6 +224,7 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         llmProviderMode: fileConfig?.llmProviderMode || readEnvDefaultLlmProviderMode(),
         cuaModel: fileConfig?.cuaModel || readEnvDefaultCuaModel(),
         aimAssistMode: fileConfig?.aimAssistMode || DEFAULT_AIM_ASSIST_MODE,
+        explainMode: fileConfig?.explainMode ?? false,
         promptCustomizations,
         appContextEnabled: fileConfig?.appContextEnabled ?? true,
         appContextPath: fileConfig?.appContextPath || null,
@@ -235,6 +243,9 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     if (typeof args["aim-assist"] === "string") {
         resolved.aimAssistMode = validateAimAssistMode(args["aim-assist"], "--aim-assist");
     }
+    if (args.explain === true) {
+        resolved.explainMode = true;
+    }
     if (hasContextOptimizationThresholdFlag) {
         resolved.contextOptimizationEnabled = true;
         resolved.contextOptimizationThreshold = parseContextOptimizationThreshold(args["context-optimization-threshold"], "--context-optimization-threshold");

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 {
@@ -175,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({
@@ -226,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,
@@ -255,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) {
@@ -275,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,
@@ -284,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) {
@@ -311,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,
@@ -337,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`);
     }
@@ -359,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);
@@ -389,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;
@@ -398,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;
             }
@@ -422,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(),
@@ -447,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/commands/help.js

@@ -46,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/execution-engine.js

@@ -399,7 +399,7 @@ export class ExecutionEngine {
                 eventId: actionEventId,
                 captureSource: CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION
             });
-            // Inline the green click marker as a data URL so self-contained reports show it.
+            // Inline the accent-colored click marker as a data URL so self-contained reports show it.
             // The Desktop recorder returns one from disk; for runs without a recorder (e.g. a
             // plain CLI `--report`) render the same marker in-memory from the raw screenshot.
             const annotatedDataUrl = await this.resolveAnnotatedDataUrl(annotatedScreenshot, currentScreenshot, action, context);
@@ -526,7 +526,7 @@ export class ExecutionEngine {
                         type: "assistant",
                         text: textPart.text,
                         eventType: "assistant_message",
-                        ...eventMeta(),
+                        ...eventMeta(options.explainMode ? { payload: { explainMode: true } } : {}),
                     });
                 }
                 this.session.addToTranscript(`[Assistant] ${textPart.text}`);
@@ -689,7 +689,10 @@ export class ExecutionEngine {
             const items = response.output || [];
             const actionableItems = extractActionableOutputItems(items);
             const pendingSafetyChecks = collectPendingSafetyChecks(items);
-            this.emitResponseOutputItems(items, addOutput, eventMeta, options);
+            this.emitResponseOutputItems(items, addOutput, eventMeta, {
+                ...options,
+                explainMode: options.explainMode === true || context?.runtimeConfig?.explainMode === true,
+            });
             if (actionableItems.length === 0) {
                 // No actions = turn complete
                 break;

package/build/src/core/report/render-html-report.js

@@ -83,13 +83,60 @@ function buildVisibleEvents(events) {
 // full-size lightbox overlay can be rendered. The href links to the CSS `:target`
 // overlay, so click-to-enlarge works even with JavaScript disabled.
 function screenshotImg(event, shots) {
-    const url = event.payload?.screenshotDataUrl;
-    if (typeof url !== "string" || !url.startsWith("data:"))
+    const url = event.payload?.screenshotDataUrl ?? event.payload?.screenshotUrl;
+    const isAllowedUrl = typeof url === "string" &&
+        (url.startsWith("data:") || url.startsWith("/api/droid-cua/runs/"));
+    if (!isAllowedUrl)
         return "";
     const index = shots.length + 1;
     shots.push({ index, url });
     return `<a class="dc-shot-link" href="#dc-shot-${index}" aria-label="Open screenshot ${index}"><img class="dc-shot" src="${escapeHtml(url)}" alt="Screenshot ${index}" /></a>`;
 }
+function icon(name, shapes) {
+    return `<svg class="dc-icon" data-icon="${name}" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${shapes}</svg>`;
+}
+const ICONS = {
+    arrowUpDown: icon("arrow-up-down", `<path d="m21 16-4 4-4-4"/><path d="M17 20V4"/><path d="m3 8 4-4 4 4"/><path d="M7 4v16"/>`),
+    botMessageSquare: icon("bot-message-square", `<path d="M12 6V2H8"/><path d="m8 18-4 4V8a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2Z"/><path d="M2 12h2"/><path d="M9 11v2"/><path d="M15 11v2"/><path d="M20 12h2"/>`),
+    camera: icon("camera", `<path d="M14.5 4h-5L7 7H4a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-3l-2.5-3z"/><circle cx="12" cy="13" r="3"/>`),
+    compass: icon("compass", `<path d="m16.24 7.76-1.804 5.411a2 2 0 0 1-1.265 1.265L7.76 16.24l1.804-5.411a2 2 0 0 1 1.265-1.265z"/><circle cx="12" cy="12" r="10"/>`),
+    flag: icon("flag", `<path d="M4 15s1-1 4-1 5 2 8 2 4-1 4-1V3s-1 1-4 1-5-2-8-2-4 1-4 1z"/><line x1="4" x2="4" y1="22" y2="15"/>`),
+    keyboard: icon("keyboard", `<path d="M10 8h.01"/><path d="M12 12h.01"/><path d="M14 8h.01"/><path d="M16 12h.01"/><path d="M18 8h.01"/><path d="M6 8h.01"/><path d="M7 16h10"/><path d="M8 12h.01"/><rect width="20" height="16" x="2" y="4" rx="2"/>`),
+    keyboardOff: icon("keyboard-off", `<path d="M20 4a2 2 0 0 1 2 2"/><path d="M22 6v10.41"/><path d="M7 16h9"/><path d="M9.69 4H20"/><path d="M14 8h.01"/><path d="M18 8h.01"/><path d="m2 2 20 20"/><path d="M20 20H4a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2"/><path d="M6 8h.01"/><path d="M8 12h.01"/>`),
+    keyRound: icon("key-round", `<path d="M2.586 17.414A2 2 0 0 0 2 18.828V21a1 1 0 0 0 1 1h3a1 1 0 0 0 1-1v-1a1 1 0 0 1 1-1h1a1 1 0 0 0 1-1v-1a1 1 0 0 1 1-1h.172a2 2 0 0 0 1.414-.586l.814-.814a6.5 6.5 0 1 0-4-4z"/><circle cx="16.5" cy="7.5" r=".5" fill="currentColor"/>`),
+    mousePointer: icon("mouse-pointer-2", `<path d="M4.037 4.688a.495.495 0 0 1 .651-.651l16 6.5a.5.5 0 0 1-.063.947l-6.124 1.58a2 2 0 0 0-1.438 1.435l-1.579 6.126a.5.5 0 0 1-.947.063z"/>`),
+    moveDiagonal: icon("move-diagonal-2", `<path d="M19 13v6h-6"/><path d="M5 11V5h6"/><path d="m5 5 14 14"/>`),
+    rotateCcw: icon("rotate-ccw", `<path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/>`),
+    squareX: icon("square-x", `<rect width="18" height="18" x="3" y="3" rx="2"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/>`),
+    timer: icon("timer", `<line x1="10" x2="14" y1="2" y2="2"/><line x1="12" x2="15" y1="14" y2="11"/><circle cx="12" cy="14" r="8"/>`),
+};
+function actionIcon(event) {
+    const lowerText = event.text.toLowerCase();
+    const toolName = typeof event.payload?.toolName === "string" ? event.payload.toolName : null;
+    const isSensitiveTyping = Boolean(event.payload?.sensitive) || lowerText.includes("typing secret");
+    if (toolName === "navigate")
+        return ICONS.compass;
+    if (toolName === "close_current_tab")
+        return ICONS.squareX;
+    if (toolName === "close_keyboard")
+        return ICONS.keyboardOff;
+    if (isSensitiveTyping)
+        return ICONS.keyRound;
+    if (event.actionType === "type" || event.actionType === "keypress" || lowerText.includes("typing"))
+        return ICONS.keyboard;
+    if (event.actionType === "scroll" || lowerText.includes("scroll"))
+        return ICONS.arrowUpDown;
+    if (event.actionType === "drag" || lowerText.includes("drag"))
+        return ICONS.moveDiagonal;
+    if (event.actionType === "screenshot" || lowerText.includes("capturing screen"))
+        return ICONS.camera;
+    if (event.actionType === "wait" || lowerText.includes("waiting"))
+        return ICONS.timer;
+    return ICONS.mousePointer;
+}
+function renderAgentText(text) {
+    return `<div class="dc-line dc-agent-line">${ICONS.botMessageSquare}<span>${escapeHtml(text)}</span></div>`;
+}
 // ---------- per-event timeline rendering (mirrors ExecutionLogItem.tsx) ----------
 function renderEvent(event, shots) {
     if (isHiddenExecutionLogEvent(event))
@@ -123,10 +170,16 @@ function renderEvent(event, shots) {
     if (isAssistant) {
         const stepCompletion = stepCompletionData(event);
         if (stepCompletion) {
+            if (event.payload?.explainMode === true) {
+                return `<div class="dc-line">${ICONS.flag}<span>Step complete</span></div>\n${renderAgentText(stepCompletion.reason)}`;
+            }
             const tooltip = stepCompletionReasonTooltip(stepCompletion);
-            return `<div class="dc-line"${tooltip ? ` title="${escapeHtml(tooltip)}"` : ""}><span aria-hidden="true">&#9873;</span><span>Step complete</span></div>`;
+            return `<div class="dc-line"${tooltip ? ` title="${escapeHtml(tooltip)}"` : ""}>${ICONS.flag}<span>Step complete</span></div>`;
         }
-        return `<div class="dc-assistant">${escapeHtml(event.text)}</div>`;
+        return renderAgentText(event.text);
+    }
+    if (event.eventType === "reasoning" || event.kind === "reasoning") {
+        return renderAgentText(event.text);
     }
     const assertion = assertionData(event);
     if (assertion) {
@@ -138,13 +191,13 @@ function renderEvent(event, shots) {
 </div>`;
     }
     if (event.eventType === "retry") {
-        return `<div class="dc-line dc-retry">${escapeHtml(event.text)}</div>`;
+        return `<div class="dc-line dc-retry">${ICONS.rotateCcw}<span>${escapeHtml(event.text)}</span></div>`;
     }
     if (event.kind === "action") {
-        return `<div class="dc-line">${escapeHtml(event.text)}${screenshotImg(event, shots)}</div>`;
+        return `<div class="dc-line">${actionIcon(event)}<span>${escapeHtml(event.text)}</span>${screenshotImg(event, shots)}</div>`;
     }
     if (event.eventType === "screenshot_captured") {
-        return `<div class="dc-line">${escapeHtml(event.text)}${screenshotImg(event, shots)}</div>`;
+        return `<div class="dc-line">${ICONS.camera}<span>${escapeHtml(event.text)}</span>${screenshotImg(event, shots)}</div>`;
     }
     return `<div class="dc-line dc-${escapeHtml(event.kind)}">${escapeHtml(event.text)}</div>`;
 }
@@ -243,13 +296,16 @@ body { margin: 0; background: #f1f5f9; color: #0f172a; font-family: -apple-syste
 .dc-row { display: flex; }
 .dc-row-right { justify-content: flex-end; }
 .dc-bubble { display: inline-block; max-width: 70%; background: #f1f5f9; border: 1px solid #e2e8f0; border-radius: 16px; border-bottom-right-radius: 6px; padding: 8px 14px; color: #0f172a; }
-.dc-assistant { max-width: 82%; color: #334155; }
 .dc-line { display: flex; align-items: center; gap: 8px; color: #475569; }
+.dc-agent-line { align-items: flex-start; }
+.dc-agent-line .dc-icon { margin-top: 4px; }
+.dc-icon { width: 14px; height: 14px; flex: 0 0 auto; color: #94a3b8; }
 .dc-retry { color: #b45309; }
 .dc-error { color: #b91c1c; }
 .dc-warning { color: #b45309; }
-.dc-shot-link { display: inline-flex; margin-left: 8px; vertical-align: middle; }
-.dc-shot { height: 34px; width: auto; border: 1px solid #e2e8f0; border-radius: 4px; cursor: zoom-in; transition: border-color .12s; }
+.dc-shot-link { display: inline-flex; align-items: center; justify-content: center; position: relative; min-width: 34px; min-height: 36px; margin-left: 8px; vertical-align: middle; }
+.dc-shot-link::before, .dc-lightbox:target::before { content: ""; position: absolute; width: 14px; height: 14px; border: 2px solid #cbd5e1; border-top-color: #475569; border-radius: 50%; animation: dc-spin .7s linear infinite; }
+.dc-shot { position: relative; z-index: 1; height: 34px; width: auto; border: 1px solid #e2e8f0; border-radius: 4px; cursor: zoom-in; transition: border-color .12s; }
 .dc-shot-link:hover .dc-shot, .dc-shot-link:focus-visible .dc-shot { border-color: #94a3b8; }
 .dc-lightbox { display: none; position: fixed; inset: 0; z-index: 1000; align-items: center; justify-content: center; padding: 32px; background: rgba(15, 23, 42, .82); }
 .dc-lightbox:target { display: flex; }
@@ -275,9 +331,10 @@ body { margin: 0; background: #f1f5f9; color: #0f172a; font-family: -apple-syste
 .dc-pill-error, .dc-pill-errored, .dc-pill-amber { border-color: #fcd34d; background: #fef3c7; color: #b45309; }
 .dc-pill-stopped { border-color: #fdba74; background: #ffedd5; color: #c2410c; }
 .dc-pill-skipped { border-color: #cbd5e1; background: #f1f5f9; color: #334155; }
+@keyframes dc-spin { to { transform: rotate(360deg); } }
 `.trim();
 // ---------- entry point ----------
-export function renderHtmlReport(model, { title } = {}) {
+export function renderHtmlReport(model, { title, includeScripts = true } = {}) {
     const docTitle = title ?? `Run Report: ${model.testName ?? model.suiteName ?? "Test run"}`;
     const heading = model.testName ?? model.suiteName ?? "Test run";
     // Screenshots are collected across the whole document (top-level + child timelines)
@@ -301,7 +358,7 @@ ${renderTimeline(model.events, shots)}
 </div>`;
     }
     const lightboxes = renderLightboxes(shots);
-    const script = renderLightboxScript(shots.length);
+    const script = includeScripts ? renderLightboxScript(shots.length) : "";
     return `<!DOCTYPE html>
 <html lang="en">
 <head>

package/build/src/core/runtime-config.js

@@ -123,7 +123,7 @@ export function resolveRuntimeCredentials({ openAiApiKey = null, loadmillApiToke
         loadmillBaseUrl: normalizeLoadmillSiteBaseUrl(loadmillBaseUrl),
     };
 }
-export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null, stepDelayMs = undefined, contextOptimizationEnabled = undefined, contextOptimizationThreshold = undefined, promptCustomizations = null, appContext = null, } = {}) {
+export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null, explainMode = false, stepDelayMs = undefined, contextOptimizationEnabled = undefined, contextOptimizationThreshold = undefined, promptCustomizations = null, appContext = null, } = {}) {
     const normalizedCuaModel = typeof cuaModel === "string" && LOADMILL_MODEL_ALIAS_SET.has(cuaModel)
         ? cuaModel
         : resolveCuaModel(cuaModel);
@@ -133,6 +133,7 @@ export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null,
             ? "loadmill"
             : normalizedProviderMode,
         cuaModel: normalizedCuaModel,
+        explainMode: explainMode === true,
         stepDelayMs: normalizeStepDelayMs(Number(stepDelayMs)),
         contextOptimizationEnabled: normalizeContextOptimizationEnabled(contextOptimizationEnabled),
         contextOptimizationThreshold: normalizeContextOptimizationThreshold(contextOptimizationThreshold),

package/build/src/core/tool-handlers/loadmill.js

@@ -1,4 +1,29 @@
 import { buildTextToolOutputItem, parseStringToolArgument } from "./utils.js";
+import { emitDesktopDebug } from "../../utils/desktop-debug.js";
+function emitLoadmillToolCall({ callId, argumentsText, command, context, stepContext }) {
+    const scope = context?.sessionId ? "design" : "execution";
+    const ids = {
+        ...(scope === "design" ? { sessionId: context?.sessionId } : { runId: context?.runId }),
+        ...(stepContext?.stepId ? { stepId: stepContext.stepId } : {}),
+        ...(Number.isInteger(stepContext?.instructionIndex) ? { instructionIndex: stepContext.instructionIndex } : {}),
+    };
+    const payload = {
+        toolName: "loadmill",
+        callId,
+        command,
+        arguments: argumentsText,
+    };
+    emitDesktopDebug("tool_call", scope, ids, payload);
+    context?.addOutput?.({
+        type: "muted",
+        text: `Running Loadmill flow: ${command}`,
+        eventType: "tool_call",
+        runId: context?.runId,
+        stepId: stepContext?.stepId,
+        instructionIndex: stepContext?.instructionIndex,
+        payload,
+    });
+}
 export async function handleLoadmillToolCall({ engine, callId, argumentsText, context = null, stepContext = null }) {
     const session = engine.session;
     const parsed = parseStringToolArgument(argumentsText, "command", "loadmill");
@@ -9,6 +34,13 @@ export async function handleLoadmillToolCall({ engine, callId, argumentsText, co
         };
     }
     const loadmillCommand = parsed.value;
+    emitLoadmillToolCall({
+        callId,
+        argumentsText,
+        command: loadmillCommand,
+        context,
+        stepContext,
+    });
     session.addToTranscript(`[Loadmill] ${loadmillCommand}`);
     const result = await engine.executeLoadmillInstruction(loadmillCommand, engine.isHeadlessMode, {
         ...context,

package/build/src/device/assertions.js

@@ -2,6 +2,7 @@
  * Assertion handling for script validation
  */
 import { printCliOutput } from "../utils/console-output.js";
+import { CAPTURE_SOURCES } from "../core/capture-sources.js";
 export { buildAssertionSystemPrompt } from "../prompts/execution.js";
 const ASSERTION_PREFIXES = ["assert", "verify", "validate", "ensure"];
 function hasAssertionPrefix(lower) {
@@ -54,6 +55,7 @@ export function handleAssertionFailure(assertionPrompt, transcript, isHeadlessMo
             assertion: assertionPrompt,
             passed: false,
             details,
+            captureSource: CAPTURE_SOURCES.INSTRUCTION_INPUT_ASSERTION,
             ...eventPayload
         }
     };
@@ -77,6 +79,7 @@ export function handleAssertionSuccess(assertionPrompt, context = null, stepCont
         payload: {
             assertion: assertionPrompt,
             passed: true,
+            captureSource: CAPTURE_SOURCES.INSTRUCTION_INPUT_ASSERTION,
             ...eventPayload
         }
     });

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

@@ -138,6 +138,18 @@ export function createLoadmillApiClient({ token = null, baseUrl = null, onUnauth
             body: JSON.stringify(payload),
         });
     }
+    async function requestDroidRunReportUploadPolicy(uploadId, payload) {
+        return await apiRequest(`/droid-cua/report-uploads/${uploadId}/policy`, {
+            method: "POST",
+            body: JSON.stringify(payload),
+        });
+    }
+    async function associateDroidRunReport(runId, payload) {
+        return await apiRequest(`/droid-cua/runs/${runId}/report`, {
+            method: "POST",
+            body: JSON.stringify(payload),
+        });
+    }
     async function validateApiToken() {
         const resolvedToken = getApiToken();
         if (!resolvedToken) {
@@ -187,6 +199,8 @@ export function createLoadmillApiClient({ token = null, baseUrl = null, onUnauth
         getTestSuiteFlowRun,
         explainFailure,
         reportDroidRun,
+        requestDroidRunReportUploadPolicy,
+        associateDroidRunReport,
         validateApiToken,
         getCurrentUser,
     };

package/build/src/integrations/loadmill/report-upload-manager.js

@@ -0,0 +1,221 @@
+import { createHash, randomUUID } from "node:crypto";
+export const MAX_SCREENSHOTS_PER_REPORT = 1000;
+export const MAX_REPORT_OBJECT_BYTES = 10 * 1024 * 1024;
+function warn(session, message) {
+    session.failed = true;
+    session.onWarning?.(message);
+}
+function getHttpStatus(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /\((\d{3})\)/.exec(message)?.[1] ?? null;
+}
+function warnAboutUploadFailure(session) {
+    if (!session.uploadFailed) {
+        return;
+    }
+    const status = session.uploadFailureStatus ? ` (HTTP ${session.uploadFailureStatus})` : "";
+    session.onWarning?.(`Cloud report upload failed${status}; further uploads skipped.`);
+}
+function decodeScreenshot(dataUrl) {
+    const match = /^data:image\/png;base64,([a-zA-Z0-9+/=\s]+)$/.exec(dataUrl);
+    return match ? Buffer.from(match[1], "base64") : null;
+}
+async function uploadObject(uploadPolicy, body, name, contentType, fetchImpl) {
+    const form = new FormData();
+    for (const [key, value] of Object.entries(uploadPolicy.data ?? {})) {
+        form.append(key, String(value));
+    }
+    form.append("file", new Blob([body], { type: contentType }), name);
+    const response = await fetchImpl(uploadPolicy.url, { method: "POST", body: form });
+    if (!response.ok) {
+        throw new Error(`S3 upload failed (${response.status}): ${await response.text()}`);
+    }
+}
+export class DroidReportUploadManager {
+    constructor({ workers = 4, fetchImpl = fetch } = {}) {
+        this.workers = workers;
+        this.fetchImpl = fetchImpl;
+        this.queue = [];
+        this.activeWorkers = 0;
+        this.sessions = new Set();
+    }
+    /**
+     * @param {{
+     *   loadmillClient?: {
+     *     requestDroidRunReportUploadPolicy: (uploadId: string, payload: { name: string, size: number }) => Promise<unknown>,
+     *     associateDroidRunReport: (runId: string, payload: object) => Promise<unknown>,
+     *   },
+     *   onWarning?: ((message: string) => void) | null,
+     * }} options
+     */
+    startSession({ loadmillClient, onWarning = null } = {}) {
+        const session = {
+            uploadId: randomUUID(),
+            loadmillClient,
+            onWarning,
+            sequence: 0,
+            screenshotCount: 0,
+            deduplication: new Map(),
+            pending: new Set(),
+            failed: false,
+            uploadFailed: false,
+            uploadFailureStatus: null,
+            finishing: false,
+            finishPromise: null,
+        };
+        this.sessions.add(session);
+        return session;
+    }
+    enqueueScreenshot(session, dataUrl) {
+        if (!session || session.finishing || session.uploadFailed || typeof dataUrl !== "string") {
+            return null;
+        }
+        const hash = createHash("sha256").update(dataUrl).digest("hex");
+        const existing = session.deduplication.get(hash);
+        if (existing) {
+            return existing;
+        }
+        const body = decodeScreenshot(dataUrl);
+        if (!body) {
+            warn(session, "Failed to upload Droid report screenshot: unsupported image data.");
+            return null;
+        }
+        if (body.length > MAX_REPORT_OBJECT_BYTES) {
+            warn(session, `Droid report screenshot exceeds ${MAX_REPORT_OBJECT_BYTES} bytes.`);
+            return null;
+        }
+        if (session.screenshotCount >= MAX_SCREENSHOTS_PER_REPORT) {
+            warn(session, `Droid report exceeds ${MAX_SCREENSHOTS_PER_REPORT} screenshots.`);
+            return null;
+        }
+        const name = `screenshots/${String(++session.sequence).padStart(4, "0")}.png`;
+        session.screenshotCount += 1;
+        session.deduplication.set(hash, name);
+        this.#enqueue(session, { name, body, contentType: "image/png" });
+        return name;
+    }
+    finish(session, { savedRunId, html } = {}) {
+        if (!session) {
+            return Promise.resolve({ published: false, reason: "missing_session" });
+        }
+        if (session.finishPromise) {
+            return session.finishPromise;
+        }
+        session.finishing = true;
+        session.finishPromise = this.#finish(session, { savedRunId, html }).catch((error) => {
+            const status = getHttpStatus(error);
+            warn(session, `Failed to publish Droid run report${status ? ` (HTTP ${status})` : ""}.`);
+            return { published: false, reason: "publish_failed" };
+        }).finally(() => {
+            this.sessions.delete(session);
+        });
+        return session.finishPromise;
+    }
+    async #finish(session, { savedRunId, html }) {
+        await this.waitForSession(session);
+        if (session.uploadFailed) {
+            warnAboutUploadFailure(session);
+            return { published: false, reason: "upload_failed" };
+        }
+        if (!savedRunId || typeof html !== "string") {
+            return { published: false, reason: "missing_report" };
+        }
+        const body = Buffer.from(html, "utf8");
+        if (body.length > MAX_REPORT_OBJECT_BYTES) {
+            warn(session, `Droid HTML report exceeds ${MAX_REPORT_OBJECT_BYTES} bytes.`);
+            return { published: false, reason: "too_large" };
+        }
+        const htmlUpload = await this.#enqueue(session, {
+            name: "report.html",
+            body,
+            contentType: "text/html; charset=utf-8",
+        });
+        if (session.failed) {
+            warnAboutUploadFailure(session);
+            return { published: false, reason: "upload_failed" };
+        }
+        const key = htmlUpload.key;
+        await session.loadmillClient.associateDroidRunReport(savedRunId, {
+            key,
+            screenshotCount: session.screenshotCount,
+        });
+        return { published: true, key };
+    }
+    async waitForSession(session) {
+        while (session?.pending?.size) {
+            await Promise.all([...session.pending]);
+        }
+        return { failed: Boolean(session?.failed) };
+    }
+    getPendingCount(session) {
+        return session?.pending?.size ?? 0;
+    }
+    /**
+     * @param {{ timeoutMs?: number | null }} options
+     */
+    async drain({ timeoutMs = null } = {}) {
+        const pending = Promise.all([...this.sessions].map((session) => session.finishPromise ?? this.waitForSession(session)));
+        if (!Number.isFinite(timeoutMs)) {
+            await pending;
+            return { timedOut: false };
+        }
+        let timer;
+        const result = await Promise.race([
+            pending.then(() => false),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(true), timeoutMs);
+            }),
+        ]);
+        clearTimeout(timer);
+        return { timedOut: result };
+    }
+    #enqueue(session, object) {
+        let resolveTask;
+        const promise = new Promise((resolve) => {
+            resolveTask = resolve;
+        });
+        session.pending.add(promise);
+        this.queue.push({ session, object, resolveTask, promise });
+        this.#pump();
+        return promise;
+    }
+    #pump() {
+        while (this.activeWorkers < this.workers && this.queue.length > 0) {
+            const task = this.queue.shift();
+            this.activeWorkers += 1;
+            this.#runTask(task).finally(() => {
+                this.activeWorkers -= 1;
+                this.#pump();
+            });
+        }
+    }
+    async #runTask(task) {
+        let result = { uploaded: false, key: null };
+        try {
+            if (task.session.uploadFailed) {
+                return;
+            }
+            const policyResult = await task.session.loadmillClient.requestDroidRunReportUploadPolicy(task.session.uploadId, { name: task.object.name, size: task.object.body.length });
+            const uploadPolicy = policyResult?.uploadPolicy;
+            if (!uploadPolicy?.key) {
+                throw new Error("Loadmill did not return an upload policy.");
+            }
+            await uploadObject(uploadPolicy, task.object.body, task.object.name.split("/").at(-1), task.object.contentType, this.fetchImpl);
+            result = { uploaded: true, key: uploadPolicy.key };
+        }
+        catch (error) {
+            task.session.failed = true;
+            task.session.uploadFailed = true;
+            task.session.uploadFailureStatus ??= getHttpStatus(error);
+        }
+        finally {
+            task.session.pending.delete(task.promise);
+            task.resolveTask(result);
+        }
+    }
+}
+export const droidReportUploadManager = new DroidReportUploadManager();
+export function droidReportScreenshotUrl(savedRunId, objectName) {
+    const fileName = objectName.split("/").at(-1);
+    return `/api/droid-cua/runs/${encodeURIComponent(savedRunId)}/report/screenshots/${encodeURIComponent(fileName)}`;
+}

package/build/src/integrations/loadmill/run-reporter.js

@@ -100,8 +100,12 @@ export async function reportDroidRunCompletion({ loadmillClient, onWarning = nul
         return { reported: false, reason: "missing_run_id" };
     }
     try {
-        await loadmillClient.reportDroidRun(payload);
-        return { reported: true };
+        const response = await loadmillClient.reportDroidRun(payload);
+        return {
+            reported: true,
+            savedRunId: response?.run?.id ?? null,
+            run: response?.run ?? null,
+        };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

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

@@ -592,7 +592,8 @@ export class ExecutionMode {
             // clearMessages() restores the base system prompt, but we need to add context
             const recoverySystemPrompt = buildExecutionRecoveryPrompt({
                 basePrompt: this.initialSystemText,
-                transcript: transcriptContext
+                transcript: transcriptContext,
+                explainMode: context?.runtimeConfig?.explainMode === true,
             });
             // Replace the system message with the enhanced one
             this.session.installRecoverySystemPrompt(recoverySystemPrompt);

package/build/src/prompts/design.js

@@ -2,6 +2,7 @@ import { appendCustomSections, buildBaseSystemPrompt, isBrowserTarget } from "./
 import { buildAppContextSection, buildSecretKeysContextSection } from "./execution.js";
 export function buildDesignModePrompt(deviceInfo, customInstructions = {}, appContextText = "", options = {}) {
     const designCustomText = typeof customInstructions.designModeInstructions === "string" ? customInstructions.designModeInstructions.trim() : "";
+    const explainMode = options.explainMode === true;
     const basePrompt = buildBaseSystemPrompt(deviceInfo, customInstructions);
     const appContextSection = buildAppContextSection(appContextText);
     const secretKeysContextSection = buildSecretKeysContextSection(options.availableSecretKeys);
@@ -94,7 +95,14 @@ WRONG Example (DON'T DO THIS):
 3. etc...
 \`\`\`
 
-Remember: You are autonomous. Explore confidently. Generate simple, executable test scripts.${appContextSection ? `\n\n${appContextSection}` : ""}${secretKeysContextSection ? `\n\n${secretKeysContextSection}` : ""}
+${explainMode ? `EXPLAIN MODE:
+- Briefly explain non-obvious decisions, including why you choose one path, skip an expected action, or consider the goal complete
+- Name only the visible evidence that matters to the decision
+- Do not narrate routine clicks, typing, scrolling, or other obvious actions
+- Before a non-obvious action, briefly explain the decision in the same response as that action
+- Include the evidence that proves the requested flow is complete in the same response as the \`test_design_complete\` call
+
+` : ""}Remember: You are autonomous. Explore confidently. Generate simple, executable test scripts.${appContextSection ? `\n\n${appContextSection}` : ""}${secretKeysContextSection ? `\n\n${secretKeysContextSection}` : ""}
 `;
     return appendCustomSections(prompt, [
         { title: "Base Prompt Instructions", text: customInstructions.basePromptInstructions },

package/build/src/prompts/execution.js

@@ -38,6 +38,7 @@ ${normalized.map((key) => `- ${key}`).join("\n")}`;
 }
 export function buildExecutionModePrompt(deviceInfo, customInstructions = {}, appContextText = "", options = {}) {
     const executionCustomText = typeof customInstructions.executionModeInstructions === "string" ? customInstructions.executionModeInstructions.trim() : "";
+    const explainMode = options.explainMode === true;
     const aimAssistMode = typeof options.aimAssistMode === "string" ? options.aimAssistMode : DEFAULT_AIM_ASSIST_MODE;
     const basePrompt = buildBaseSystemPrompt(deviceInfo, { aimAssistMode });
     const appContextSection = buildAppContextSection(appContextText);
@@ -54,12 +55,12 @@ EXECUTION MODE - Critical Behavior:
 You are executing test script commands one at a time. This is an automated test run, not a chat with the user.
 
 CRITICAL RULES:
-- DO NOT generate conversational text or narration
+- ${explainMode ? "Explain non-obvious decisions briefly, including why you skip an expected action or consider the current instruction complete" : "DO NOT generate conversational text or narration"}
 - DO NOT ask questions like "What should I do next?", "Would you like...", "Can I assist...?"
-- DO NOT describe what you see on screen
+- ${explainMode ? "When a decision depends on visible state, name only the evidence that matters to that decision" : "DO NOT describe what you see on screen"}
 - DO NOT say "Let me know if you need help" or similar phrases
-- Just execute the action silently and stop immediately
-- Only generate text if the action FAILED or cannot be completed
+- ${explainMode ? "Do not narrate routine clicks, typing, scrolling, or other obvious actions" : "Just execute the action silently and stop immediately"}
+- ${explainMode ? "Before a non-obvious action, briefly explain the decision in the same response as that action\n- Explain completion evidence using assistant text; do not call `assert` merely to confirm that an ordinary action succeeded\n- Call `assert` only when the current instruction explicitly contains assertion or verification intent\n- If an action FAILED or the instruction cannot be completed, state that clearly and explain why" : "Only generate text if the action FAILED or cannot be completed"}
 - ${browserTarget ? "Use browser-appropriate keyboard input only when it is the most reliable path" : "Never emit desktop keyboard shortcuts or modifier combos; mobile execution only supports mobile-safe single-key presses"}
 - Never repeat the same mutating action with the same apparent intent unless the UI clearly shows failure or no state change
 - If a submit/create/approve/reject/login action appears to succeed, stop instead of trying to reconfirm by doing it again
@@ -86,7 +87,7 @@ ${browserTarget ? "" : `   - Every \`type\` action must end its computer-action
 4. ${browserTarget ? "Before tapping a mutating action, dismiss the keyboard if it is open and not needed" : "Use `close_keyboard` before any later interaction when the post-type dismissal rules require it"}
 5. After a mutating action, inspect the resulting screen for success cues such as cleared fields, reset buttons, changed status, refreshed content, or navigation
 6. Stop as soon as success is visible
-7. Stop immediately - no commentary, no questions
+7. ${explainMode ? "If the completion decision is not obvious, briefly state the visible evidence, then stop - no questions" : "Stop immediately - no commentary, no questions"}
 
 ${instructionContextRule}
 ${appContextSection ? `\n\n${appContextSection}` : ""}${testDataContextSection ? `\n\n${testDataContextSection}` : ""}${secretKeysContextSection ? `\n\n${secretKeysContextSection}` : ""}`;
@@ -95,7 +96,7 @@ ${appContextSection ? `\n\n${appContextSection}` : ""}${testDataContextSection ?
         { title: "Execution Mode Instructions", text: executionCustomText }
     ]);
 }
-export function buildExecutionRecoveryPrompt({ basePrompt, transcript }) {
+export function buildExecutionRecoveryPrompt({ basePrompt, transcript, explainMode = false }) {
     if (!transcript) {
         return basePrompt;
     }
@@ -104,7 +105,9 @@ export function buildExecutionRecoveryPrompt({ basePrompt, transcript }) {
 [SESSION RECOVERY - Connection was lost. Previous actions completed before the error:]
 ${transcript}
 
-[IMPORTANT: Resume execution silently. Do NOT narrate or explain. Just execute the next instruction.]`;
+${explainMode
+        ? "[IMPORTANT: Resume execution. Continue using concise decision explanations without narrating routine actions.]"
+        : "[IMPORTANT: Resume execution silently. Do NOT narrate or explain. Just execute the next instruction.]"}`;
 }
 export function buildExecutionNavigationRecoveryPrompt({ basePrompt, transcript, navigatedUrl }) {
     const normalizedTranscript = typeof transcript === "string" ? transcript.trim() : "";

package/build/src/utils/console-output.js

@@ -27,6 +27,9 @@ export function formatCliOutput(item) {
         }
         const stepCompletion = stepCompletionData(text);
         if (stepCompletion) {
+            if (item.payload?.explainMode === true) {
+                return `assistant: Step complete — ${stepCompletion.instruction}\nassistant: Reason: ${stepCompletion.reason}`;
+            }
             return `assistant: Step complete — ${stepCompletion.instruction}`;
         }
         return text

package/build/src/utils/run-screenshot-recorder.js

@@ -84,9 +84,9 @@ function buildMarkerPlacement(marker = {}, width, height) {
 }
 const MARKER_APPEARANCES = {
     click: {
-        haloFill: "#39ff14",
+        haloFill: "#2f7df6",
         haloOpacity: 0.28,
-        ringStroke: "#39ff14",
+        ringStroke: "#2f7df6",
         centerDotFill: "#07131f",
     },
     preview: {

package/package.json

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