@loadmill/droid-cua 2.43.0 → 2.45.0

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

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import path from "path";
 import { mkdir, writeFile } from "fs/promises";
 import { getNetworkCaptureContext, navigateToUrl as navigateBrowserToUrl, getBrowserInfo, getCurrentPlatform as getBrowserCurrentPlatform, getScreenshotAsBase64 as getBrowserScreenshotAsBase64, } from "../browser/connection.js";
@@ -9,6 +10,7 @@ import { buildExecutionModePrompt } from "../core/prompts.js";
 import { addOpenAiResponseToDroidCuaRunUsage, createDroidCuaRunUsageTotals, estimateDroidCuaRunCostUsd, setDroidCuaRunUsageModel, } from "../core/droid-cua-run-usage.js";
 import { getDroidVersion } from "../core/droid-version.js";
 import { ExecutionMode } from "../modes/execution-mode.js";
+import { STEP_WATCHDOG_MODEL } from "../core/step-watchdog.js";
 import { buildDroidRunConfiguration, reportDroidRunCompletion, } from "../integrations/loadmill/run-reporter.js";
 import { droidReportUploadManager } from "../integrations/loadmill/report-upload-manager.js";
 import { reportDroidCuaCiTestRunCompleted } from "../integrations/segment/droid-cua-segment.js";
@@ -28,10 +30,6 @@ function sanitizePathSegment(value) {
         .replace(/-+/g, "-")
         .replace(/^[-_.]+|[-_.]+$/g, "") || "test";
 }
-function createHeadlessRunId(index = 0) {
-    const suffix = index > 0 ? `-${index + 1}` : "";
-    return `run-${Date.now()}${suffix}`;
-}
 function networkLogPath(runId, report) {
     if (!report?.enabled)
         return path.resolve("logs", `network-${runId}.jsonl`);
@@ -73,14 +71,14 @@ function getRecordScreenshotDirForTest(baseScreenshotDir, testName, isBatchRun)
     }
     return path.join(baseScreenshotDir, sanitizePathSegment(testName));
 }
