@loadmill/droid-cua 2.22.0 → 2.24.0

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

@@ -4,15 +4,15 @@ import { connectToBrowser, getBrowserInfo, getCurrentPlatform as getBrowserCurre
 import { normalizeBrowserInfoForSession } from "../browser/normalize.js";
 import { sendCUARequest } from "../device/openai.js";
 import { buildExecutionRecoveryPrompt } from "../core/prompts.js";
-import { isAssertion } from "../device/assertions.js";
+import { extractAssertionPrompt, isAssertion } from "../device/assertions.js";
+import { handleAssertionToolCall } from "../core/tool-handlers/assert.js";
 import { logger } from "../utils/logger.js";
 import { emitDesktopDebug } from "../utils/desktop-debug.js";
 import { printCliOutput } from "../utils/console-output.js";
-// Mirrors the codes emitted by the Loadmill LLM gateway (see services/app/private/llm
-// in the server repo): a transient burst limit plus day/week/fixed-budget request and
-// token quotas. Free plans run on the fixed-budget quota.
+// Mirrors the quota codes emitted by the Loadmill LLM gateway (see
+// services/app/private/llm in the server repo). Free plans run on the
+// fixed-budget quota.
 const LLM_USAGE_LIMIT_ERROR_CODES = new Set([
-    "llm_rate_limit_exceeded",
     "llm_day_quota_exceeded",
     "llm_week_quota_exceeded",
     "llm_fixed_budget_quota_exceeded",
@@ -21,6 +21,8 @@ const LLM_USAGE_LIMIT_ERROR_CODES = new Set([
     "llm_fixed_budget_token_quota_exceeded",
 ]);
 const LOADMILL_UPGRADE_URL = "https://www.loadmill.com/book-a-demo";
+const LLM_REQUEST_RATE_LIMIT_ERROR_CODE = "llm_rate_limit_exceeded";
+const DEFAULT_ASSERTION_CONTEXT = "No additional prior context is needed; validate directly from the current screen.";
 function isLlmUsageLimitError(err) {
     if (!err || typeof err !== "object") {
         return false;
@@ -30,9 +32,15 @@ function isLlmUsageLimitError(err) {
     }
     return err.status === 429 && err.type === "rate_limit_error";
 }
+function isLlmRequestRateLimitError(err) {
+    return err && typeof err === "object" && err.code === LLM_REQUEST_RATE_LIMIT_ERROR_CODE;
+}
 function getLlmUsageLimitMessage() {
     return `Execution stopped: you've reached the AI usage limit for this account. Contact the Loadmill team to upgrade: ${LOADMILL_UPGRADE_URL}`;
 }
+function getLlmRequestRateLimitMessage() {
+    return "Execution stopped: too many AI requests are running for this account right now. Please retry shortly or reduce parallel test runs.";
+}
 /**
  * Execution Mode - Run test scripts line-by-line
  * Each instruction is executed in isolation (messages cleared after each turn)
@@ -105,10 +113,11 @@ export class ExecutionMode {
         lines.push(`  Retries:      ${this.stats.retryCount}`);
         return lines;
     }
-    buildStepContext(instructionIndex) {
+    buildStepContext(instructionIndex, instruction = null) {
         return {
             instructionIndex,
             stepId: `step-${String(instructionIndex + 1).padStart(4, "0")}`,
+            ...(typeof instruction === "string" ? { instruction } : {}),
         };
     }
     emit(addOutput, type, text, context = {}, stepContext = null, extra = {}) {
@@ -123,6 +132,45 @@ export class ExecutionMode {
             payload: extra.payload
         });
     }
+    resetInstructionConversationState() {
+        this.session.updateResponseId(null);
+        if (typeof this.session.clearTranscript === "function") {
+            this.session.clearTranscript();
+            return;
+        }
+        if (Array.isArray(this.session.transcript)) {
+            this.session.transcript = [];
+        }
+    }
+    async executeVerificationInstruction(instruction, context, stepContext = null) {
+        const toolResult = await handleAssertionToolCall({
+            engine: this.engine,
+            callId: stepContext?.stepId ? `${stepContext.stepId}-assert` : "instruction-assert",
+            argumentsText: JSON.stringify({
+                condition: extractAssertionPrompt(instruction),
+                context: DEFAULT_ASSERTION_CONTEXT,
+            }),
+            context,
+            stepContext,
+        });
+        const assertionStatus = toolResult.summaryUpdates?.assertionStatus;
+        if (assertionStatus === "passed") {
+            this.stats.assertionsPassed++;
+        }
+        else if (assertionStatus === "failed" || assertionStatus === "failed_skipped") {
+            this.stats.assertionsFailed++;
+        }
+        if (toolResult.kind === "retry_instruction") {
+            this.stats.retryCount++;
+            this.session.clearMessages();
+            return await this.executeInstruction(instruction, context, 0, stepContext);
+        }
+        if (toolResult.kind === "fail") {
+            return { success: false, error: toolResult.error || "Assertion failed." };
+        }
+        this.session.clearMessages();
+        return { success: true };
+    }
     /**
      * Execute all instructions in the test script
      * @param {Object} context - Additional context (Ink context with addOutput)
@@ -137,7 +185,8 @@ export class ExecutionMode {
         // Start timing
         this.stats.startTime = Date.now();
         for (let i = 0; i < this.instructions.length; i++) {
-            const stepContext = this.buildStepContext(i);
+            const instruction = this.instructions[i];
+            const stepContext = this.buildStepContext(i, instruction);
             // Check if execution should be stopped
             if (this.shouldStop) {
                 this.emit(addOutput, 'info', 'Test execution stopped by user.', runContext, stepContext, {
@@ -158,7 +207,6 @@ export class ExecutionMode {
                     return { success: false, error: 'Stopped by user' };
                 }
             }
-            const instruction = this.instructions[i];
             this.emit(addOutput, 'user', instruction, runContext, stepContext, {
                 eventType: 'instruction_started',
                 payload: {
@@ -236,10 +284,17 @@ export class ExecutionMode {
         const MAX_RETRIES = 10;
         const instructionContext = {
             ...context,
+            currentInstruction: instruction,
             futureInstructions: this.instructions.slice((stepContext?.instructionIndex ?? -1) + 1),
         };
+        if (retryCount === 0) {
+            this.resetInstructionConversationState();
+        }
         this.session.addToTranscript(`[User] ${instruction}`);
         this.session.addMessage("user", instruction);
+        if (isAssertion(instruction)) {
+            return await this.executeVerificationInstruction(instruction, instructionContext, stepContext);
+        }
         try {
             const screenshotBase64 = await this.getScreenshotAsBase64(this.session.deviceId, this.session.deviceInfo);
             const currentScreenshot = await this.engine.recordScreenshot?.(screenshotBase64, {
@@ -309,6 +364,26 @@ export class ExecutionMode {
                 stack: err.stack
             });
             const addOutput = context.addOutput || printCliOutput;
+            if (isLlmRequestRateLimitError(err)) {
+                const stopMessage = getLlmRequestRateLimitMessage();
+                logger.debug('Stopping execution because an LLM request rate limit was reached', {
+                    instruction,
+                    message: err.message,
+                    status: err.status,
+                    code: err.code,
+                    type: err.type,
+                });
+                this.emit(addOutput, 'error', stopMessage, context, stepContext, {
+                    eventType: 'error',
+                    payload: {
+                        message: stopMessage,
+                        status: err.status,
+                        code: err.code,
+                        type: err.type,
+                    }
+                });
+                return { success: false, error: stopMessage, usageLimitReached: true };
+            }
             if (isLlmUsageLimitError(err)) {
                 const stopMessage = getLlmUsageLimitMessage();
                 logger.debug('Stopping execution because an LLM usage limit was reached', {
@@ -449,6 +524,7 @@ export class ExecutionMode {
             });
             // Replace the system message with the enhanced one
             this.session.installRecoverySystemPrompt(recoverySystemPrompt);
+            this.session.updateResponseId(null);
             // Wait a bit before retrying
             await new Promise(resolve => setTimeout(resolve, 1000));
             // Retry the same instruction with incremented counter

package/build/src/prompts/design.js

@@ -139,7 +139,9 @@ Test design exploration is complete. Use the validated completion summary below
 Do not call tools.
 Do not continue exploring.
 Do not add explanation.
-Output only the final result in the required design-mode format.
+Output only the exact final result format below: one "Suggested test name:" line, then one fenced code block.
+Do not use TEST NAME, GOAL, STEPS, VERIFICATIONS, FINAL STATE, markdown headings, numbered lists, or bullets.
+The fenced code block must contain only executable test instructions, one per line, ending with exit.
 
 Completion summary:
 Suggested test name: ${suggestedTestName || "(choose a short kebab-case name)"}
@@ -151,3 +153,21 @@ Verification points:
 ${formatStringList(summary.verificationPoints)}
 ${notesForScript ? `Notes for script:\n${notesForScript}\n` : ""}`;
 }
+export function buildDesignScriptFormatRetryPrompt(previousOutput = "") {
+    const previousOutputText = typeof previousOutput === "string" ? previousOutput.trim() : "";
+    return `AUTHORING FORMAT CORRECTION:
+Your previous answer did not use the required design-mode format.
+
+Output only:
+Suggested test name: short-kebab-case-name
+
+\`\`\`
+one executable instruction per line
+exit
+\`\`\`
+
+Do not include TEST NAME, GOAL, STEPS, VERIFICATIONS, FINAL STATE, markdown headings, numbered lists, bullets, or explanation.${previousOutputText ? `
+
+Previous output to reformat:
+${previousOutputText}` : ""}`;
+}

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

@@ -1,4 +1,5 @@
 import { classifyCaptureSource } from "../core/capture-sources.js";
+import { stepCompletionData } from "../core/report/run-log-model.js";
 function isHiddenExecutionOutput(item) {
     const captureSource = item?.payload?.captureSource;
     return classifyCaptureSource(captureSource).mediaKind === "hidden-debug";
@@ -24,6 +25,10 @@ export function formatCliOutput(item) {
         if (!text || text.trim().length === 0) {
             return null;
         }
+        const stepCompletion = stepCompletionData(text);
+        if (stepCompletion) {
+            return `assistant: Step complete — ${stepCompletion.instruction}`;
+        }
         return text
             .split("\n")
             .map((line) => `assistant: ${line}`)

package/build/src/utils/cua-debug-tracer.js

@@ -92,6 +92,54 @@ function summarizeRequestInput(input) {
         };
     });
 }
+function extractImageBase64Length(imageUrl) {
+    return typeof imageUrl === "string" ? imageUrl.replace("data:image/png;base64,", "").length : 0;
+}
+function summarizeRequestScreenshots(input, deviceInfo) {
+    const screenshots = [];
+    for (const item of input) {
+        if (item?.role && Array.isArray(item.content)) {
+            for (const entry of item.content) {
+                if (entry?.type !== "input_image" || typeof entry.image_url !== "string")
+                    continue;
+                screenshots.push({
+                    source: `message:${item.role}`,
+                    base64Length: extractImageBase64Length(entry.image_url),
+                });
+            }
+            continue;
+        }
+        if (item?.type === "computer_call_output" && typeof item.output?.image_url === "string") {
+            screenshots.push({
+                source: "computer_call_output",
+                callId: item.call_id,
+                base64Length: extractImageBase64Length(item.output.image_url),
+            });
+            continue;
+        }
+        if (item?.type === "function_call_output" && Array.isArray(item.output)) {
+            for (const entry of item.output) {
+                if (entry?.type !== "input_image" || typeof entry.image_url !== "string")
+                    continue;
+                screenshots.push({
+                    source: "function_call_output",
+                    callId: item.call_id,
+                    base64Length: extractImageBase64Length(entry.image_url),
+                });
+            }
+        }
+    }
+    if (screenshots.length === 0) {
+        return null;
+    }
+    return {
+        count: screenshots.length,
+        sources: screenshots.map((entry) => entry.source),
+        base64Lengths: screenshots.map((entry) => entry.base64Length),
+        width: deviceInfo?.scaled_width ?? null,
+        height: deviceInfo?.scaled_height ?? null,
+    };
+}
 function redactRequestForFileLog(requestParams) {
     return {
         ...requestParams,
@@ -223,6 +271,7 @@ export class CuaDebugTracer {
         const localRequestId = crypto.randomUUID();
         const requestLog = redactRequestForFileLog(requestParams);
         const messages = summarizeRequestInput(input);
+        const screenshot = summarizeRequestScreenshots(input, deviceInfo);
         const acknowledgedSafetyChecksSent = input
             .filter((item) => item?.type === "computer_call_output")
             .flatMap((item) => {
@@ -260,13 +309,7 @@ export class CuaDebugTracer {
             inputItemTypes,
             inputCallIds,
             messages,
-            screenshot: screenshotBase64
-                ? {
-                    width: deviceInfo?.scaled_width ?? null,
-                    height: deviceInfo?.scaled_height ?? null,
-                    base64Length: screenshotBase64.length
-                }
-                : null,
+            screenshot,
             safetyChecks: {
                 previousPending: previousPendingSafetyChecks,
                 previousPendingCount: previousPendingSafetyChecks.length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "build/**/*",
     "bin/**/*",
+    "skill/**/*",
     "README.md",
     "LICENSE"
   ],

package/skill/droid-cua/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: droid-cua
+description: Write, run, monitor, and troubleshoot Droid CUA mobile and web tests. Use when an agent needs to onboard @loadmill/droid-cua, configure Loadmill authentication, discover Android devices or AVDs, prepare iOS simulators or local browsers, author or revise .dcua tests and project context, run tests locally or on supported cloud devices, analyze reports and debug artifacts, distinguish test failures from product bugs, or perform guarded test healing.
+---
+
+# Droid CUA
+
+Use the existing `droid-cua` CLI and repository files. Do not invent commands, flags, or product capabilities.
+
+## Workflow
+
+1. Inspect the active test project before creating files. Find existing `.dcua` tests, `context.md`, `test-data.md`, `.secrets`, `.env`, and `ci/droid-cua.json` without reading secret values. Do not search other projects or the user's home directory for credentials.
+2. Determine the requested platform and target from the task or project. Ask the user only when the choice is unclear.
+3. Check authentication and environment readiness before the first run. Read [project-and-auth.md](references/project-and-auth.md) for project boundaries and token handling. Read [onboarding-and-troubleshooting.md](references/onboarding-and-troubleshooting.md) when setup, dependency, device, simulator, browser, or connection work is needed.
+4. Author or update the smallest useful test. Read [authoring-tests.md](references/authoring-tests.md) before changing `.dcua`, context, test data, secrets, or config.
+5. Run the narrowest relevant test and monitor it to completion. Read [running-and-healing.md](references/running-and-healing.md) for commands, targets, artifacts, failure classification, and guarded healing.
+6. Report the outcome, evidence paths, changes made, and whether the failure belongs to the test, environment, or product.
+
+## Safety
+
+- Never print, open, or echo secret values. Check only whether required keys are configured.
+- Never search for credentials outside the active test project or source another project's `.env` file.
+- Get approval before installing dependencies, running `sudo`, accepting licenses, or changing system configuration.
+- During setup, do not create or edit user tests. Rerun only the failed readiness check, then resume the original task.
+- During healing, edit only `.dcua`, `context.md`, `test-data.md`, or Droid CUA config. Never modify application code under the guise of healing a test.
+- Never weaken or remove an assertion merely to make a failing run pass.
+- Make one minimal change and run the affected test again. Stop after two edit/rerun cycles and present the evidence.
+- Stop immediately when evidence indicates a likely application regression; do not rewrite the test to match broken behavior.
+- Gracefully allow cloud runs to finish cleanup. Avoid terminating a metered device session unless necessary.
+
+## Operating principles
+
+- Prefer an existing project convention over creating a parallel structure.
+- Prefer headless runs for agent work because they are observable and return deterministic exit codes.
+- Use explicit, user-observable outcomes in tests rather than implementation details or coordinates.
+- Diagnose the first divergence between the instruction and observed behavior before changing anything.

package/skill/droid-cua/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Droid Cua"
+  short_description: "Write, run, monitor, and troubleshoot Droid CUA tests"
+  icon_small: "./assets/droid-cua-app-icon.png"
+  icon_large: "./assets/droid-cua-app-icon.png"
+  brand_color: "#1895F7"

package/skill/droid-cua/references/authoring-tests.md

@@ -0,0 +1,39 @@
+# Authoring tests
+
+## Inspect first
+
+Find nearby `.dcua` tests and project files before writing. Match their directory layout, naming, vocabulary, starting state, and config conventions. Do not open `.env` or `.secrets`.
+
+## Write `.dcua` instructions
+
+- Put one clear instruction or assertion on each non-empty line.
+- Describe visible UI intent, not coordinates, selectors, implementation details, or model strategy.
+- Prefer a high-level business intent when `context.md` makes the flow unambiguous. Do not translate every tap and keystroke into a brittle micro-script.
+- Break an instruction down only when the agent demonstrably needs help finding a control or completing part of the flow.
+- State the starting condition when it is not guaranteed by the environment.
+- Use explicit assertions for important outcomes. Prefer stable visible facts such as a screen title, confirmation message, changed value, or navigation result.
+- Use exact visible labels when naming controls or outcomes.
+- Keep each test focused on one behavior. Split unrelated flows.
+- Use `//` comments sparingly for human context; comments are not executed.
+- Never include secret values in the test.
+
+Example:
+
+```text
+Sign in using the USER_EMAIL and USER_PASSWORD secrets.
+Assert that the Home screen is visible and shows the signed-in account.
+```
+
+Use the secret key names that exist in `.secrets`; do not inspect their values. If key discovery is necessary, filter the file so only keys reach output, for example `sed -n 's/^\([^#][^=]*\)=.*/\1/p' .secrets`. If a required key is absent, ask the user to add it without sharing its value.
+
+## Put knowledge in the right place
+
+- Put durable product behavior and terminology in `context.md`, not repeated in every test.
+- Put non-secret reusable people, accounts, products, and scenario combinations in `test-data.md`.
+- Put credentials and sensitive values in `.secrets`.
+- Put reproducible headless settings in `ci/droid-cua.json`.
+- Keep environment and provider credentials in `.env` or the shell/CI secret store.
+
+Use `--scenario "<goal>" --test-data <path>` only when the user wants generated permutations or cases. A normal `.dcua` run does not automatically consume `test-data.md`.
+
+After editing, show the user the test instructions and explain any new context, data keys, or secret keys required. Never show secret values.

package/skill/droid-cua/references/onboarding-and-troubleshooting.md

@@ -0,0 +1,74 @@
+# Onboarding and troubleshooting
+
+Follow the Desktop Device Setup Wizard sequence: choose a platform, run checks, discover/connect a target, verify runtime access during the requested run, then continue the original task. Run authentication as the separate first preflight described in `project-and-auth.md`.
+
+Do not create or modify user test files merely to perform setup. Get approval before installing software, changing system configuration, running `sudo`, or accepting a license. After remediation, rerun only the failed check.
+
+## Android
+
+Resolve `adb` and `emulator` from `ANDROID_HOME`, `ANDROID_SDK_ROOT`, the macOS default `~/Library/Android/sdk`, the Windows default `%LOCALAPPDATA%\Android\Sdk`, then `PATH`. Respect explicit `DROID_CUA_ANDROID_ADB_PATH` and `DROID_CUA_ANDROID_EMULATOR_PATH` overrides.
+
+Run these checks:
+
+```sh
+adb version
+emulator -list-avds
+adb devices
+```
+
+- `adb` is blocking.
+- The emulator CLI and existence of an AVD are individually non-blocking.
+- Target availability is blocking and passes when `adb devices` contains a `device` entry or `emulator -list-avds` contains a launchable AVD.
+- For `unauthorized`, ask the user to accept the computer authorization prompt on the device.
+- For `offline`, reconnect the device or restart ADB, then retry.
+- If nothing is available, guide the user to connect a device or create an AVD in Android Studio Device Manager.
+
+Use `--avd adb:<serial>` for an attached target and `--avd avd:<name>` to launch an AVD.
+
+## iOS
+
+Local iOS execution requires macOS. Run checks in this order:
+
+```sh
+xcrun --version
+xcode-select -p
+xcodebuild -license check
+xcodebuild -checkFirstLaunchStatus
+node --version
+npm --version
+appium --version
+appium driver list --installed
+xcrun simctl list devices --json
+```
+
+Require `xcode-select -p` to point to an `/Xcode*.app/Contents/Developer` path, an installed XCUITest driver, and at least one available iPhone simulator. A booted simulator is helpful but not blocking.
+
+Offer only the relevant remediation, with approval:
+
+```sh
+sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+sudo xcodebuild -license accept
+sudo xcodebuild -runFirstLaunch
+npm install -g appium
+appium driver install xcuitest
+```
+
+Use `--platform ios --avd "<simulator name>"` for the run.
+
+## Web
+
+Droid CUA automatically discovers Chrome or Edge on macOS and Windows. Check the standard application locations, then run the requested test with `--target web --browser <chrome|edge> --session-mode fresh`. A successful Playwright launch is the runtime verification; do not create a persistent setup-only test.
+
+On Linux, automatic installed-browser discovery is not currently supported. Do not claim that a PATH-installed browser will be found.
+
+## Cloud targets
+
+For LambdaTest, require `LAMBDATEST_USERNAME`, `LAMBDATEST_ACCESS_KEY`, a device name, OS version, and `.apk` or `.ipa`. The CLI uploads the app for each run.
+
+For AWS Device Farm, require `AWS_DEVICE_FARM_ACCESS_KEY_ID`, `AWS_DEVICE_FARM_SECRET_ACCESS_KEY`, and `AWS_DEVICE_FARM_PROJECT_ARN`. Discover targets with:
+
+```sh
+droid-cua --device-source aws-device-farm --list-devices
+```
+
+Do not document BrowserStack CLI runs; BrowserStack is not consistently exposed by the current CLI.

package/skill/droid-cua/references/project-and-auth.md

@@ -0,0 +1,38 @@
+# Project files and authentication
+
+## Project files
+
+- `.dcua`: executable test instructions. Each non-empty line is one instruction; `//` begins a comment.
+- `context.md`: durable knowledge about product terminology, screens, navigation, and behavior. Pass it with `--context`, or reference it from `ci/droid-cua.json`.
+- `test-data.md`: non-secret entities and scenario inputs. It is used with `--scenario` and `--test-data`; it is not automatically loaded by every normal test run.
+- `.secrets`: dotenv-style values that Droid CUA may type into the tested application. The model receives the keys, not the resolved values. Headless execution loads this file from the current working directory; `--secrets` overrides it.
+- `.env`: infrastructure credentials and runtime environment variables loaded from the current working directory, including `LOADMILL_API_TOKEN`.
+- `ci/droid-cua.json`: optional checked-in headless config. Paths inside it are relative to the config file.
+- `logs/`: structured JSONL and screenshot artifacts created by `--debug`.
+- HTML reports: self-contained evidence produced by `--report`.
+
+Keep `.env` and `.secrets` out of version control. Use `git check-ignore -q .env` and `git check-ignore -q .secrets` to check ignore coverage without opening either file.
+
+## Loadmill authentication
+
+Loadmill is the default LLM provider. Before a run, check only for presence:
+
+```sh
+test -n "${LOADMILL_API_TOKEN:-}" || grep -Eq '^LOADMILL_API_TOKEN=.+$' .env 2>/dev/null
+```
+
+Run this check from the active test project's working directory. Do not print the variable, run `env`, open `.env`, or ask the user to paste the token. Do not search parent directories, sibling repositories, the user's home directory, or the Droid CUA source repository for credentials.
+
+If it is missing, instruct the user to:
+
+1. Sign in at <https://app.loadmill.com>.
+2. Open **Settings → Security**.
+3. Create an API token with a description such as `Droid CUA CLI`.
+4. Copy it when shown; Loadmill shows it once.
+5. Ensure `.env` is ignored by version control before storing a project token; add `.env` to `.gitignore` if needed.
+6. Save it as `LOADMILL_API_TOKEN=...` in the active test project's `.env`, a shell environment variable, or a CI secret.
+7. Confirm when configuration is complete, without sharing the value.
+
+Do not create or populate the token value for the user. Do not copy a token from another file or source another project's `.env`. Sourcing an unrelated file can import development endpoints, proxy settings, and unrelated secrets. When the active project's `.env` contains the key, run `droid-cua` normally from that project; the CLI loads that file automatically.
+
+If the user explicitly selects direct OpenAI access, use `--llm-provider openai` with one of the supported OpenAI CUA models: `gpt-5.6-terra`, `gpt-5.6-luna`, or `gpt-5.4`. Check only for the presence of `OPENAI_API_KEY`. If it is missing, instruct the user to create an API key in their OpenAI account and save it in the active project's gitignored `.env`, their shell environment, or a CI secret. Apply the same secret-handling rules: never request, print, inspect, copy, or source the key. Do not silently switch providers to bypass missing Loadmill authentication.

package/skill/droid-cua/references/running-and-healing.md

@@ -0,0 +1,70 @@
+# Running, monitoring, and guarded healing
+
+## Construct the run
+
+Prefer a single test before a directory or scenario run. Preserve an existing provider/model choice in `ci/droid-cua.json`; otherwise use the Loadmill provider. Use Loadmill Smart as the recommended default, or Loadmill Beacon when the user prioritizes faster, lower-cost execution:
+
+```sh
+# Recommended default
+--llm-provider loadmill --cua-model loadmill-smart
+
+# Faster, lower-cost option
+--llm-provider loadmill --cua-model loadmill-beacon
+```
+
+Both Loadmill models require `LOADMILL_API_TOKEN`. Do not switch between Smart and Beacon silently; preserve the project's model or explain the speed/cost tradeoff and follow the user's choice. If the user chooses direct OpenAI access instead, require `OPENAI_API_KEY` and use `--llm-provider openai` with one of `gpt-5.6-terra`, `gpt-5.6-luna`, or `gpt-5.4`. Do not mix a provider with another provider's model, silently switch providers, or override an existing project choice without explaining it.
+
+Include `--report reports/<test-name>.html` for normal test runs unless the user opts out. Prefer an explicit filename over a directory so the result is easy to locate. Add `--debug` when diagnosis may be needed.
+
+```sh
+# Attached Android device or running emulator
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --avd adb:<serial> --instructions tests/example.dcua --context tests/context.md --debug --report reports/example.html
+
+# Launchable Android AVD
+droid-cua --avd avd:<avd-name> --instructions tests/example.dcua --config ci/droid-cua.json --debug --report reports/example.html
+
+# iOS Simulator
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --platform ios --avd "<simulator-name>" --instructions tests/example.dcua --debug --report reports/example.html
+
+# Local web
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --target web --browser chrome --session-mode fresh --instructions tests/example.dcua --debug --report reports/example.html
+
+# LambdaTest
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --device-source lambdatest --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --instructions tests/example.dcua --debug --report reports/example.html
+
+# AWS Device Farm
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --device-source aws-device-farm --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --instructions tests/example.dcua --debug --report reports/example.html
+
+# Direct OpenAI alternative
+droid-cua --llm-provider openai --cua-model gpt-5.4 --avd adb:<serial> --instructions tests/example.dcua --context tests/context.md --debug --report reports/example.html
+```
+
+Use `.ipa` and `--platform ios` for supported cloud iOS runs. Preserve existing config flags rather than replacing them with defaults.
+
+## Monitor and collect evidence
+
+Remain attached until the command exits and cloud cleanup finishes. Read terminal progress as it appears; do not treat a long model step as success or failure before completion.
+
+- Exit `0`: all requested tests passed.
+- Exit `1`: configuration, connection, execution, or assertion failure.
+- Exit `130`: interrupted run.
+- `--debug`: writes structured execution JSONL and adjacent screenshots under `logs/`.
+- `--report`: writes a self-contained HTML report. Prefer an explicit `.html` file path such as `reports/example.html` so the evidence location is unambiguous.
+
+After the run, verify that the report exists and resolve its absolute path. Open it for the user when the agent environment supports local-file opening and policy permits; otherwise provide a clickable local-file link or the absolute path so the user can open it directly.
+
+Report the outcome, failing instruction and first divergence when applicable, relevant error text, screenshot/debug/report paths, target, provider/model, and command with secret values omitted.
+
+## Classify the first divergence
+
+1. **Setup or authentication**: missing/invalid provider credential, dependency, license, browser, or executable. Return to onboarding and rerun only the failed check.
+2. **Target connectivity**: no device, unauthorized/offline ADB state, unavailable simulator, cloud credential/device/app problem, or lost session. Restore the same target, then rerun.
+3. **Test ambiguity or stale test knowledge**: instruction has multiple interpretations, relies on an unstable label, lacks a starting condition, or context contradicts the visible product. A minimal test/context correction is allowed.
+4. **Application regression**: the app crashes, displays an error, violates an explicit requirement, or consistently fails a stable assertion after correct setup. Stop and report a bug with evidence.
+5. **Transient execution**: temporary network, service, model, or timing failure without evidence of a deterministic product/test issue. Retry the unchanged targeted test once.
+
+## Guarded healing
+
+Before editing, state the classification and evidence. Change only `.dcua`, `context.md`, `test-data.md`, or Droid CUA config. Never edit app code, delete coverage, loosen the expected outcome, or add broad waits simply to obtain green output.
+
+Make one minimal change, explain why it corrects the test rather than hides a product defect, and rerun only the affected test. Allow at most two edit/rerun cycles. If it still fails, stop with the original and final evidence, changes attempted, and recommended owner/action.

package/build/src/core/cua-backends.js

@@ -1,11 +0,0 @@
-export const CUA_BACKENDS = ["openai", "fara"];
-export const DEFAULT_CUA_BACKEND = "openai";
-export const DEFAULT_FARA_BASE_URL = "http://localhost:5000/v1";
-export const DEFAULT_FARA_MODEL = "Fara-7B";
-const VALID_CUA_BACKENDS = new Set(CUA_BACKENDS);
-export function isValidCuaBackend(value) {
-    return VALID_CUA_BACKENDS.has(value);
-}
-export function resolveCuaBackend(value) {
-    return isValidCuaBackend(value) ? value : DEFAULT_CUA_BACKEND;
-}