@loadmill/droid-cua 2.17.0 → 2.19.0

package/README.md

@@ -206,7 +206,9 @@ Supported CLI options include:
 - `--execution-prompt`
 - `--base-prompt-file`
 - `--execution-prompt-file`
+- `--secrets`
 - `--record`
+- `--report`
 - `--debug`
 
 Config and precedence rules:
@@ -221,6 +223,22 @@ Config and precedence rules:
 - `--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.
 
+Secret typing:
+- Put runtime typing secrets in a project `.secrets` file using dotenv-style `KEY=value` lines.
+- Desktop execution and design mode load `.secrets` from the selected project folder. Headless CLI loads `.secrets` from the current working directory.
+- Headless CLI also accepts `--secrets KEY=value,OTHER=value`; these values override `.secrets` for that run.
+- The agent sees only secret keys and may call `type_sensitive_text({ key })`. Logs and reports may include keys, but not resolved values.
+- Screenshot masking is out of scope. Secret values also necessarily pass through ADB, Appium, or browser automation while being typed.
+
+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.
+
+```sh
+droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua --report ./reports
+```
+
 LambdaTest CLI runs:
 - Use `--device-source lambdatest` with `--platform`, `--device-name`, `--os-version`, `--app`, and `--instructions`.
 - Set `LAMBDATEST_USERNAME` and `LAMBDATEST_ACCESS_KEY` in the environment.

package/build/index.js

@@ -14,6 +14,7 @@ import { logger } from "./src/utils/logger.js";
 import { selectDevice } from "./src/cli/device-selector.js";
 import { resolveExecutionAppContext } from "./src/core/app-context.js";
 import { resolveExecutionTestData } from "./src/core/test-data.js";
+import { getDefaultSecretsPath, resolveExecutionSecrets } from "./src/core/secrets.js";
 import { createRunContext, resolveRuntimeConfigFromEnv, resolveRuntimeCredentialsFromEnv, } from "./src/core/runtime-config.js";
 import { resolveHeadlessExecutionConfig } from "./src/cli/headless-execution-config.js";
 import { resolveHeadlessTarget } from "./src/cli/headless-target.js";
@@ -35,6 +36,13 @@ const startupUrl = typeof args.url === "string" && args.url.trim().length > 0 ?
 const instructionsFile = args.instructions || args.i || null;
 const appContextPath = typeof args.context === "string" ? args.context : null;
 const debugMode = args["debug"] || false;
+// --report [path]: generate a self-contained HTML report at the end of the run.
+// `--report` alone writes <test>-<stamp>.html in the cwd; `--report <path>` lets the
+// user choose a file (single run) or directory (used for every run).
+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,
+};
 const screenshotDir = path.join("droid-cua-recording-" + Date.now());
 if (recordScreenshots)
     await mkdir(screenshotDir, { recursive: true });
@@ -155,9 +163,14 @@ async function main() {
     let headlessInstructionRuns = [];
     let preloadedAppContext = null;
     let preloadedTestData = null;
+    let preloadedSecrets = null;
     if (isHeadlessInstructionsRun) {
         preloadedHeadlessConfig = await resolveHeadlessExecutionConfig(args);
         preloadedHeadlessTarget = await resolveHeadlessInstructionsTarget(instructionsFile);
+        preloadedSecrets = await resolveExecutionSecrets({
+            secretsPath: getDefaultSecretsPath(process.cwd()),
+            cliSecrets: preloadedHeadlessConfig.secretsOverride,
+        });
         if (preloadedHeadlessTarget.type === "directory") {
             const files = await listHeadlessInstructionFiles(preloadedHeadlessTarget.path);
             if (files.length === 0) {
@@ -315,12 +328,14 @@ async function main() {
                 deviceInfo,
                 headlessConfig,
                 appContext,
+                secrets: preloadedSecrets,
                 runtimeContext,
                 headlessDebug,
                 recordScreenshots,
                 screenshotDir,
                 isBrowserTarget,
-                isLambdaTestTarget
+                isLambdaTestTarget,
+                report: reportConfig
             });
             exitCode = result.exitCode;
         }

package/build/src/browser/playwright/actions.js

@@ -2,6 +2,7 @@ import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug, truncateForDebug } from "../../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../../utils/step-delay.js";
 import { buildActionEventMeta } from "../../device/action-event-meta.js";
+import { actionForErrorLog, buildActionErrorOutput, buildDebugTextField, buildSensitiveDebugFields, buildTypeActionPayload, buildTypeActionText, isSensitiveAction, } from "../../device/sensitive-action.js";
 import { getActiveBrowserPage } from "./session-state.js";
 const KEY_ALIASES = {
     CTRL: "Control",
@@ -77,7 +78,8 @@ export async function handleModelAction(browserSessionId, action, scale = 1, con
             y1: action?.y1,
             x2: action?.x2,
             y2: action?.y2,
-            text: typeof action?.text === "string" ? truncateForDebug(action.text, 300) : undefined,
+            text: buildDebugTextField(action, truncateForDebug),
+            ...buildSensitiveDebugFields(action),
             keyCount: Array.isArray(action?.keys) ? action.keys.length : 0,
             pathPoints: Array.isArray(action?.path) ? action.path.length : 0,
         });
@@ -138,7 +140,11 @@ export async function handleModelAction(browserSessionId, action, scale = 1, con
             }
             case "type": {
                 const text = typeof action.text === "string" ? action.text : "";
-                addOutput({ type: "action", text: `Typing text: ${text}`, ...buildMeta(context, action, { text }) });
+                addOutput({
+                    type: "action",
+                    text: buildTypeActionText(action, text),
+                    ...buildMeta(context, action, buildTypeActionPayload(action, text))
+                });
                 await page.keyboard.type(text);
                 break;
             }
@@ -163,12 +169,14 @@ export async function handleModelAction(browserSessionId, action, scale = 1, con
             default:
                 addOutput({ type: "info", text: `Unknown action: ${JSON.stringify(action)}` });
         }
+        return { success: true };
     }
     catch (error) {
+        const outputError = buildActionErrorOutput(action, error);
         logger.error("Action execution error", {
-            action,
-            message: error.message,
-            stack: error.stack,
+            action: actionForErrorLog(action),
+            message: outputError.message,
+            stack: isSensitiveAction(action) ? undefined : error.stack,
         });
         emitDesktopDebug("browser.error", "device", {
             runId: context?.runId,
@@ -179,21 +187,22 @@ export async function handleModelAction(browserSessionId, action, scale = 1, con
             platform: "browser",
             operation: "action.execute",
             actionType: action?.type,
-            message: error.message,
+            message: outputError.message,
         });
         addOutput({
             type: "error",
-            text: `Error executing action: ${error.message}`,
+            text: outputError.text,
             eventType: "error",
             actionType: action?.type,
             runId: context?.runId,
             stepId: context?.stepId,
             instructionIndex: context?.instructionIndex,
             payload: {
-                message: error.message,
+                message: outputError.message,
                 platform: "browser",
             },
         });
         addOutput({ type: "info", text: "Full error details have been logged to the debug log." });
+        return { success: false, error: outputError.message };
     }
 }

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

@@ -4,6 +4,7 @@ import { DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD, MAX_CONTEXT_OPTIMIZATION_THRESH
 import { AIM_ASSIST_MODES, DEFAULT_AIM_ASSIST_MODE } from "../core/aim-assist.js";
 import { CUA_MODELS, DEFAULT_OPENAI_CUA_MODEL, isOpenAiCuaModel, isValidCuaModel, resolveCuaModel } from "../core/cua-models.js";
 import { LLM_PROVIDER_MODES, isValidLlmProviderMode, resolveLlmProviderMode } from "../core/runtime-config.js";
+import { parseSecretsOverrideString } from "../core/secrets.js";
 function createEmptyPromptCustomizations() {
     return {
         basePromptInstructions: "",
@@ -184,6 +185,7 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     const executionPromptText = typeof args["execution-prompt"] === "string" ? args["execution-prompt"] : null;
     const basePromptFilePath = typeof args["base-prompt-file"] === "string" ? path.resolve(cwd, args["base-prompt-file"]) : null;
     const executionPromptFilePath = typeof args["execution-prompt-file"] === "string" ? path.resolve(cwd, args["execution-prompt-file"]) : null;
+    const secretsOverride = args.secrets == null ? null : args.secrets;
     if (explicitContextPath && noContext) {
         throw new Error("--context and --no-context cannot be used together.");
     }
@@ -199,6 +201,9 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     if (contextOptimizationEnabledByFlag) {
         throw new Error("--context-optimization is not supported; Context Optimization is enabled by default.");
     }
+    if (secretsOverride != null) {
+        parseSecretsOverrideString(secretsOverride);
+    }
     if (noContextOptimization && hasContextOptimizationThresholdFlag) {
         throw new Error("--context-optimization-threshold and --no-context-optimization cannot be used together.");
     }
@@ -217,6 +222,7 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         appContextPath: fileConfig?.appContextPath || null,
         scenarioPrompt,
         testDataPath,
+        secretsOverride,
         contextOptimizationEnabled: fileConfig?.contextOptimizationEnabled ?? true,
         contextOptimizationThreshold: fileConfig?.contextOptimizationThreshold ?? DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD,
     };

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

@@ -0,0 +1,113 @@
+// CLI-side HTML report generation for `--report`. Captures the run's emitted events
+// (the same `addOutput` items the engine produces), synthesizes the run-summary event
+// the CLI stream omits, and renders a self-contained HTML report via the shared core
+// renderer (src/core/report). Screenshots are inlined as data URLs because the report
+// run sets `includeScreenshotDataUrl: true` in the execution context.
+import path from "node:path";
+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";
+// 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) {
+    return (item) => {
+        if (item && typeof item === "object") {
+            sink.push({
+                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,
+            });
+        }
+        return underlying(item);
+    };
+}
+// Derives the JUnit-style counts the shared status ladder expects from the CLI's
+// boolean/error/event signals. Exactly one of {stopped, failures, errors} is ever set, so
+// the shared precedence (error > fail > stopped > skipped > pass) yields the same verdict
+// the CLI produced before — see R1.
+function deriveCounts(success, error, events) {
+    if (success)
+        return { failures: 0, errors: 0, stopped: false };
+    if (String(error || "").toLowerCase().includes("stopped by user")) {
+        return { failures: 0, errors: 0, stopped: true };
+    }
+    const failedAssertion = events.some((event) => event.eventType === "assertion_result" && event.payload?.passed === false) ||
+        String(error || "").startsWith("Assertion failed:");
+    return failedAssertion ? { failures: 1, errors: 0, stopped: false } : { failures: 0, errors: 1, stopped: false };
+}
+// 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.
+export function buildCliRunReportModel({ suiteName, testName, startedAtIso, durationMs, success, error, instructionsTotal, stats = {}, events, }) {
+    const warnings = [];
+    const normalizedEvents = normalizeEvents(events, { fallbackTs: startedAtIso ?? null, warnings });
+    const summaryPayload = buildRunFinishedPayload({
+        success,
+        error,
+        durationMs,
+        instructionsTotal,
+        instructionsCompleted: stats.instructionsCompleted,
+        actionsTotal: stats.actionCount,
+        assertionsPassed: stats.assertionsPassed,
+        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 { failures, errors, stopped } = deriveCounts(success, error, allEvents);
+    const status = deriveRunStatus({ tests: 1, failures, errors, stopped });
+    const successRate = computeSuccessRate({ tests: 1, failures, errors, status });
+    return assembleRunReportModel({
+        suiteName: suiteName ?? null,
+        testName: testName ?? null,
+        timestamp: startedAtIso ?? null,
+        durationSeconds: Number.isFinite(durationMs) ? durationMs / 1000 : null,
+        status,
+        testCases: 1,
+        successRate,
+        failureOrError: success
+            ? undefined
+            : makeFailureOrError({ kind: status === "error" ? "error" : "failure", message: error ?? undefined }),
+        events: allEvents,
+        warnings,
+    });
+}
+// Resolves where to write the report. A `--report <path>`:
+//   - ending in .html for a single run → that exact file
+//   - otherwise → treated as a directory; the file is named <test>--<date>--<time>.html
+// With no path, writes <test>--<date>--<time>.html in the current working directory.
+export function resolveReportOutputPath({ reportPath, testName, startedAtIso, cwd = process.cwd(), isBatch = false }) {
+    const fileName = buildReportFileName({ testName, timestamp: startedAtIso });
+    if (!reportPath) {
+        return path.join(cwd, fileName);
+    }
+    const resolved = path.resolve(cwd, reportPath);
+    if (/\.html?$/i.test(reportPath)) {
+        return isBatch ? path.join(path.dirname(resolved), fileName) : resolved;
+    }
+    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 } = {}) {
+    const model = buildCliRunReportModel(modelInput);
+    const outputPath = resolveReportOutputPath({
+        reportPath,
+        testName: modelInput.testName,
+        startedAtIso: modelInput.startedAtIso,
+        cwd,
+        isBatch,
+    });
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, renderHtmlReport(model), "utf-8");
+    return outputPath;
+}

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

@@ -8,6 +8,7 @@ import { ExecutionMode } from "../modes/execution-mode.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";
 function sanitizePathSegment(value) {
     return String(value || "test")
         .replace(/\.dcua$/i, "")
@@ -55,13 +56,14 @@ function emitCliAppContextDebug(runId, appContext, appContextText) {
         });
     }
 }
-function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionPrompt, screenshotRecorder, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
+function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionPrompt, screenshotRecorder, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget, secrets = null }) {
     const executionEngineOptions = {
         toolCapabilities: {
             assert: true,
             navigate: isBrowserTarget,
             loadmill: true,
         },
+        secretsByKey: secrets?.secretsByKey || {},
         baseSystemPrompt: executionPrompt,
         isHeadlessMode: true,
     };
@@ -100,8 +102,13 @@ function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionP
     }
     return engineOptions;
 }
-async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
+async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget, secrets = null, report = null, isBatchRun = false }) {
     let executionMode = null;
+    const reportEnabled = Boolean(report?.enabled);
+    const collectedEvents = [];
+    const addOutput = reportEnabled
+        ? createCapturingAddOutput(printCliOutput, collectedEvents)
+        : printCliOutput;
     try {
         await headlessDebug.startExecutionSession(runId, {
             testName,
@@ -123,6 +130,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         const executionPrompt = buildExecutionModePrompt(deviceInfo, headlessConfig.promptCustomizations, appContextText, {
             aimAssistMode: headlessConfig.aimAssistMode,
             testDataContext,
+            availableSecretKeys: secrets?.availableSecretKeys || [],
         });
         session.setSystemPrompt(executionPrompt);
         const screenshotRecorder = headlessDebug.createExecutionScreenshotRecorder({
@@ -138,16 +146,19 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             recordScreenshots,
             screenshotDir,
             isBrowserTarget,
-            isLambdaTestTarget
+            isLambdaTestTarget,
+            secrets
         });
         const engine = new ExecutionEngine(session, engineOptions);
         executionMode = new ExecutionMode(session, engine, instructions, true);
         const result = await executionMode.execute({
             runId,
-            addOutput: printCliOutput,
+            addOutput,
             openAiClient: runtimeContext.openAiClient,
             loadmillClient: runtimeContext.loadmillClient,
             runtimeCredentials: runtimeContext.credentials,
+            // Inline screenshots as data URLs so the HTML report is self-contained.
+            ...(reportEnabled ? { includeScreenshotDataUrl: true } : {}),
         });
         const stats = executionMode.stats || {};
         const durationMs = stats.startTime ? Math.max(0, Date.now() - stats.startTime) : 0;
@@ -165,6 +176,26 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         if (!result.success) {
             console.error(`\nTest failed: ${result.error}`);
         }
+        if (reportEnabled) {
+            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 });
+                console.log(`HTML report saved: ${outputPath}`);
+            }
+            catch (reportError) {
+                const message = reportError instanceof Error ? reportError.message : String(reportError);
+                console.warn(`Warning: failed to write HTML report: ${message}`);
+            }
+        }
         return {
             success: Boolean(result.success),
             error: result.error ?? null
@@ -192,7 +223,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         throw error;
     }
 }
-export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget, runHeadlessTestImpl = runHeadlessTest }) {
+export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, secrets = null, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget, report = null, runHeadlessTestImpl = runHeadlessTest }) {
     const isBatchRun = instructionsTarget?.type === "directory" || instructionsTarget?.type === "scenario";
     if (instructionsTarget?.type === "scenario") {
         console.log(`\nRunning ${runs.length} scenario case${runs.length === 1 ? "" : "s"}\n`);
@@ -224,10 +255,13 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
                 testDataContext: run.testDataContext || "",
                 runtimeContext,
                 headlessDebug,
+                secrets,
                 recordScreenshots,
                 screenshotDir: testScreenshotDir,
                 isBrowserTarget,
-                isLambdaTestTarget
+                isLambdaTestTarget,
+                report,
+                isBatchRun
             });
             if (!result.success) {
                 failures += 1;

package/build/src/commands/help.js

@@ -28,6 +28,7 @@ export async function handleHelp(args, session, context) {
     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' });
+    addOutput({ type: 'info', text: '  --secrets <pairs>      Runtime typing secrets as KEY=value,OTHER=value' });
     addOutput({ type: 'info', text: '  --session-mode <mode>  Browser session mode for web runs: persistent or fresh' });
     addOutput({ type: 'info', text: '  --config <file>        Headless execution JSON config for prompt parity' });
     addOutput({ type: 'info', text: '  --llm-provider <mode>  Headless AI provider: loadmill or openai' });

package/build/src/commands/run.js

@@ -88,7 +88,8 @@ export async function handleRun(args, session, context) {
         });
     }
     // Set execution mode system prompt (replaces any design mode prompt)
-    const executionPrompt = buildExecutionModePrompt(session.deviceInfo, {}, appContextText);
+    const availableSecretKeys = context.engine.getAvailableSecretKeys();
+    const executionPrompt = buildExecutionModePrompt(session.deviceInfo, {}, appContextText, { availableSecretKeys });
     session.setSystemPrompt(executionPrompt);
     // Create execution mode
     const executionMode = new ExecutionMode(session, context.engine, instructions);