-function toDroidCuaSegmentRunStatus(success, error = null) {
+function toDroidCuaSegmentRunStatus(success, error = null, failureKind = null) {
     if (success) {
         return "pass";
     }
     if (error === "Stopped by user") {
         return "skipped";
     }
-    if (typeof error === "string" && error.startsWith("Assertion failed:")) {
+    if (failureKind === "step_watchdog" || (typeof error === "string" && error.startsWith("Assertion failed:"))) {
         return "failure";
     }
     return "error";
@@ -179,7 +177,7 @@ export function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, exe
     }
     return engineOptions;
 }
-async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isDesktopTarget, desktopController, isCloudTarget, runTarget = null, secrets = null, report = null, isBatchRun = false, reportToLoadmill = true, runConfiguration = {}, cloudUploadSession = null, uploadManager = droidReportUploadManager, networkCapture = null, initialBrowserUrl = null, }) {
+async function runHeadlessTest({ runId, captureIndex = 0, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isDesktopTarget, desktopController, isCloudTarget, runTarget = null, secrets = null, report = null, isBatchRun = false, reportToLoadmill = true, runConfiguration = {}, cloudUploadSession = null, uploadManager = droidReportUploadManager, networkCapture = null, initialBrowserUrl = null, }) {
     let executionMode = null;
     let captureStarted = false;
     const finishCapture = async () => {
@@ -201,12 +199,13 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         }
     };
     let loadmillSessionUser = null;
+    let stepWatchdogUsage = createDroidCuaRunUsageTotals({ model: STEP_WATCHDOG_MODEL });
     let runUsageTotals = setDroidCuaRunUsageModel(createDroidCuaRunUsageTotals(), runtimeContext.config.cuaModel);
     const buildSegmentUsageProperties = () => ({
         model: runUsageTotals.model,
         llmProviderMode: runtimeContext.config.llmProviderMode,
-        estimatedCostUsd: estimateDroidCuaRunCostUsd(runUsageTotals),
-        tokensUsed: runUsageTotals.totalTokens,
+        estimatedCostUsd: estimateDroidCuaRunCostUsd(runUsageTotals, stepWatchdogUsage),
+        tokensUsed: runUsageTotals.totalTokens + stepWatchdogUsage.totalTokens,
     });
     const reportSegmentRunCompleted = async (input) => {
         await reportDroidCuaCiTestRunCompleted({
@@ -288,7 +287,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         if (networkCapture) {
             try {
                 const browserContext = isBrowserTarget ? getNetworkCaptureContext(session.deviceId) : null;
-                const capturePath = await networkCapture.startCapture(networkLogPath(runId, report), { browserContext });
+                const capturePath = await networkCapture.startCapture(networkLogPath(isBatchRun ? `${runId}-${captureIndex + 1}` : runId, report), { browserContext });
                 console.log(`Network log: ${capturePath}`);
                 captureStarted = true;
                 engine.networkQuery = networkCapture.query;
@@ -309,6 +308,10 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             loadmillClient: runtimeContext.loadmillClient,
             runtimeConfig: runtimeContext.config,
             runtimeCredentials: runtimeContext.credentials,
+            testDataContext,
+            onStepWatchdogResponse: (response) => {
+                stepWatchdogUsage = addOpenAiResponseToDroidCuaRunUsage(stepWatchdogUsage, response);
+            },
             // Inline screenshots as data URLs so the HTML report is self-contained.
             ...(reportEnabled ? { includeScreenshotDataUrl: true } : {}),
         });
@@ -318,6 +321,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         await headlessDebug.endExecutionSession(runId, {
             success: Boolean(result.success),
             error: result.error ?? null,
+            failureKind: result.failureKind,
             durationMs,
             instructionsTotal: instructions.length,
             instructionsCompleted: stats.instructionsCompleted ?? 0,
@@ -327,7 +331,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             retries: stats.retryCount ?? 0
         });
         await reportSegmentRunCompleted({
-            status: toDroidCuaSegmentRunStatus(Boolean(result.success), result.error ?? null),
+            status: toDroidCuaSegmentRunStatus(Boolean(result.success), result.error ?? null, result.failureKind),
             durationMs,
             numOfSteps: instructions.length,
         });
@@ -338,6 +342,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
                 loadmillClient: runtimeContext.loadmillClient,
                 source: "ci",
                 runId,
+                outcome: toDroidCuaSegmentRunStatus(Boolean(result.success), result.error ?? null, result.failureKind),
                 projectName: path.basename(path.dirname(testPath)) || null,
                 testName,
                 runType: "test",
@@ -363,12 +368,17 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             console.error(`\nTest failed: ${result.error}`);
         }
         const reportInput = {
+            deviceInfo,
             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,
+            failureKind: result.failureKind,
+            ...(runtimeContext.config.stepWatchdogMode !== "off" && runtimeContext.config.stepWatchdogMode
+                ? { stepWatchdogMode: runtimeContext.config.stepWatchdogMode, stepWatchdogUsage }
+                : {}),
             instructionsTotal: instructions.length,
             stats,
         };
@@ -465,6 +475,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             });
         }
         const failedReportInput = {
+            deviceInfo,
             suiteName: path.basename(path.dirname(testPath)) || null,
             testName,
             startedAtIso: stats.startTime ? new Date(stats.startTime).toISOString() : null,
@@ -518,7 +529,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         throw error;
     }
 }
