@loadmill/droid-cua 2.17.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

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

package/build/src/core/execution-engine.js

@@ -5,9 +5,11 @@ import { handleModelAction } from "../device/actions.js";
 import { sendCUARequest } from "../device/openai.js";
 import { executeLoadmillInstruction } from "../device/loadmill.js";
 import { emitDesktopDebug } from "../utils/desktop-debug.js";
+import { createAnnotatedScreenshotFromBase64 } from "../utils/run-screenshot-recorder.js";
 import { getConfiguredStepDelayMs } from "../utils/step-delay.js";
 import { printCliOutput } from "../utils/console-output.js";
 import { CAPTURE_SOURCES } from "./capture-sources.js";
+import { normalizeSecretKeys } from "./secrets.js";
 import { ScreenshotStore } from "./screenshot-store.js";
 import { handlePreviewClick } from "./tool-handlers/preview-click.js";
 import { handleNavigateToolCall } from "./tool-handlers/navigate.js";
@@ -15,6 +17,7 @@ import { handleCloseCurrentTabToolCall } from "./tool-handlers/close-current-tab
 import { handleAssertionToolCall } from "./tool-handlers/assert.js";
 import { handleLoadmillToolCall } from "./tool-handlers/loadmill.js";
 import { handleTestDesignCompleteToolCall } from "./tool-handlers/test-design-complete.js";
