@loadmill/droid-cua 2.43.0 → 2.45.0

package/build/src/core/report/run-log-model.js

@@ -6,6 +6,37 @@ export function isNetworkCaptureStarted(line) {
     return (line.kind === "system" || line.kind === "info") &&
         /^Network capture started(?::|$)/.test(line.text || "");
 }
+// Run-level capture notices belong in the report header, not instruction actions.
+export function isNetworkCaptureNotice(line) {
+    return ["system", "info", "warning"].includes(line.kind) &&
+        /^(Network capture (?:started|incomplete|could not finish)|Captured \d+ (?:browser )?requests|No browser traffic observed|No traffic observed;|HTTPS reached the proxy)/i.test(line.text || "");
+}
+// Presentation shared by desktop and exported reports; original events remain intact.
+export function runNotice(line) {
+    const text = line.text || "";
+    if (!["warning", "info", "system"].includes(line.kind))
+        return null;
+    if (/^Network capture (?:incomplete|could not finish):/.test(text)) {
+        return { message: "Network capture couldn’t finish. Some traffic may be missing.", details: text.replace(/^Network capture (?:incomplete|could not finish):\s*/, ""), warning: true };
+    }
+    if (text.startsWith("HTTPS reached the proxy but no requests were decrypted")) {
+        return { message: "HTTPS traffic couldn’t be decrypted. Check certificate trust on the device.", details: text, warning: true };
+    }
+    if (line.kind === "warning" && text.startsWith("Warning: could not load app context")) {
+        return { message: "App context couldn’t be loaded. This run continued without it.", warning: true };
+    }
+    const reportFailure = /^Failed to (write JUnit report|report run to Loadmill):\s*(.*)$/s.exec(text);
+    if (line.kind === "warning" && reportFailure) {
+        return { message: reportFailure[1] === "write JUnit report" ? "Couldn’t save the run report." : "Couldn’t report this run to Loadmill.", details: reportFailure[2], warning: true };
+    }
+    if (line.kind === "warning" && text === "Failed to upload Droid run report. The local report is still available.") {
+        return { message: "Couldn’t upload the report to Loadmill. The local report is still available.", warning: true };
+    }
+    if (text === "Network Capture supports local mobile devices and Chrome/Edge browsers only; this run continues without capture.") {
+        return { message: "Network capture isn’t supported on this device. This run continued without it.", warning: false };
+    }
+    return null;
+}
 export function captureSourceOf(line) {
     const captureSource = line.payload?.captureSource;
     return typeof captureSource === "string" && captureSource.trim().length > 0 ? captureSource : null;
@@ -90,7 +121,7 @@ export function runSummaryData(event) {
     const success = Boolean(payload.success);
     const error = typeof payload.error === "string" && payload.error.trim().length > 0 ? payload.error : null;
     const stopped = !success && Boolean(error && error.toLowerCase().includes("stopped by user"));
-    const isAssertionFailure = Boolean(error && error.startsWith("Assertion failed:"));
+    const isAssertionFailure = payload.failureKind === "step_watchdog" || Boolean(error && error.startsWith("Assertion failed:"));
     return {
         status: success ? "passed" : stopped ? "stopped" : isAssertionFailure ? "failed" : "errored",
         durationMs: typeof payload.durationMs === "number" ? payload.durationMs : null,
@@ -255,3 +286,55 @@ export function networkCardData(lines) {
         answer: networkAnswerPresentation(answer),
     };
 }
+export function stepFailureData(event) {
+    if (event.eventType !== "error" && event.kind !== "error")
+        return null;
+    // Older saved runs identify this failure only by its message.
+    if (event.payload?.failureKind !== "step_watchdog" && event.text !== "Execution stopped: the last step could not be completed as instructed.")
+        return null;
+    const instruction = typeof event.payload?.instruction === "string" ? event.payload.instruction.trim() : "";
+    const details = typeof event.payload?.details === "string" ? event.payload.details.trim() : "";
+    return {
+        title: "Step Failed",
+        passed: false,
+        assertion: instruction || "Complete this step as instructed.",
+        details: stepCompletionData(details)?.reason || details || "This step could not be completed as instructed.",
+    };
+}
+export function isRepeatedStepFailureMessage(events, index) {
+    const event = events[index];
+    if (event.eventType !== "assistant_message" && event.kind !== "assistant")
+        return false;
+    for (let i = index + 1; i < events.length; i++) {
+        const next = events[i];
+        if (next.eventType === "instruction_started" || next.kind === "user" || next.eventType === "run_finished")
+            break;
+        if (stepFailureData(next) && next.payload?.details === event.text.trim())
+            return true;
+    }
+    return false;
+}
+// A run's final error often repeats an error or assertion already shown in the timeline.
+export function isRepeatedRunError(error, events) {
+    if (!error)
+        return false;
+    return events.some((event) => {
+        if (event.eventType !== "run_finished" && (event.eventType === "error" || event.kind === "error") && event.text === error)
+            return true;
+        const assertion = assertionData(event);
+        return assertion?.passed === false && (error === `Assertion failed: ${assertion.assertion}` ||
+            error === assertion.details);
+    });
+}
+// Counts from child completions, excluding the aggregate suite completion event.
+export function runSummaryCounts(events) {
+    const results = events.filter((event) => event.eventType === "run_finished" && typeof event.payload?.testsTotal !== "number").map(runSummaryData);
+    if (!results.length)
+        return null;
+    const counts = { instructionsTotal: 0, instructionsCompleted: 0, assertionsPassed: 0, assertionsFailed: 0, retries: 0 };
+    for (const result of results) {
+        for (const key of Object.keys(counts))
+            counts[key] += result[key] ?? 0;
+    }
+    return counts;
+}

package/build/src/core/report/run-report-model.js

@@ -29,6 +29,7 @@ const VALID_EVENTS = new Set([
     "tool_result",
     "screenshot_captured",
     "assertion_result",
+    "step_watchdog_result",
     "retry",
     "input_request",
     "run_finished",
@@ -112,10 +113,12 @@ export function makeFailureOrError({ kind, type, message, body } = {}) {
 }
 // The single run_finished payload contract — the shape the shared renderer's
 // runSummaryData() consumes. Producers map their own stat names to these canonical fields.
-export function buildRunFinishedPayload({ success, error, durationMs, instructionsTotal, instructionsCompleted, actionsTotal, assertionsPassed, assertionsFailed, retries, } = {}) {
+export function buildRunFinishedPayload({ success, error, failureKind, stepWatchdogMode, stepWatchdogUsage, durationMs, instructionsTotal, instructionsCompleted, actionsTotal, assertionsPassed, assertionsFailed, retries, } = {}) {
     return {
         success: Boolean(success),
         error: error ?? null,
+        ...(failureKind ? { failureKind } : {}),
+        ...(stepWatchdogMode ? { stepWatchdogMode, stepWatchdogUsage } : {}),
         durationMs,
         instructionsTotal,
         instructionsCompleted: instructionsCompleted ?? 0,

package/build/src/core/report/run-report-sections.js

@@ -1,3 +1,4 @@
+import { isNetworkCaptureStarted } from "./run-log-model.js";
 const CLOUD_PROVIDERS = [
     ["browserstack", "BrowserStack", "BrowserStack"],
     ["lambdatest", "LambdaTest", "LambdaTest"],
@@ -149,3 +150,12 @@ export function buildRunReportSections(logs) {
     }
     return sections;
 }
+// Stable order, independent of execution order; each activity appears only once.
+export function instructionActivities(lines) {
+    const sections = buildRunReportSections(lines);
+    return [
+        { type: "assertion", label: "Assertion", present: lines.some((line) => line.eventType === "assertion_result") },
+        { type: "loadmill", label: "Loadmill flow", present: sections.some((section) => section.kind === "loadmill") },
+        { type: "network", label: "Network capture / query", present: lines.some(isNetworkCaptureStarted) || sections.some((section) => section.kind === "network") },
+    ].filter((activity) => activity.present);
+}

package/build/src/core/runtime-config.js

@@ -1,4 +1,6 @@
+import { getExecutionRunId } from "./execution-context.js";
 import OpenAI from "openai";
+import { parseStepWatchdogMode } from "./step-watchdog.js";
 import { normalizeOptionalAutomationUrl } from "../browser/playwright/url.js";
 import { readContextOptimizationEnv, normalizeContextOptimizationEnabled, normalizeContextOptimizationThreshold, } from "./context-optimization.js";
 import { DEFAULT_OPENAI_CUA_MODEL, isLoadmillCuaModel, resolveCuaModel, resolveCuaModelProviderMode, } from "./cua-models.js";
@@ -123,7 +125,7 @@ export function resolveRuntimeCredentials({ openAiApiKey = null, loadmillApiToke
         loadmillBaseUrl: normalizeLoadmillSiteBaseUrl(loadmillBaseUrl),
     };
 }
-export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null, explainMode = true, stepDelayMs = undefined, contextOptimizationEnabled = undefined, contextOptimizationThreshold = undefined, promptCustomizations = null, appContext = null, } = {}) {
+export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null, explainMode = true, stepWatchdogMode = "off", stepDelayMs = undefined, contextOptimizationEnabled = undefined, contextOptimizationThreshold = undefined, promptCustomizations = null, appContext = null, } = {}) {
     const normalizedCuaModel = typeof cuaModel === "string" && LOADMILL_MODEL_ALIAS_SET.has(cuaModel)
         ? cuaModel
         : resolveCuaModel(cuaModel);
@@ -134,6 +136,7 @@ export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null,
             : normalizedProviderMode,
         cuaModel: normalizedCuaModel,
         explainMode: explainMode !== false,
+        stepWatchdogMode: parseStepWatchdogMode(stepWatchdogMode),
         stepDelayMs: normalizeStepDelayMs(Number(stepDelayMs)),
         contextOptimizationEnabled: normalizeContextOptimizationEnabled(contextOptimizationEnabled),
         contextOptimizationThreshold: normalizeContextOptimizationThreshold(contextOptimizationThreshold),
@@ -237,6 +240,13 @@ async function normalizeLoadmillGatewayErrorResponse(response) {
 }
 function createLoadmillGatewayFetch(baseFetch = fetch) {
     return async (input, init) => {
+        const runId = getExecutionRunId();
+        if (runId) {
+            const headers = new Headers(input instanceof Request ? input.headers : undefined);
+            new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
+            headers.set("X-Loadmill-Run-Id", runId);
+            init = { ...init, headers };
+        }
         const response = await baseFetch(input, init);
         if (response.ok) {
             return response;

package/build/src/core/step-watchdog.js

@@ -0,0 +1,61 @@
+import { buildStepWatchdogEvidence, STEP_WATCHDOG_INSTRUCTIONS } from "../prompts/step-watchdog.js";
+export const STEP_WATCHDOG_MODES = ["off", "on"];
+export const STEP_WATCHDOG_MODEL = "gpt-6-luna";
+// Provisional threshold; calibrate against labeled runs before enabling by default.
+export const STEP_WATCHDOG_THRESHOLD = 0.65;
+export const STEP_WATCHDOG_TIMEOUT_MS = 10000;
+/** @param {unknown} [value] */
+export function parseStepWatchdogMode(value = "off") {
+    if (!STEP_WATCHDOG_MODES.includes(value)) {
+        throw new Error("stepWatchdogMode must be off or on.");
+    }
+    return value;
+}
+export async function evaluateStepWatchdog({ client, screenshotBase64, signal, onResponse, secretsByKey = {}, ...evidence }) {
+    if (!screenshotBase64)
+        throw new Error("Step Watchdog requires a current screenshot.");
+    let text = buildStepWatchdogEvidence(evidence);
+    for (const value of Object.values(secretsByKey).filter((value) => typeof value === "string" && value).sort((a, b) => b.length - a.length)) {
+        text = text.replaceAll(JSON.stringify(value).slice(1, -1), "[REDACTED]");
+    }
+    let response;
+    try {
+        response = await client.post("/decisions", {
+            body: {
+                model: STEP_WATCHDOG_MODEL,
+                input: [{ role: "user", content: [
+                            { type: "input_text", text },
+                            { type: "input_image", image_url: `data:image/png;base64,${screenshotBase64}` },
+                        ] }],
+                questions: [{ type: "predicate", name: "should_stop", instructions: STEP_WATCHDOG_INSTRUCTIONS }],
+            },
+            timeout: STEP_WATCHDOG_TIMEOUT_MS,
+            maxRetries: 0,
+            signal,
+        });
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        if (error?.status === 404 || error?.status === 405) {
+            throw new Error("The selected AI provider does not support the Decisions endpoint. Loadmill runs require gateway support for /decisions.");
+        }
+        if (error?.name === "APIConnectionTimeoutError")
+            throw new Error("Step Watchdog timed out after 10 seconds.");
+        throw new Error(`Step Watchdog request failed${Number.isInteger(error?.status) ? ` (HTTP ${error.status})` : ""}. Check the selected AI provider's connection, credentials, and Decisions support.`);
+    }
+    onResponse?.(response);
+    const answers = Array.isArray(response?.answers) ? response.answers : [];
+    const answer = answers.find((item) => item?.name === "should_stop");
+    if (answer?.type === "refusal")
+        throw new Error("The Step Watchdog evaluator declined to answer.");
+    if (answers.length !== 1 || answer?.type !== "predicate" || !Number.isFinite(answer.probability) || answer.probability < 0 || answer.probability > 1) {
+        throw new Error("The Step Watchdog evaluator returned an invalid decision.");
+    }
+    return {
+        probability: answer.probability,
+        shouldStop: answer.probability >= STEP_WATCHDOG_THRESHOLD,
+        model: response.model || STEP_WATCHDOG_MODEL,
+        usage: response.usage,
+    };
+}

package/build/src/desktop-shared/ios-real-device.js

@@ -0,0 +1,82 @@
+import { iosDeviceLabel, iosDeviceStateHint } from "../cli/ios-device-list.js";
+import { describeFailure } from "../device/ios/real-device/readiness.js";
+import { IOS_DEVICE_PREFIX, parseIosDeviceToken } from "../device/ios/real-device/session.js";
+export const IPHONE_STATUS_EVENT = "ios_device.status";
+const TEAM_ID_PATTERN = /^[A-Z0-9]{10}$/;
+const CAUSE_REMEDIATION = {
+    "command-line-tools-selected": [{ kind: "run_fix", label: "Set Xcode Developer Path", fixId: "ios_set_xcode_developer_path" }],
+    "xcode-license": [{ kind: "run_fix", label: "Accept Xcode License", fixId: "ios_accept_xcode_license" }],
+    "ios-platform-missing": [{ kind: "run_fix", label: "Download iOS Platform", fixId: "ios_download_ios_platform" }],
+};
+const XCODE_CHECK_IDS = ["xcode_devicectl", "ios_platform"];
+export function iphoneDeviceOptions(devices) {
+    return devices
+        .filter((device) => device.transport === "wired" && device.udid)
+        .map((device) => {
+        const hint = iosDeviceStateHint(device);
+        return {
+            name: `${IOS_DEVICE_PREFIX}${device.udid}`,
+            label: iosDeviceLabel(device),
+            platform: "ios",
+            running: true,
+            iosKind: "device",
+            iosUdid: device.udid,
+            ...(hint ? { iosStateHint: hint } : {}),
+        };
+    })
+        .sort((a, b) => a.label.localeCompare(b.label));
+}
+export function isIphoneDeviceName(deviceName) {
+    return parseIosDeviceToken(deviceName) !== null;
+}
+export function toSetupCheckResult(result) {
+    const remediation = result.remediation ?? CAUSE_REMEDIATION[result.cause];
+    return {
+        id: result.id,
+        status: result.status,
+        title: result.title,
+        summary: result.summary,
+        ...(result.details ? { details: result.details } : {}),
+        blocking: result.blocking,
+        checkedAt: result.checkedAt,
+        ...(remediation ? { remediation } : {}),
+        ...(result.kind ? { kind: result.kind } : {}),
+        ...(result.blockedBy ? { blockedBy: result.blockedBy } : {}),
+    };
+}
+export function orderIphoneSetupChecks(deviceResults, toolResults) {
+    const isXcode = (result) => XCODE_CHECK_IDS.includes(result.id);
+    return [...deviceResults.filter(isXcode), ...toolResults, ...deviceResults.filter((result) => !isXcode(result))];
+}
+export function iphoneFixResult(checkId, results) {
+    const result = results.find((entry) => entry.id === checkId);
+    if (result?.status === "pass") {
+        return { ok: true, summary: "Fix completed successfully.", details: result.summary };
+    }
+    return { ok: false, summary: "Fix failed.", details: result ? describeFailure(result) : `Unknown iPhone check: ${checkId}.` };
+}
+export function normalizeTeamId(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim().toUpperCase();
+    return TEAM_ID_PATTERN.test(trimmed) ? trimmed : null;
+}
+export function iphoneTeamOptions(teams) {
+    return teams.map((team) => ({
+        teamId: team.teamId,
+        label: team.teamName ? `${team.teamName} (${team.teamId})` : team.teamId,
+    }));
+}
+export function iphoneConnectOptions(deviceName, teamId) {
+    if (!isIphoneDeviceName(deviceName))
+        return {};
+    const normalized = normalizeTeamId(teamId);
+    return normalized ? { teamId: normalized } : {};
+}
+export function iphoneStatusLogEvent({ status, message }) {
+    return {
+        kind: status === "unlocked" ? "success" : "warning",
+        text: message,
+        payload: { event: IPHONE_STATUS_EVENT, status },
+    };
+}

package/build/src/device/factory.js

@@ -9,6 +9,7 @@ import * as cloudConnection from "./cloud/connection.js";
 import * as cloudActions from "./cloud/actions.js";
 import * as iosConnection from "./ios/connection.js";
 import * as iosActions from "./ios/actions.js";
+import { parseIosDeviceToken } from "./ios/real-device/session.js";
 // Current platform state
 let currentPlatform = null;
 let currentSource = "local";
@@ -25,6 +26,9 @@ export function detectPlatform(deviceName) {
     if (process.env.DROID_CUA_PLATFORM === "android") {
         return "android";
     }
+    if (parseIosDeviceToken(deviceName)) {
+        return "ios";
+    }
     // Auto-detect from device name
     if (deviceName) {
         const lower = deviceName.toLowerCase();

package/build/src/device/ios/actions.js

@@ -7,25 +7,55 @@ import * as appium from "./appium-client.js";
 import { buildActionEventMeta } from "../action-event-meta.js";
 import { buildIosAppSwitcherGesture, buildMobileKeypressPayload, getIosTransport, normalizeMobileKeypress } from "../mobile-keypress.js";
 import { actionForErrorLog, buildActionErrorOutput, buildDebugTextField, buildSensitiveDebugFields, buildTypeActionPayload, buildTypeActionText, isSensitiveAction, } from "../sensitive-action.js";
-import { getActiveSession, getDevicePixelRatio } from "./connection.js";
+import { getActiveSession, getDevicePixelRatio, recoverRealDevice } from "./connection.js";
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug, truncateForDebug } from "../../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../../utils/step-delay.js";
 import { resolveScrollGesture } from "../scroll-gesture.js";
-import { closeAppiumKeyboardWithTap } from "../keyboard.js";
+import { KEYBOARD_CLOSE_RESULTS, closeAppiumKeyboardWithTap } from "../keyboard.js";
+export function realDeviceScreenBounds(session) {
+    const size = session?.realDevice ? session.windowSize : null;
+    if (!Number.isFinite(size?.width) || !Number.isFinite(size?.height)) {
+        return {};
+    }
+    return { minX: 0, maxX: Math.round(size.width) - 1, minY: 0, maxY: Math.round(size.height) - 1 };
+}
+function clampToBounds(value, min, max) {
+    return Number.isFinite(min) && Number.isFinite(max) ? Math.min(Math.max(value, min), max) : value;
+}
 export async function closeKeyboard(_deviceId, { dismissalPoint = null, scale = 1 } = {}) {
     const session = getActiveSession();
     if (!session) {
         throw new Error("No active iOS session");
     }
     const dpr = getDevicePixelRatio();
-    const tap = dismissalPoint
-        ? () => appium.tap(session.sessionId, Math.round((dismissalPoint.x / scale) / dpr), Math.round((dismissalPoint.y / scale) / dpr))
+    const tapPoint = dismissalPoint
+        ? { x: Math.round((dismissalPoint.x / scale) / dpr), y: Math.round((dismissalPoint.y / scale) / dpr) }
         : null;
-    return closeAppiumKeyboardWithTap({
-        isKeyboardShown: () => appium.isKeyboardShown(session.sessionId),
-        tap,
+    const keyboardShownReadings = [];
+    const result = await closeAppiumKeyboardWithTap({
+        isKeyboardShown: async () => {
+            const shown = await appium.isKeyboardShown(session.sessionId);
+            keyboardShownReadings.push(shown);
+            return shown;
+        },
+        tap: tapPoint ? () => appium.tap(session.sessionId, tapPoint.x, tapPoint.y) : null,
     });
+    if (result.status === KEYBOARD_CLOSE_RESULTS.FAILED) {
+        const details = {
+            platform: "ios",
+            realDevice: session.realDevice === true,
+            dismissalPoint,
+            tapPoint,
+            unit: "points",
+            keyboardShownBefore: keyboardShownReadings[0] ?? null,
+            keyboardShownAfter: keyboardShownReadings[1] ?? null,
+            error: result.error ?? null,
+        };
+        logger.debug("iOS keyboard close failed", details);
+        emitDesktopDebug("device.keyboard.close_failed", "device", {}, details);
+    }
+    return result;
 }
 /**
  * Handle an action from the CUA model
@@ -100,7 +130,8 @@ export async function handleModelAction(simulatorId, action, scale = 1.0, contex
                     scale,
                     dpr,
                     fallbackStartX: 197,
-                    fallbackStartY: 426
+                    fallbackStartY: 426,
+                    ...realDeviceScreenBounds(session)
                 });
                 addOutput({
                     type: "action",
@@ -117,10 +148,11 @@ export async function handleModelAction(simulatorId, action, scale = 1.0, contex
                     const start = path[0];
                     const end = path[path.length - 1];
                     // Convert to pixels then to logical points
-                    const startX = Math.round((start.x / scale) / dpr);
-                    const startY = Math.round((start.y / scale) / dpr);
-                    const endX = Math.round((end.x / scale) / dpr);
-                    const endY = Math.round((end.y / scale) / dpr);
+                    const { minX, maxX, minY, maxY } = realDeviceScreenBounds(session);
+                    const startX = clampToBounds(Math.round((start.x / scale) / dpr), minX, maxX);
+                    const startY = clampToBounds(Math.round((start.y / scale) / dpr), minY, maxY);
+                    const endX = clampToBounds(Math.round((end.x / scale) / dpr), minX, maxX);
+                    const endY = clampToBounds(Math.round((end.y / scale) / dpr), minY, maxY);
                     addOutput({
                         type: "action",
                         text: `Dragging from (${startX}, ${startY}) to (${endX}, ${endY}) points`,
@@ -213,6 +245,10 @@ export async function handleModelAction(simulatorId, action, scale = 1.0, contex
             }
         });
         addOutput({ type: "info", text: "Full error details have been logged to the debug log." });
+        if (session.realDevice) {
+            await recoverRealDevice(error, { log: (text) => addOutput({ type: "info", text }) })
+                .catch((recoveryError) => addOutput({ type: "error", text: recoveryError.message }));
+        }
         return { success: false, error: outputError.message };
     }
 }

package/build/src/device/ios/appium-server.js

@@ -5,30 +5,19 @@
  * Auto-starts if not running, cleans up on process exit.
  */
 import { spawn } from "child_process";
-import { existsSync, readdirSync } from "fs";
+import { existsSync } from "fs";
+import os from "os";
 import path from "path";
-import { COMMON_NODE_BIN_DIRS, makeNodeCliCommandEnv } from "./node-cli-env.js";
+import { COMMON_NODE_BIN_DIRS, listNvmNodeBinDirs, makeNodeCliCommandEnv } from "./node-cli-env.js";
 let appiumProcess = null;
 let cleanupRegistered = false;
 function getAppiumBaseUrl() {
     return process.env.APPIUM_URL || "http://localhost:4723";
 }
-function collectNvmAppiumCandidates() {
-    const home = process.env.HOME;
-    if (!home)
-        return [];
-    const nvmNodeVersionsDir = path.join(home, ".nvm", "versions", "node");
-    if (!existsSync(nvmNodeVersionsDir))
-        return [];
-    try {
-        return readdirSync(nvmNodeVersionsDir)
-            .map((versionDir) => path.join(nvmNodeVersionsDir, versionDir, "bin", "appium"))
-            .filter((candidate) => existsSync(candidate))
-            .reverse();
-    }
-    catch {
-        return [];
-    }
+export function collectNvmAppiumCandidates(home = os.homedir()) {
+    return listNvmNodeBinDirs(home)
+        .map((binDir) => path.join(binDir, "appium"))
+        .filter((candidate) => existsSync(candidate));
 }
 export function resolveAppiumCommand() {
     const explicit = process.env.DROID_CUA_APPIUM_PATH?.trim() || process.env.APPIUM_PATH?.trim();

package/build/src/device/ios/connection.js

@@ -10,6 +10,7 @@ import { startAppium, setupAppiumCleanup } from "./appium-server.js";
 import * as appium from "./appium-client.js";
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug } from "../../utils/desktop-debug.js";
+import { IOS_DEVICE_PREFIX, createRealDeviceSession, parseIosDeviceToken, recoverIfLocked, recoverRealDeviceSession, startRealDeviceSession, } from "./real-device/session.js";
 const execAsync = promisify(exec);
 // Active session state
 let activeSession = null;
@@ -157,6 +158,13 @@ export async function connectToDevice(simulatorName, options = {}) {
     setupAppiumCleanup();
     // Start Appium if not running
     await startAppium({ log });
+    const realDevice = parseIosDeviceToken(simulatorName);
+    if (realDevice) {
+        return connectToRealDevice(realDevice.udid, {
+            log,
+            teamId: resolveRealDeviceTeamId(realDevice.udid, options.teamId),
+        });
+    }
     // If no simulator specified, auto-detect
     if (!simulatorName) {
         const found = await findAnySimulator();
@@ -194,6 +202,22 @@ export async function connectToDevice(simulatorName, options = {}) {
     });
     return simulator.udid;
 }
+export function resolveRealDeviceTeamId(udid, explicitTeamId = null) {
+    const previous = activeSession?.realDevice && activeSession.udid === udid ? activeSession.teamId : null;
+    return explicitTeamId || previous || process.env.DROID_CUA_IOS_TEAM_ID || null;
+}
+async function connectToRealDevice(udid, { log, teamId }) {
+    activeSession = await startRealDeviceSession({ udid, teamId, log });
+    log(`Connected to iPhone "${activeSession.deviceName}" (${activeSession.udid})`);
+    emitDesktopDebug("device.connect", "device", {}, {
+        platform: "ios",
+        stage: "success",
+        realDevice: true,
+        deviceName: activeSession.deviceName,
+        udid: activeSession.udid
+    });
+    return `${IOS_DEVICE_PREFIX}${activeSession.udid}`;
+}
 /**
  * Get device info (screen dimensions and scale)
  * @param {string} simulatorId - The UDID returned from connectToDevice
@@ -216,15 +240,18 @@ export async function getDeviceInfo(simulatorId, options = {}) {
     log(`Device pixel ratio: ${devicePixelRatio}x (${pixelWidth}x${pixelHeight} pixels, ${windowSize.width}x${windowSize.height} points)`);
     // Store the pixel ratio for coordinate conversion
     activeSession.devicePixelRatio = devicePixelRatio;
+    activeSession.windowSize = windowSize;
     // Use pixel dimensions as the "real" resolution (like Android does)
     const targetWidth = 400;
     const scale = pixelWidth > targetWidth ? targetWidth / pixelWidth : 1.0;
     const scaledWidth = Math.round(pixelWidth * scale);
     const scaledHeight = Math.round(pixelHeight * scale);
+    const name = activeSession.realDevice ? activeSession.deviceName : activeSession.simulatorName;
+    const model = activeSession.realDevice ? activeSession.model : activeSession.simulatorName;
     return {
         platform: "ios",
-        device_name: activeSession?.simulatorName || simulatorId,
-        model: activeSession?.simulatorName || simulatorId,
+        device_name: name || simulatorId,
+        model: model || simulatorId,
         device_width: pixelWidth,
         device_height: pixelHeight,
         scaled_width: scaledWidth,
@@ -238,9 +265,24 @@ export async function getDeviceInfo(simulatorId, options = {}) {
  * @param {object} deviceInfo
  * @returns {Promise<string>}
  */
-export async function getScreenshotAsBase64(simulatorId, deviceInfo) {
+export async function getScreenshotAsBase64(simulatorId, deviceInfo, { deps } = {}) {
     await ensureSessionAlive();
-    const rawBase64 = await appium.getScreenshot(activeSession.sessionId);
+    if (activeSession.realDevice) {
+        const sessionId = await recoverIfLocked(activeSession, { deps });
+        if (sessionId) {
+            activeSession.sessionId = sessionId;
+        }
+    }
+    let rawBase64;
+    try {
+        rawBase64 = await appium.getScreenshot(activeSession.sessionId);
+    }
+    catch (error) {
+        if (!await recoverRealDevice(error)) {
+            throw error;
+        }
+        rawBase64 = await appium.getScreenshot(activeSession.sessionId);
+    }
     let buffer = Buffer.from(rawBase64, "base64");
     logger.debug(`iOS screenshot captured: ${buffer.length} bytes before scaling`);
     if (deviceInfo.scale < 1.0) {
@@ -279,14 +321,20 @@ async function ensureSessionAlive() {
             reason: "appium session no longer active"
         });
         console.log("Session died, recreating...");
-        const session = await appium.createSession({
-            platformName: "iOS",
-            "appium:automationName": "XCUITest",
-            "appium:deviceName": activeSession.simulatorName,
-            "appium:udid": activeSession.udid,
-            "appium:noReset": true,
-            "appium:shouldTerminateApp": false,
-        });
+        const session = activeSession.realDevice
+            ? await createRealDeviceSession({
+                udid: activeSession.udid,
+                bundleIdBase: activeSession.bundleIdBase,
+                deviceName: activeSession.deviceName,
+            })
+            : await appium.createSession({
+                platformName: "iOS",
+                "appium:automationName": "XCUITest",
+                "appium:deviceName": activeSession.simulatorName,
+                "appium:udid": activeSession.udid,
+                "appium:noReset": true,
+                "appium:shouldTerminateApp": false,
+            });
         activeSession.sessionId = session.sessionId;
         emitDesktopDebug("reconnect.attempt", "device", {}, {
             platform: "ios",
@@ -295,6 +343,17 @@ async function ensureSessionAlive() {
         });
     }
 }
+export async function recoverRealDevice(error, { log = console.log, deps } = {}) {
+    if (!activeSession?.realDevice) {
+        return false;
+    }
+    const sessionId = await recoverRealDeviceSession(activeSession, error, { log, deps });
+    if (!sessionId) {
+        return false;
+    }
+    activeSession.sessionId = sessionId;
+    return true;
+}
 /**
  * Get the active session (for use by actions module)
  * @returns {object|null}