-export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, secrets = null, recordScreenshots, screenshotDir, isBrowserTarget, isDesktopTarget = false, desktopController = null, isCloudTarget, runTarget = null, report = null, droidVersion = getDroidVersion(), runHeadlessTestImpl = runHeadlessTest, uploadManager = droidReportUploadManager, networkCapture = null, initialBrowserUrl = null, }) {
+export async function runHeadlessInstructionRuns({ runId = randomUUID(), runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, secrets = null, recordScreenshots, screenshotDir, isBrowserTarget, isDesktopTarget = false, desktopController = null, isCloudTarget, runTarget = null, report = null, droidVersion = getDroidVersion(), runHeadlessTestImpl = runHeadlessTest, uploadManager = droidReportUploadManager, networkCapture = null, initialBrowserUrl = null, }) {
     await clearLoadmillReportMetadata(report?.metadataPath);
     const resolvedRunTarget = runTarget ?? { isBrowserTarget, isDesktopTarget, isCloudTarget };
     const runConfiguration = buildDroidRunConfiguration({
@@ -560,7 +571,6 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
     const aggregateLocalReportModels = [];
     const aggregateReportModels = [];
     for (const [index, run] of runs.entries()) {
-        const runId = createHeadlessRunId(index);
         const testScreenshotDir = getRecordScreenshotDirForTest(screenshotDir, run.testName, isBatchRun);
         if (isBatchRun) {
             console.log(`\n[${index + 1}/${runs.length}] ${run.testName}`);
@@ -572,6 +582,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             }
             const result = await runHeadlessTestImpl({
                 runId,
+                captureIndex: index,
                 testPath: run.testPath,
                 testName: run.testName,
                 instructions,
@@ -625,6 +636,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             const message = error instanceof Error ? error.message : String(error);
             if (instructionsTarget?.type === "selection" && (report?.enabled || cloudReportEnabled)) {
                 const failedReportModel = buildCliRunReportModel({
+                    deviceInfo,
                     suiteName: path.basename(path.dirname(run.testPath)) || null,
                     testName: run.testName,
                     startedAtIso: new Date().toISOString(),
@@ -670,6 +682,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
                 : path.basename(instructionsTarget.path);
         if (isSelection && report?.enabled && aggregateLocalReportModels.length > 0) {
             const aggregateReport = createCliAggregateRunReport({
+                deviceInfo,
                 suiteName: projectName,
                 testName,
                 startedAtIso: new Date(batchStartedAt).toISOString(),
@@ -691,7 +704,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             ...runConfiguration,
             loadmillClient: runtimeContext.loadmillClient,
             source: "ci",
-            runId: createHeadlessRunId(),
+            runId,
             projectName,
             testName,
             runType: "project",
@@ -715,6 +728,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
         });
         if (cloudUploadSession && reportedRun.savedRunId) {
             const aggregateReport = createCliAggregateRunReport({
+                deviceInfo,
                 suiteName: projectName,
                 testName,
                 startedAtIso: new Date(batchStartedAt).toISOString(),

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

@@ -1,4 +1,5 @@
 import { CLOUD_BROWSER_FAMILIES, CLOUD_BROWSER_VERSION_ALIASES, LOCAL_BROWSER_FAMILIES, } from "../browser/cloud-browser-catalog.js";
+import { parseIosDeviceToken } from "../device/ios/real-device/session.js";
 function normalizeTarget(value) {
     if (value == null || value === "") {
         return "mobile";
@@ -332,6 +333,9 @@ export function resolveHeadlessTarget(args = {}) {
     }
     if (deviceSource === "local") {
         assertNoCloudFlags(args);
+        if (platform === "android" && parseIosDeviceToken(avdName)) {
+            throw new Error("--avd ios-device:<udid> is an iPhone; use --platform ios or omit --platform.");
+        }
     }
     if (isCloudDeviceSource(deviceSource)) {
         const deviceName = hasNonEmptyString(args["device-name"]) ? args["device-name"].trim() : null;
@@ -393,3 +397,23 @@ export function resolveHeadlessTarget(args = {}) {
         listDevices: false,
     };
 }
+const APPLE_TEAM_ID_PATTERN = /^[A-Z0-9]{10}$/;
+export function normalizeIosTeamId(value) {
+    const teamId = readNonEmptyCliValue(value)?.toUpperCase() ?? null;
+    if (!teamId || !APPLE_TEAM_ID_PATTERN.test(teamId)) {
+        throw new Error("--ios-team must be a 10-character Apple team ID, for example ABCDE12345.");
+    }
+    return teamId;
+}
+export function resolveIosTeamId(args = {}, targetConfig = {}) {
+    if (args["ios-team"] == null) {
+        return null;
+    }
+    const teamId = normalizeIosTeamId(args["ios-team"]);
+    const isLocalMobile = targetConfig.target === "mobile" && targetConfig.deviceSource === "local";
+    const isOtherDevice = targetConfig.avdName != null && !parseIosDeviceToken(targetConfig.avdName);
+    if (!isLocalMobile || targetConfig.platform === "android" || isOtherDevice) {
+        throw new Error("--ios-team can only be used with a local iPhone (--avd ios-device:<udid> or ios-device:auto).");
+    }
+    return teamId;
+}

package/build/src/cli/ios-device-command.js

@@ -0,0 +1,121 @@
+import { runChecks as defaultRunChecks } from "../device/ios/real-device/readiness.js";
+import { IOS_DEVICE_PREFIX, parseIosDeviceToken } from "../device/ios/real-device/session.js";
+import { createStatusLine as defaultCreateStatusLine } from "./cloud-status-line.js";
+import { normalizeIosTeamId } from "./headless-target.js";
+const ALLOWED_OPTIONS = new Set(["_", "udid", "fix", "ios-team", "h", "help"]);
+const SYMBOLS = {
+    pass: { text: "✔", color: 32 },
+    fail: { text: "✖", color: 31 },
+    warn: { text: "!", color: 33 },
+    blocked: { text: "·", color: 90 },
+};
+export function iosDeviceCommandHelp() {
+    return [
+        "Usage: droid-cua ios-device check [options]",
+        "",
+        "Check that a real iPhone connected by USB is ready for droid-cua tests",
+        "",
+        "Options:",
+        "  --udid <udid>          Check this iPhone (default: the first iPhone connected by USB)",
+        "  --ios-team <TEAMID>    Apple team that signs the helper app (default: DROID_CUA_IOS_TEAM_ID, or your only paid team)",
+        "  --fix                  Set up signing and install the helper app (WebDriverAgent) when needed",
+        "  -h, --help             display help for command",
+        "",
+        "Examples:",
+        "  droid-cua ios-device check",
+        "  droid-cua ios-device check --udid 00008120-001C18501A81A01E --ios-team ABCDE12345 --fix",
+        "",
+        "Run tests on the iPhone with --avd ios-device:<udid> or --avd ios-device:auto.",
+    ].join("\n");
+}
+function parseIosDeviceCommandArgs(args, env) {
+    const unknownOption = Object.keys(args).find((key) => !ALLOWED_OPTIONS.has(key));
+    if (unknownOption)
+        throw new Error(`Unknown ios-device option --${unknownOption}.`);
+    if (args.help === true || args.h === true || args._.length === 1) {
+        return { help: iosDeviceCommandHelp() };
+    }
+    if (args._[1] !== "check" || args._.length !== 2) {
+        throw new Error(`Unknown ios-device command "${args._.slice(1).join(" ")}". Expected: droid-cua ios-device check`);
+    }
+    if (args.fix != null && typeof args.fix !== "boolean") {
+        throw new Error("--fix does not accept a value.");
+    }
+    let udid = null;
+    if (args.udid != null) {
+        const value = typeof args.udid === "string" ? args.udid.trim() : "";
+        if (!value)
+            throw new Error("--udid requires a value.");
+        udid = parseIosDeviceToken(value) ? parseIosDeviceToken(value).udid : value;
+    }
+    const teamValue = args["ios-team"] ?? env.DROID_CUA_IOS_TEAM_ID;
+    const teamId = teamValue == null || teamValue === "" ? null : normalizeIosTeamId(teamValue);
+    return { udid, teamId, fix: args.fix === true };
+}
+function paint(text, code, color) {
+    return color ? `\u001b[${code}m${text}\u001b[39m` : text;
+}
+function symbolFor(result, color) {
+    const symbol = SYMBOLS[result.blockedBy ? "blocked" : result.status];
+    return paint(symbol.text, symbol.color, color);
+}
+function guidanceLines(result, { fix }) {
+    if (result.blockedBy || result.status === "pass")
+        return [];
+    const lines = [];
+    if (result.details) {
+        lines.push(result.status === "fail" ? `Fix: ${result.details}` : result.details);
+    }
+    if (result.id === "apple_team" && result.status === "fail" && /paid Apple teams/.test(result.summary)) {
+        lines.push("Choose the team with --ios-team <TEAMID> (or set DROID_CUA_IOS_TEAM_ID).");
+    }
+    if (!fix && result.remediation?.some((step) => step.kind === "run_fix")) {
+        lines.push("Run droid-cua ios-device check --fix to do it now (a test run also does it automatically).");
+    }
+    return lines.map((line) => `    ${line}`);
+}
+export function formatReadinessReport({ ready, results, context }, { fix = false, color = false } = {}) {
+    const device = context?.device;
+    const heading = device
+        ? `iPhone readiness: ${device.name} (${device.model}, iOS ${device.iosVersion})`
+        : "iPhone readiness";
+    const lines = [heading, ""];
+    for (const result of results) {
+        lines.push(`${symbolFor(result, color)} ${result.title}: ${result.summary}`);
+        lines.push(...guidanceLines(result, { fix }));
+    }
+    lines.push("");
+    if (ready) {
+        lines.push(`Ready. Run tests on this iPhone with --avd ${IOS_DEVICE_PREFIX}${context.udid}`);
+    }
+    else {
+        lines.push("Not ready. Fix the first ✖ above, then run droid-cua ios-device check again.");
+    }
+    return lines;
+}
+function shouldUseColor() {
+    return Boolean(process.stdout.isTTY) && !Object.hasOwn(process.env, "NO_COLOR");
+}
+export async function runIosDeviceCommand({ args, env = process.env, output = console, runChecks = defaultRunChecks, createStatusLine = defaultCreateStatusLine, color = shouldUseColor(), } = {}) {
+    const command = parseIosDeviceCommandArgs(args ?? { _: ["ios-device"] }, env);
+    if (command.help) {
+        output.log(command.help);
+        return 0;
+    }
+    const statusLine = createStatusLine();
+    statusLine.start(command.fix ? "Checking and preparing the iPhone" : "Checking the iPhone");
+    let result;
+    try {
+        result = await runChecks({
+            udid: command.udid,
+            teamId: command.teamId,
+            autoFix: command.fix,
+            onProgress: (progress) => statusLine.update(progress.message),
+        });
+    }
+    finally {
+        statusLine.stop();
+    }
+    output.log(formatReadinessReport(result, { fix: command.fix, color }).join("\n"));
+    return result.ready ? 0 : 1;
+}

package/build/src/cli/ios-device-list.js

@@ -0,0 +1,32 @@
+import { listDevices } from "../device/ios/real-device/devicectl.js";
+import { IOS_DEVICE_PREFIX } from "../device/ios/real-device/session.js";
+export function iosDeviceStateHint(device) {
+    if (device.pairingState !== "paired")
+        return "not trusted";
+    if (device.developerModeStatus === "disabled")
+        return "Developer Mode off";
+    return null;
+}
+export function iosDeviceLabel(device) {
+    const details = [device.model, device.iosVersion ? `iOS ${device.iosVersion}` : null].filter(Boolean).join(" · ");
+    const hint = iosDeviceStateHint(device);
+    return `${device.name || device.udid} — ${details ? `${details} ` : ""}(USB)${hint ? ` — ${hint}` : ""}`;
+}
+export async function getConnectedIphones({ list = listDevices } = {}) {
+    let devices;
+    try {
+        devices = await list();
+    }
+    catch {
+        return [];
+    }
+    return devices
+        .filter((device) => device.transport === "wired" && device.udid)
+        .map((device) => ({
+        label: iosDeviceLabel(device),
+        value: `${IOS_DEVICE_PREFIX}${device.udid}`,
+        running: true,
+        realDevice: true,
+    }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+}

package/build/src/cli/network-capture-device.js

@@ -0,0 +1,21 @@
+import { parseIosDeviceToken } from "../device/ios/real-device/session.js";
+import { androidProxyInstruction, iphoneProxyInstruction, LAN_PROXY_HOST, macLanAddresses, NETWORK_PROXY_HOST } from "../network/local-proxy.js";
+function isAndroidEmulatorSerial(serial) {
+    return /^emulator-\d+$/.test(serial || "");
+}
+function physicalAndroidSerial(deviceName) {
+    const serial = typeof deviceName === "string" && deviceName.startsWith("adb:") ? deviceName.slice(4) : null;
+    return serial && !isAndroidEmulatorSerial(serial) ? serial : null;
+}
+export function cliNetworkProxyTarget(deviceName, addresses = macLanAddresses()) {
+    if (parseIosDeviceToken(deviceName))
+        return { host: LAN_PROXY_HOST, instruction: iphoneProxyInstruction(addresses) };
+    if (physicalAndroidSerial(deviceName))
+        return { host: LAN_PROXY_HOST, instruction: androidProxyInstruction(addresses) };
+    return { host: NETWORK_PROXY_HOST, instruction: null };
+}
+export function cliNetworkCaptureDeviceKind(platform, targetId) {
+    if (platform === "android")
+        return isAndroidEmulatorSerial(targetId) ? "android-emulator" : "android-device";
+    return parseIosDeviceToken(targetId) ? "iphone" : "ios-simulator";
+}

package/build/src/commands/help.js

@@ -19,6 +19,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  droid-cua --target web --instructions <file> [options]' });
     addOutput({ type: 'info', text: '  droid-cua --target desktop --instructions <file> [options]' });
     addOutput({ type: 'info', text: '  droid-cua --device-source lambdatest --instructions <file> [options]' });
+    addOutput({ type: 'info', text: '  droid-cua ios-device check [--udid <udid>] [--ios-team <TEAMID>] [--fix]' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Options:' });
     addOutput({ type: 'info', text: '  --target <kind>        Target kind: mobile (default), web, or desktop' });
@@ -27,8 +28,9 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --desktop-window <id>  Select a window within --desktop-app' });
     addOutput({ type: 'info', text: '  --desktop-input <mode> Physical pointer (default); accessibility requires --desktop-app' });
     addOutput({ type: 'info', text: '  --list-desktop-apps    List running desktop apps and windows' });
-    addOutput({ type: 'info', text: '  --avd <name>           Device name (Android device ID/serial or iOS Simulator)' });
+    addOutput({ type: 'info', text: '  --avd <name>           Device name (Android device ID/serial, iOS Simulator, or ios-device:<udid|auto>)' });
     addOutput({ type: 'info', text: '  --platform <platform>  Force platform: android or ios' });
+    addOutput({ type: 'info', text: '  --ios-team <TEAMID>    Apple team that signs the helper app on a USB iPhone' });
     addOutput({ type: 'info', text: '  --device-source <src>  Mobile source: local (default) or lambdatest' });
     addOutput({ type: 'info', text: '  --device-name <name>   LambdaTest real device name' });
     addOutput({ type: 'info', text: '  --os-version <version> LambdaTest OS version' });
@@ -54,8 +56,9 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --execution-prompt-file Headless execution prompt customization file' });
     addOutput({ type: 'info', text: '  --record               Record screenshots during execution' });
     addOutput({ type: 'info', text: '  --explain              Explain non-obvious decisions and completion evidence' });
+    addOutput({ type: 'info', text: '  --step-watchdog <off|on>  Check for failures after each instruction: off (default), on' });
     addOutput({ type: 'info', text: '  --report [path]        Save a self-contained HTML report locally' });
-    addOutput({ type: 'info', text: '  --network-proxy        Forward local mobile traffic through 127.0.0.1:8765 without capture' });
+    addOutput({ type: 'info', text: '  --network-proxy        Forward local mobile traffic through port 8765 without capture (all Mac addresses for iPhones and Android phones)' });
     addOutput({ type: 'info', text: '  --capture-network      Capture local mobile or browser test traffic to one JSONL log per test' });
     addOutput({ type: 'info', text: '  --no-cloud-report      Skip uploading the HTML report and screenshots to Loadmill' });
     addOutput({ type: 'info', text: '  --report-metadata <path> Write uploaded Loadmill report metadata as JSON' });
@@ -77,7 +80,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Platform Support:' });
     addOutput({ type: 'info', text: '  Android: Uses ADB to communicate with Android devices (physical or emulator)' });
-    addOutput({ type: 'info', text: '  iOS:     Uses Appium + XCUITest for iOS Simulator automation' });
+    addOutput({ type: 'info', text: '  iOS:     Uses Appium + XCUITest for iOS Simulators and iPhones connected by USB' });
     addOutput({ type: 'info', text: '  LambdaTest: Uses real cloud devices for headless mobile runs' });
     addOutput({ type: 'info', text: '  Web:     Uses Playwright with installed Google Chrome or Microsoft Edge for browser execution' });
     addOutput({ type: 'info', text: '  Desktop: Controls the primary display or a selected application on macOS and Windows' });
@@ -94,11 +97,20 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  3. XCUITest driver: appium driver install xcuitest' });
     addOutput({ type: 'info', text: '  Note: Appium server is auto-started when iOS platform is detected' });
     addOutput({ type: 'info', text: '' });
+    addOutput({ type: 'info', text: 'iPhone over USB (macOS only):' });
+    addOutput({ type: 'info', text: '  1. Xcode that supports the iPhone\'s iOS, opened once' });
+    addOutput({ type: 'info', text: '  2. Your Apple ID in Xcode, on your company\'s paid Apple Developer team' });
+    addOutput({ type: 'info', text: '     (Developer role with Access to Certificates, Identifiers & Profiles)' });
+    addOutput({ type: 'info', text: '  3. On the iPhone: tap Trust, turn on Developer Mode, set Auto-Lock to Never' });
+    addOutput({ type: 'info', text: '  4. droid-cua ios-device check --fix   (checks the iPhone and installs the helper app)' });
+    addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Examples:' });
     addOutput({ type: 'info', text: '  droid-cua --avd adb:emulator-5554        (Connected Android target by adb serial)' });
     addOutput({ type: 'info', text: '  droid-cua --avd avd:Pixel_8_API_35       (Launch Android AVD then connect)' });
     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 run tests/login.dcua --avd ios-device:auto   (iPhone connected by USB)' });
+    addOutput({ type: 'info', text: '  droid-cua run tests/login.dcua --avd ios-device:<udid> --ios-team ABCDE12345' });
     addOutput({ type: 'info', text: '  droid-cua run tests/login.dcua admin/refund.dcua --context app/context.md' });
     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"' });

package/build/src/commands/stop.js

@@ -23,6 +23,7 @@ export async function handleStop(args, session, context) {
         // Set flag to stop execution
         if (context.activeExecutionMode) {
             context.activeExecutionMode.shouldStop = true;
+            context.activeExecutionMode.requestStop?.();
         }
         return true; // Continue loop
     }

package/build/src/core/capture-sources.js

@@ -20,15 +20,19 @@ export const CAPTURE_SOURCES = Object.freeze({
     CALL_OUTPUT_EXPLICIT_ACTION: "call-output-explicit-action",
     INSTRUCTION_INPUT: "instruction-input",
     INSTRUCTION_INPUT_ASSERTION: "instruction-input-assertion",
+    STEP_WATCHDOG: "step-watchdog",
+    STEP_FAILURE: "step-failure",
     DESIGN_INPUT: "design-input",
 });
 const HIDDEN_DEBUG_MEDIA_KINDS = new Set([
     CAPTURE_SOURCES.PREVIEW_CLICK,
+    CAPTURE_SOURCES.STEP_WATCHDOG,
 ]);
 const CLICK_ANNOTATION_MEDIA_KINDS = new Set([
     CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION,
 ]);
 const SCREENSHOT_MEDIA_KINDS = new Set([
+    CAPTURE_SOURCES.STEP_FAILURE,
     CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION,
     CAPTURE_SOURCES.CALL_OUTPUT_EXPLICIT_ACTION,
     CAPTURE_SOURCES.INSTRUCTION_INPUT_ASSERTION,

package/build/src/core/droid-cua-run-usage.js

@@ -61,6 +61,7 @@ export function normalizeDroidCuaCostModel(model) {
     }
     return null;
 }
+/** @param {{ model?: string | null }} [options] */
 export function createDroidCuaRunUsageTotals({ model = null } = {}) {
     const normalizedModel = trimToNull(model);
     return {
@@ -110,7 +111,11 @@ export function addOpenAiResponseToDroidCuaRunUsage(totals, response) {
         totalTokens: totals.totalTokens + totalTokens,
     };
 }
-export function estimateDroidCuaRunCostUsd(totals) {
+/**
+ * @param {ReturnType<typeof createDroidCuaRunUsageTotals>} totals
+ * @param {{ inputTokens: number } | null} [stepWatchdogUsage]
+ */
+export function estimateDroidCuaRunCostUsd(totals, stepWatchdogUsage = null) {
     const costModel = totals.costModel ?? normalizeDroidCuaCostModel(totals.model);
     if (!costModel) {
         return null;
@@ -119,6 +124,8 @@ export function estimateDroidCuaRunCostUsd(totals) {
     if (!pricing) {
         return null;
     }
-    const cost = (totals.inputTokens / TOKENS_PER_MILLION) * pricing.inputPerMillionUsd;
+    // Decisions charges input tokens only; keep its usage separate from the actor model.
+    const cost = (totals.inputTokens / TOKENS_PER_MILLION) * pricing.inputPerMillionUsd
+        + (finiteNumber(stepWatchdogUsage?.inputTokens) / TOKENS_PER_MILLION) * 0.1;
     return Number(cost.toFixed(8));
 }

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

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const executionRunId = new AsyncLocalStorage();
+export function withExecutionRunId(runId, callback) {
+    return executionRunId.run(runId, callback);
+}
+export function getExecutionRunId() {
+    return executionRunId.getStore();
+}

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

@@ -206,6 +206,9 @@ function getInstructionScrollDirection(instruction) {
         return null;
     }
     const normalizedInstruction = instruction.toLowerCase();
+    if ((normalizedInstruction.match(/\bscroll/g) || []).length > 1) {
+        return null;
+    }
     if (normalizedInstruction.includes("scroll down")) {
         return 1;
     }