+import { handleTypeSensitiveTextToolCall } from "./tool-handlers/type-sensitive-text.js";
 import { buildDebugContext, buildTextToolOutputItem, } from "./tool-handlers/utils.js";
 function extractActionableOutputItems(items) {
     const entries = [];
@@ -77,11 +80,33 @@ export class ExecutionEngine {
         this.closeCurrentTab = options.closeCurrentTab || closeCurrentBrowserTab;
         this.executeLoadmillInstruction = options.executeLoadmillInstruction || executeLoadmillInstruction;
         this.toolCapabilities = options.toolCapabilities || {};
+        this.secretsByKey = options.secretsByKey && typeof options.secretsByKey === "object" ? options.secretsByKey : {};
         this.baseSystemPrompt = options.baseSystemPrompt || session?.systemPrompt || null;
         this.isHeadlessMode = options.isHeadlessMode === true;
     }
+    hasSecrets() {
+        return this.getAvailableSecretKeys().length > 0;
+    }
+    getAvailableSecretKeys() {
+        return normalizeSecretKeys(Object.keys(this.secretsByKey));
+    }
     async recordScreenshot(screenshotBase64, metadata = {}) {
-        return await this.screenshotStore.saveScreenshot(screenshotBase64, metadata);
+        const saved = await this.screenshotStore.saveScreenshot(screenshotBase64, metadata);
+        if (saved) {
+            return saved;
+        }
+        // No recorder/persistence (e.g. a plain CLI `--report` run): still hold onto the raw
+        // base64 so downstream click-annotation can render the marker in-memory for the report.
+        if (typeof screenshotBase64 !== "string" || !screenshotBase64) {
+            return null;
+        }
+        return {
+            base64: screenshotBase64,
+            artifactPaths: [],
+            annotationSourcePaths: [],
+            screenshotPath: null,
+            screenshotDataUrl: null,
+        };
     }
     async annotateScreenshot(currentScreenshot, action, metadata = {}) {
         if (!(action?.type === "click" || action?.type === "double_click")) {
@@ -89,6 +114,30 @@ export class ExecutionEngine {
         }
         return await this.screenshotStore.annotateScreenshot(currentScreenshot, { x: action.x, y: action.y, style: "click" }, { ...metadata, actionType: action.type });
     }
+    // Resolves the click-annotation data URL for an action event when a self-contained
+    // report is being produced (`includeScreenshotDataUrl`). Prefers the recorder's own
+    // annotated data URL (Desktop); otherwise renders the green "click" marker in-memory
+    // from the raw screenshot so reports work even without a disk recorder.
+    async resolveAnnotatedDataUrl(annotatedScreenshot, currentScreenshot, action, context) {
+        if (!context?.includeScreenshotDataUrl) {
+            return null;
+        }
+        if (annotatedScreenshot?.screenshotDataUrl) {
+            return annotatedScreenshot.screenshotDataUrl;
+        }
+        if (!(action?.type === "click" || action?.type === "double_click")) {
+            return null;
+        }
+        if (typeof currentScreenshot?.base64 !== "string" || !currentScreenshot.base64) {
+            return null;
+        }
+        const annotated = await createAnnotatedScreenshotFromBase64(currentScreenshot.base64, {
+            x: action.x,
+            y: action.y,
+            style: "click",
+        });
+        return annotated?.screenshotBase64 ? `data:image/png;base64,${annotated.screenshotBase64}` : null;
+    }
     /**
      * Dispatches a function-call tool to its handler. Each handler returns a
      * discriminated outcome that runFullTurn interprets below. Continue and
@@ -108,6 +157,8 @@ export class ExecutionEngine {
                 return await handleCloseCurrentTabToolCall(handlerArgs);
             case "loadmill":
                 return await handleLoadmillToolCall(handlerArgs);
+            case "type_sensitive_text":
+                return await handleTypeSensitiveTextToolCall(handlerArgs);
             case "test_design_complete":
                 return await handleTestDesignCompleteToolCall(handlerArgs);
             default:
@@ -146,6 +197,10 @@ 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.
+            // 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);
             await this.handleModelAction(this.session.deviceId, action, this.session.deviceInfo.scale, {
                 ...context,
                 shouldStop,
@@ -154,7 +209,7 @@ export class ExecutionEngine {
                 eventId: actionEventId,
                 captureSource: CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION,
                 ...(annotatedScreenshot?.screenshotPath ? { screenshotPath: annotatedScreenshot.screenshotPath } : {}),
-                ...(context?.includeScreenshotDataUrl && annotatedScreenshot?.screenshotDataUrl ? { screenshotDataUrl: annotatedScreenshot.screenshotDataUrl } : {})
+                ...(context?.includeScreenshotDataUrl && annotatedDataUrl ? { screenshotDataUrl: annotatedDataUrl } : {})
             });
             if (trackAction) {
                 trackAction(action);

package/build/src/core/prompts.js

@@ -1,3 +1,3 @@
 export { buildBaseSystemPrompt } from "../prompts/base.js";
 export { buildDesignModePrompt, buildDesignRecoveryPrompt, buildDesignScriptGenerationPrompt, } from "../prompts/design.js";
-export { buildAppContextSection, buildAssertionSystemPrompt, buildExecutionModePrompt, buildExecutionNavigationRecoveryPrompt, buildExecutionRecoveryPrompt, buildTestDataContextSection, } from "../prompts/execution.js";
+export { buildAppContextSection, buildAssertionSystemPrompt, buildExecutionModePrompt, buildExecutionNavigationRecoveryPrompt, buildExecutionRecoveryPrompt, buildSecretKeysContextSection, buildTestDataContextSection, } from "../prompts/execution.js";

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

@@ -0,0 +1,88 @@
+// File/glue layer for the HTML report: reads a stored JUnit run-result XML, inlines
+// its sibling screenshot PNGs as base64 data URLs, and renders a self-contained HTML
+// document. Used by both the CLI (`--report`) and the Desktop App ("Share" button).
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseRunReport } from "./parse-run-report.js";
+import { renderHtmlReport } from "./render-html-report.js";
+const MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+};
+function mimeForPath(filePath) {
+    return MIME_BY_EXT[path.extname(filePath).toLowerCase()] ?? "image/png";
+}
+// Resolves a screenshotPath (relative to the results directory) to an absolute path,
+// guarding against escaping the results directory via traversal. Returns null if the
+// resolved path would fall outside `resultsDir`.
+function resolveScreenshotPath(resultsDir, screenshotPath) {
+    if (typeof screenshotPath !== "string" || screenshotPath.length === 0)
+        return null;
+    const resolved = path.resolve(resultsDir, screenshotPath);
+    const base = path.resolve(resultsDir);
+    if (resolved !== base && !resolved.startsWith(base + path.sep))
+        return null;
+    return resolved;
+}
+// Reads an image file and returns a data URL, or null if it cannot be read.
+async function toDataUrl(filePath) {
+    try {
+        const buffer = await readFile(filePath);
+        return `data:${mimeForPath(filePath)};base64,${buffer.toString("base64")}`;
+    }
+    catch {
+        return null;
+    }
+}
+// Walks every event (top-level and child tests) and replaces payload.screenshotPath
+// with an inlined payload.screenshotDataUrl read from disk. Missing files are skipped.
+async function inlineScreenshots(model, resultsDir) {
+    const allEventLists = [model.events ?? []];
+    for (const child of model.childTests ?? []) {
+        allEventLists.push(child.events ?? []);
+    }
+    for (const events of allEventLists) {
+        for (const event of events) {
+            const screenshotPath = event.payload?.screenshotPath;
+            if (typeof screenshotPath !== "string" || screenshotPath.length === 0)
+                continue;
+            if (typeof event.payload?.screenshotDataUrl === "string")
+                continue; // already inlined
+            const absolute = resolveScreenshotPath(resultsDir, screenshotPath);
+            if (!absolute)
+                continue;
+            const dataUrl = await toDataUrl(absolute);
+            if (dataUrl) {
+                event.payload = { ...event.payload, screenshotDataUrl: dataUrl };
+            }
+        }
+    }
+    return model;
+}
+// Builds the HTML report from an in-memory model. Screenshots are inlined from
+// `resultsDir` (the directory the relative screenshotPath values are based on).
+export async function generateHtmlReportFromModel(model, { resultsDir, title } = {}) {
+    if (resultsDir) {
+        await inlineScreenshots(model, resultsDir);
+    }
+    return renderHtmlReport(model, { title });
+}
+// Reads a stored run-result XML file and produces both the self-contained HTML report
+// and the parsed model (so callers can derive a filename from testName/timestamp without
+// re-reading the file). Screenshots are read from the sibling directory the relative
+// screenshotPath values reference (which is the XML file's own directory).
+export async function generateReportFromXmlFile(xmlPath, { title } = {}) {
+    const xml = await readFile(xmlPath, "utf-8");
+    const model = parseRunReport(xml);
+    const resultsDir = path.dirname(path.resolve(xmlPath));
+    const html = await generateHtmlReportFromModel(model, { resultsDir, title });
+    return { html, model };
+}
+// Convenience wrapper returning just the HTML for callers that don't need the model.
+export async function generateHtmlReportFromXmlFile(xmlPath, options = {}) {
+    const { html } = await generateReportFromXmlFile(xmlPath, options);
+    return html;
+}