@loadmill/droid-cua 2.16.0 → 2.18.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

@@ -13,6 +13,8 @@ import { createOpenAiExecutor } from "./src/device/openai.js";
 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";
@@ -20,6 +22,7 @@ import { createHeadlessDebugArtifacts } from "./src/cli/headless-debug.js";
 import { loadHeadlessInstructions } from "./src/cli/headless-instructions.js";
 import { listHeadlessInstructionFiles, resolveHeadlessInstructionsTarget } from "./src/cli/headless-instruction-target.js";
 import { runHeadlessInstructionRuns } from "./src/cli/headless-runner.js";
+import { planScenarioRuns } from "./src/cli/scenario-planner.js";
 import { resolveLambdaTestCredentials, uploadLambdaTestCliApp } from "./src/cli/lambdatest-app-upload.js";
 import { createLoadmillApiClient } from "./src/integrations/loadmill/client.js";
 import { getCloudProviderAdapter } from "./src/device/cloud/registry.js";
@@ -33,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 });
@@ -67,6 +77,41 @@ function wait(ms) {
 function isLambdaTestAppAutomationUrl(value) {
     return typeof value === "string" && value.startsWith("https://appautomation.lambdatest.com/test?");
 }
+async function loadScenarioCandidateRuns(runs) {
+    return await Promise.all(runs.map(async (run) => ({
+        ...run,
+        instructions: run.instructions ?? await loadHeadlessInstructions(run.testPath),
+    })));
+}
+function printScenarioCasePreview(cases) {
+    console.log(`\nScenario preview: ${cases.length} case${cases.length === 1 ? "" : "s"}\n`);
+    cases.forEach((entry, index) => {
+        console.log(`${index + 1}. ${entry.caseName}`);
+    });
+    console.log("");
+}
+function buildScenarioInstructionTarget(originalTarget, scenarioPrompt) {
+    return {
+        type: "scenario",
+        path: originalTarget?.path || null,
+        sourceType: originalTarget?.type || null,
+        scenarioPrompt,
+    };
+}
+function buildScenarioRuns({ candidateRuns, cases }) {
+    const runByTestName = new Map(candidateRuns.map((run) => [run.testName, run]));
+    return cases.map((entry) => {
+        const sourceRun = runByTestName.get(entry.testName);
+        return {
+            ...sourceRun,
+            testName: entry.caseName,
+            sourceTestName: entry.testName,
+            scenarioCaseName: entry.caseName,
+            testDataContext: entry.testDataContext,
+            instructions: sourceRun.instructions,
+        };
+    });
+}
 async function resolveLambdaTestDashboardUrl(credentials, sessionId, { attempts = 1, delayMs = 1000 } = {}) {
     const adapter = getCloudProviderAdapter("lambdatest");
     for (let attempt = 1; attempt <= attempts; attempt += 1) {
@@ -107,13 +152,25 @@ async function main() {
     if (isLambdaTestTarget && !isHeadlessInstructionsRun) {
         throw new Error("--device-source lambdatest is only supported with --instructions headless execution.");
     }
+    if (!isHeadlessInstructionsRun && args.scenario != null) {
+        throw new Error("--scenario can only be used with --instructions headless execution.");
+    }
+    if (!isHeadlessInstructionsRun && args["test-data"] != null) {
+        throw new Error("--test-data can only be used with --instructions headless execution.");
+    }
     let preloadedHeadlessConfig = null;
     let preloadedHeadlessTarget = null;
     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) {
@@ -139,6 +196,14 @@ async function main() {
         if (preloadedAppContext.status === "failed") {
             throw new Error(`Could not read app context file ${preloadedAppContext.contextPath}: ${preloadedAppContext.message}`);
         }
+        if (preloadedHeadlessConfig.scenarioPrompt) {
+            preloadedTestData = await resolveExecutionTestData({
+                testDataPath: preloadedHeadlessConfig.testDataPath,
+            });
+            if (preloadedTestData.status === "failed") {
+                throw new Error(`Could not read test data file ${preloadedTestData.testDataPath}: ${preloadedTestData.message}`);
+            }
+        }
     }
     // If no device specified, show interactive selection menu
     if (!isBrowserTarget && !isLambdaTestTarget && !avdName && !platform) {
@@ -236,6 +301,26 @@ async function main() {
             });
             console.log(`Using AI provider: ${runtimeContext.config.llmProviderMode}`);
             console.log(`Using CUA model: ${runtimeContext.config.cuaModel}`);
+            if (headlessConfig.scenarioPrompt) {
+                const candidateRuns = await loadScenarioCandidateRuns(headlessInstructionRuns);
+                const scenarioCases = await planScenarioRuns({
+                    client: runtimeContext.openAiClient,
+                    runtimeConfig: runtimeContext.config,
+                    scenarioPrompt: headlessConfig.scenarioPrompt,
+                    tests: candidateRuns.map((run) => ({
+                        testName: run.testName,
+                        instructions: run.instructions,
+                    })),
+                    appContextText,
+                    testDataText: preloadedTestData?.text || "",
+                });
+                printScenarioCasePreview(scenarioCases);
+                headlessInstructionRuns = buildScenarioRuns({
+                    candidateRuns,
+                    cases: scenarioCases,
+                });
+                preloadedHeadlessTarget = buildScenarioInstructionTarget(preloadedHeadlessTarget, headlessConfig.scenarioPrompt);
+            }
             const result = await runHeadlessInstructionRuns({
                 runs: headlessInstructionRuns,
                 instructionsTarget: preloadedHeadlessTarget,
@@ -243,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: "",
@@ -172,6 +173,10 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     const cwd = typeof options.cwd === "string" ? options.cwd : process.cwd();
     const configPath = typeof args.config === "string" ? args.config : null;
     const explicitContextPath = typeof args.context === "string" ? path.resolve(cwd, args.context) : null;
+    const scenarioPrompt = typeof args.scenario === "string" ? args.scenario.trim() : null;
+    const hasScenarioFlag = args.scenario != null;
+    const testDataPath = typeof args["test-data"] === "string" ? path.resolve(cwd, args["test-data"]) : null;
+    const hasTestDataFlag = args["test-data"] != null;
     const noContext = args["no-context"] === true || args.context === false;
     const contextOptimizationEnabledByFlag = args["context-optimization"] === true;
     const noContextOptimization = args["no-context-optimization"] === true || args["context-optimization"] === false;
@@ -180,12 +185,25 @@ 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.");
     }
+    if (hasScenarioFlag && !scenarioPrompt) {
+        throw new Error("--scenario must be a non-empty string.");
+    }
+    if (hasTestDataFlag && !testDataPath) {
+        throw new Error("--test-data must be a non-empty path.");
+    }
+    if (testDataPath && !scenarioPrompt) {
+        throw new Error("--test-data can only be used with --scenario.");
+    }
     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.");
     }
@@ -202,6 +220,9 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         promptCustomizations,
         appContextEnabled: fileConfig?.appContextEnabled ?? true,
         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,11 +102,17 @@ function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionP
     }
     return engineOptions;
 }
-async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, 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,
+            ...(testDataContext ? { testDataUsed: true } : {}),
             platform: deviceInfo.platform,
             deviceName: deviceInfo.device_name,
             aimAssistMode: headlessConfig.aimAssistMode
@@ -119,7 +127,11 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         emitCliAppContextDebug(runId, appContext, appContextText);
         session.updateResponseId(undefined);
         session.clearMessages();
-        const executionPrompt = buildExecutionModePrompt(deviceInfo, headlessConfig.promptCustomizations, appContextText, { aimAssistMode: headlessConfig.aimAssistMode });
+        const executionPrompt = buildExecutionModePrompt(deviceInfo, headlessConfig.promptCustomizations, appContextText, {
+            aimAssistMode: headlessConfig.aimAssistMode,
+            testDataContext,
+            availableSecretKeys: secrets?.availableSecretKeys || [],
+        });
         session.setSystemPrompt(executionPrompt);
         const screenshotRecorder = headlessDebug.createExecutionScreenshotRecorder({
             runId,
@@ -134,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;
@@ -161,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
@@ -188,9 +223,12 @@ 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 }) {
-    const isBatchRun = instructionsTarget?.type === "directory";
-    if (isBatchRun) {
+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`);
+    }
+    else if (isBatchRun) {
         console.log(`\nRunning ${runs.length} tests from: ${instructionsTarget.path}\n`);
     }
     let failures = 0;
@@ -205,7 +243,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             if (recordScreenshots && testScreenshotDir) {
                 await mkdir(testScreenshotDir, { recursive: true });
             }
-            const result = await runHeadlessTest({
+            const result = await runHeadlessTestImpl({
                 runId,
                 testPath: run.testPath,
                 testName: run.testName,
@@ -214,12 +252,16 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
                 deviceInfo,
                 headlessConfig,
                 appContext,
+                testDataContext: run.testDataContext || "",
                 runtimeContext,
                 headlessDebug,
+                secrets,
                 recordScreenshots,
                 screenshotDir: testScreenshotDir,
                 isBrowserTarget,
-                isLambdaTestTarget
+                isLambdaTestTarget,
+                report,
+                isBatchRun
             });
             if (!result.success) {
                 failures += 1;
@@ -234,7 +276,11 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             console.error(`\nTest failed: ${run.testName}: ${message}`);
         }
     }
-    if (isBatchRun) {
+    if (instructionsTarget?.type === "scenario") {
+        const passed = runs.length - failures;
+        console.log(`\nScenario run complete: ${passed}/${runs.length} passed`);
+    }
+    else if (isBatchRun) {
         const passed = runs.length - failures;
         console.log(`\nFolder run complete: ${passed}/${runs.length} passed`);
     }

package/build/src/cli/scenario-planner.js

@@ -0,0 +1 @@
+export { planScenarioRuns, validateScenarioCases, } from "../core/scenario-planner.js";

package/build/src/commands/help.js

@@ -26,6 +26,9 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --os-version <version> LambdaTest OS version' });
     addOutput({ type: 'info', text: '  --app <path>           LambdaTest app package path (.apk or .ipa)' });
     addOutput({ type: 'info', text: '  --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' });
@@ -80,6 +83,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  droid-cua --avd "iPhone 16"             (iOS Simulator, auto-detected)' });
     addOutput({ type: 'info', text: '  droid-cua --platform ios --avd MySim    (Force iOS platform)' });
     addOutput({ type: 'info', text: '  droid-cua --instructions tests/login.dcua --context app/context.md' });
+    addOutput({ type: 'info', text: '  droid-cua --instructions tests --test-data tests/test-data.md --scenario "Run every checkout test with each buyer account"' });
     addOutput({ type: 'info', text: '  droid-cua --target web --instructions tests/search.dcua' });
     addOutput({ type: 'info', text: '  droid-cua --device-source lambdatest --platform android --device-name "Galaxy S24" --os-version 14 --app app.apk --instructions tests/login.dcua' });
     addOutput({ type: 'info', text: '  /create login-test                      (design a new test)' });

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);