@loadmill/droid-cua 2.22.0 → 2.23.0

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

@@ -98,6 +98,48 @@ export function runSummaryData(event) {
         error,
     };
 }
+export function stepCompletionData(eventOrText) {
+    const text = typeof eventOrText === "string"
+        ? eventOrText
+        : typeof eventOrText?.text === "string"
+            ? eventOrText.text
+            : null;
+    if (!text)
+        return null;
+    const normalized = text.replace(/\r/g, "").trim();
+    const prefix = "Step complete:";
+    if (!normalized.startsWith(prefix))
+        return null;
+    const rest = normalized.slice(prefix.length);
+    const reasonLabel = /\sReason:\s*/.exec(rest);
+    if (!reasonLabel)
+        return null;
+    const instruction = rest.slice(0, reasonLabel.index).trim();
+    const reasonStart = reasonLabel.index + reasonLabel[0].length;
+    const afterReason = rest.slice(reasonStart);
+    const visibleStateLabel = /\sVisible state:\s*/.exec(afterReason);
+    if (!visibleStateLabel)
+        return null;
+    const reason = afterReason.slice(0, visibleStateLabel.index).trim();
+    const visibleState = afterReason.slice(visibleStateLabel.index + visibleStateLabel[0].length).trim();
+    if (!instruction || !reason || !visibleState)
+        return null;
+    return { instruction, reason, visibleState };
+}
+export function stepCompletionReasonTooltip(stepCompletion, maxLength = 140) {
+    if (!stepCompletion?.reason)
+        return null;
+    const firstSentence = stepCompletion.reason.match(/^.*?[.!?](?:\s|$)/)?.[0]?.trim();
+    const text = (firstSentence || stepCompletion.reason).replace(/\s+/g, " ").trim();
+    if (!text)
+        return null;
+    if (text.length <= maxLength)
+        return `Reason: ${text}`;
+    const truncated = text.slice(0, Math.max(0, maxLength - 1)).trimEnd();
+    const wordBoundary = truncated.lastIndexOf(" ");
+    const cleanTruncated = wordBoundary > maxLength * 0.6 ? truncated.slice(0, wordBoundary).trimEnd() : truncated;
+    return `Reason: ${cleanTruncated}…`;
+}
 export function formatDuration(ms) {
     if (ms === null || ms === undefined)
         return "n/a";

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

@@ -2,13 +2,12 @@ import OpenAI from "openai";
 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";
-import { DEFAULT_FARA_BASE_URL, DEFAULT_FARA_MODEL, resolveCuaBackend, } from "./cua-backends.js";
 import { normalizeStepDelayMs } from "../utils/step-delay.js";
 export const LOADMILL_MODEL_ALIASES = Object.freeze({
     DEFAULT_AGENT_MODEL: "default-agent-model",
     FAST: "fast",
     SMART: "smart",
-    COMPUTER_USE: "computer-use",
+    BEACON: "beacon",
 });
 const LOADMILL_MODEL_ALIAS_SET = new Set(Object.values(LOADMILL_MODEL_ALIASES));
 export const LLM_PROVIDER_MODES = Object.freeze(["loadmill", "openai"]);
@@ -89,19 +88,19 @@ export function inferLlmProviderModeFromCredentials(credentials = {}) {
     }
     return DEFAULT_LLM_PROVIDER_MODE;
 }
-export function resolveGatewayCuaModelAlias({ cuaBackend, cuaModel } = {}) {
-    if (resolveCuaBackend(cuaBackend) === "fara") {
-        return LOADMILL_MODEL_ALIASES.COMPUTER_USE;
-    }
+export function resolveGatewayCuaModelAlias({ cuaModel } = {}) {
     const normalizedCuaModel = resolveCuaModel(cuaModel);
+    if (normalizedCuaModel === "loadmill-beacon") {
+        return LOADMILL_MODEL_ALIASES.BEACON;
+    }
     return normalizedCuaModel === "gpt-5.4-mini"
         ? LOADMILL_MODEL_ALIASES.FAST
         : LOADMILL_MODEL_ALIASES.SMART;
 }
-export function resolveEffectiveCuaModel({ llmProviderMode = null, cuaBackend = null, cuaModel = null, } = {}) {
+export function resolveEffectiveCuaModel({ llmProviderMode = null, cuaModel = null, } = {}) {
     const providerMode = resolveLlmProviderMode(llmProviderMode);
     if (providerMode === "loadmill") {
-        return resolveGatewayCuaModelAlias({ cuaBackend, cuaModel });
+        return resolveGatewayCuaModelAlias({ cuaModel });
     }
     return resolveCuaModelProviderMode(cuaModel) === "openai"
         ? resolveCuaModel(cuaModel)
@@ -115,17 +114,14 @@ export function resolveEffectiveHelperModel({ llmProviderMode = null, cuaModel =
         ? resolveCuaModel(cuaModel)
         : DEFAULT_OPENAI_CUA_MODEL;
 }
-export function resolveRuntimeCredentials({ openAiApiKey = null, faraApiKey = null, faraBaseUrl = null, faraModel = null, loadmillApiToken = null, loadmillBaseUrl = null, } = {}) {
+export function resolveRuntimeCredentials({ openAiApiKey = null, loadmillApiToken = null, loadmillBaseUrl = null, } = {}) {
     return {
         openAiApiKey: trimNullableString(openAiApiKey),
-        faraApiKey: trimNullableString(faraApiKey),
-        faraBaseUrl: trimNullableString(faraBaseUrl) || DEFAULT_FARA_BASE_URL,
-        faraModel: trimNullableString(faraModel) || DEFAULT_FARA_MODEL,
         loadmillApiToken: trimNullableString(loadmillApiToken),
         loadmillBaseUrl: normalizeLoadmillSiteBaseUrl(loadmillBaseUrl),
     };
 }
-export function resolveRuntimeConfig({ llmProviderMode = null, cuaBackend = null, cuaModel = null, stepDelayMs = undefined, contextOptimizationEnabled = undefined, contextOptimizationThreshold = undefined, promptCustomizations = null, appContext = null, } = {}) {
+export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null, 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,7 +130,6 @@ export function resolveRuntimeConfig({ llmProviderMode = null, cuaBackend = null
         llmProviderMode: llmProviderMode == null && isLoadmillCuaModel(normalizedCuaModel)
             ? "loadmill"
             : normalizedProviderMode,
-        cuaBackend: resolveCuaBackend(cuaBackend),
         cuaModel: normalizedCuaModel,
         stepDelayMs: normalizeStepDelayMs(Number(stepDelayMs)),
         contextOptimizationEnabled: normalizeContextOptimizationEnabled(contextOptimizationEnabled),
@@ -161,11 +156,6 @@ export function resolveRuntimeConfigFromEnv(env = process.env, overrides = {}) {
     const contextOptimization = readContextOptimizationEnv(env);
     return resolveRuntimeConfig({
         llmProviderMode: env.DROID_CUA_LLM_PROVIDER,
-        // Only the explicit backend flag should influence CUA model routing.
-        // Legacy screenshot-provider env vars must not silently remap Loadmill
-        // model aliases like "smart" to backend-specific aliases like
-        // "computer-use".
-        cuaBackend: env.DROID_CUA_BACKEND,
         cuaModel: env.OPENAI_CUA_MODEL,
         stepDelayMs: env.DROID_CUA_STEP_DELAY_MS,
         contextOptimizationEnabled: contextOptimization.enabled,
@@ -176,9 +166,6 @@ export function resolveRuntimeConfigFromEnv(env = process.env, overrides = {}) {
 export function resolveRuntimeCredentialsFromEnv(env = process.env, overrides = {}) {
     return resolveRuntimeCredentials({
         openAiApiKey: env.OPENAI_API_KEY,
-        faraApiKey: env.DROID_CUA_FARA_API_KEY,
-        faraBaseUrl: env.DROID_CUA_FARA_BASE_URL,
-        faraModel: env.DROID_CUA_FARA_MODEL,
         loadmillApiToken: env.LOADMILL_API_TOKEN,
         loadmillBaseUrl: env.LOADMILL_BASE_URL,
         ...overrides,
@@ -278,19 +265,27 @@ export function createLlmClient({ loadmillApiToken, loadmillBaseUrl, clientName
         },
     });
 }
-export function createFaraClient({ apiKey, baseUrl }) {
-    return new OpenAI({
-        apiKey: trimNullableString(apiKey) || "",
-        baseURL: trimNullableString(baseUrl) || DEFAULT_FARA_BASE_URL,
-    });
-}
-export function createResolvedLlmClient({ llmProviderMode = null, credentials = null, clientName = "desktop", maxRetries = 1, } = {}) {
+export function assertRuntimeCredentialsForProvider({ llmProviderMode = null, credentials = null, } = {}) {
     const resolvedCredentials = resolveRuntimeCredentials(credentials);
     const resolvedProviderMode = resolveLlmProviderMode(llmProviderMode);
     if (resolvedProviderMode === "loadmill") {
         if (!hasLoadmillLlmAccess(resolvedCredentials)) {
             throw new Error(missingCredentialErrorMessage(resolvedProviderMode));
         }
+        return;
+    }
+    if (!hasOpenAiLlmAccess(resolvedCredentials)) {
+        throw new Error(missingCredentialErrorMessage(resolvedProviderMode));
+    }
+}
+export function createResolvedLlmClient({ llmProviderMode = null, credentials = null, clientName = "desktop", maxRetries = 1, } = {}) {
+    const resolvedCredentials = resolveRuntimeCredentials(credentials);
+    const resolvedProviderMode = resolveLlmProviderMode(llmProviderMode);
+    assertRuntimeCredentialsForProvider({
+        llmProviderMode: resolvedProviderMode,
+        credentials: resolvedCredentials,
+    });
+    if (resolvedProviderMode === "loadmill") {
         return createLlmClient({
             loadmillApiToken: resolvedCredentials.loadmillApiToken,
             loadmillBaseUrl: resolvedCredentials.loadmillBaseUrl,
@@ -298,9 +293,6 @@ export function createResolvedLlmClient({ llmProviderMode = null, credentials =
             maxRetries,
         });
     }
-    if (!hasOpenAiLlmAccess(resolvedCredentials)) {
-        throw new Error(missingCredentialErrorMessage(resolvedProviderMode));
-    }
     return createOpenAiClient(resolvedCredentials.openAiApiKey);
 }
 export function createRunContext({ config, credentials }) {
@@ -312,7 +304,6 @@ export function createRunContext({ config, credentials }) {
         llmProviderMode: resolvedProviderMode,
         cuaModel: resolveEffectiveCuaModel({
             llmProviderMode: resolvedProviderMode,
-            cuaBackend: resolvedConfig.cuaBackend,
             cuaModel: resolvedConfig.cuaModel,
         }),
     };
@@ -328,12 +319,6 @@ export function createRunContext({ config, credentials }) {
                 credentials: resolvedCredentials,
                 clientName: "desktop",
             }),
-            fara: resolvedConfig.cuaBackend === "fara"
-                ? createFaraClient({
-                    apiKey: resolvedCredentials.faraApiKey,
-                    baseUrl: resolvedCredentials.faraBaseUrl,
-                })
-                : null,
         },
     };
 }

package/build/src/core/session.js

@@ -56,6 +56,12 @@ export class Session {
     getTranscriptText() {
         return this.transcript.join("\n");
     }
+    /**
+     * Clear the per-instruction transcript.
+     */
+    clearTranscript() {
+        this.transcript = [];
+    }
     /**
      * Update the previous response ID for chaining
      */

package/build/src/core/tool-handlers/loadmill.js

@@ -29,6 +29,9 @@ export async function handleLoadmillToolCall({ engine, callId, argumentsText, co
     return {
         kind: "close_turn",
         outputItem: buildTextToolOutputItem(callId, "Loadmill command completed successfully."),
+        nextTurnConfig: {
+            attachFreshScreenshotOnContinuation: true,
+        },
         summaryUpdates: result.runtimeParameterContext?.note
             ? { preserveSessionMessages: true }
             : undefined,

package/build/src/core/tool-handlers/test-design-complete.js

@@ -88,6 +88,7 @@ export async function handleTestDesignCompleteToolCall({ engine, callId, argumen
                 testDesignComplete: false,
             },
             includeComputerToolOverride: false,
+            continuationMode: "fresh",
         },
     };
 }

package/build/src/core/tool-handlers/type-sensitive-text.js

@@ -58,5 +58,6 @@ export async function handleTypeSensitiveTextToolCall({ engine, callId, argument
             imageBase64: screenshotBase64,
         })),
         currentScreenshot,
+        executedActions: [action],
     };
 }

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

@@ -51,8 +51,12 @@ export async function handleModelAction(deviceId, action, scale = 1.0, context =
             case "scroll":
                 const { scrollX, scrollY, startX, startY, endX, endY, hasAnchor } = resolveScrollGesture(action, {
                     scale,
-                    fallbackStartX: 500,
-                    fallbackStartY: 500
+                    fallbackStartX: Number.isFinite(context?.fallbackScrollStartX) ? Math.round(context.fallbackScrollStartX) : 500,
+                    fallbackStartY: Number.isFinite(context?.fallbackScrollStartY) ? Math.round(context.fallbackScrollStartY) : 500,
+                    minX: 0,
+                    maxX: Number.isFinite(context?.deviceWidth) ? Math.round(context.deviceWidth) - 1 : undefined,
+                    minY: 0,
+                    maxY: Number.isFinite(context?.deviceHeight) ? Math.round(context.deviceHeight) - 1 : undefined
                 });
                 addOutput({
                     type: 'action',

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

@@ -21,6 +21,18 @@ async function listConnectedDevices() {
     })
         .filter(entry => entry.id.length > 0);
 }
+export function getAndroidConnectErrorMessage({ state, avdName } = {}) {
+    if (state === "offline" && avdName) {
+        return `Emulator "${avdName}" is running but offline. Restart adb or cold boot the emulator, then retry.`;
+    }
+    if (state === "offline") {
+        return "Device is offline. Reconnect device or restart adb.";
+    }
+    if (state === "unauthorized") {
+        return "Authorize this computer on the device and retry.";
+    }
+    return "Selected device is no longer connected. Refresh and select again.";
+}
 function wait(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -35,6 +47,14 @@ function parseTargetToken(rawTarget) {
     }
     return { kind: "legacy", value: rawTarget };
 }
+function normalizeAvdName(value) {
+    const parts = value
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .filter((line) => line.toUpperCase() !== "OK");
+    return parts[0] || "";
+}
 async function getEmulatorAvdName(serial) {
     const candidates = [
         ["-s", serial, "emu", "avd", "name"],
@@ -45,7 +65,7 @@ async function getEmulatorAvdName(serial) {
     for (const args of candidates) {
         try {
             const { stdout } = await execAdb(args);
-            const value = stdout.trim();
+            const value = normalizeAvdName(stdout);
             if (value)
                 return value;
         }
@@ -74,16 +94,23 @@ function emulatorLaunchTimeoutError() {
     return new Error(`Emulator launch timed out after ${AVD_READY_TIMEOUT_SECONDS}s. Check AVD health and retry.`);
 }
 async function findRunningEmulatorByAvdName(avdName) {
+    const match = await findConnectedEmulatorByAvdName(avdName, { includeOffline: false });
+    return match?.state === "device" ? match.id : null;
+}
+async function findConnectedEmulatorByAvdName(avdName, options = {}) {
     const devices = await listConnectedDevices();
-    const readyEmulators = devices.filter((entry) => entry.state === "device" && entry.id.startsWith("emulator-"));
-    for (const entry of readyEmulators) {
+    const emulatorEntries = devices.filter((entry) => entry.id.startsWith("emulator-") && (options.includeOffline || entry.state === "device"));
+    for (const entry of emulatorEntries) {
         const runningAvdName = await getEmulatorAvdName(entry.id);
         if (runningAvdName === avdName) {
-            return entry.id;
+            return entry;
         }
     }
     return null;
 }
+function offlineEmulatorError(avdName) {
+    return new Error(getAndroidConnectErrorMessage({ state: "offline", avdName }));
+}
 async function launchAndWaitForAvd(avdName, timeoutMs = AVD_READY_TIMEOUT_MS, options = {}) {
     const log = options.log || console.log;
     let avdExists = false;
@@ -99,6 +126,10 @@ async function launchAndWaitForAvd(avdName, timeoutMs = AVD_READY_TIMEOUT_MS, op
     if (!avdExists) {
         throw new Error(`AVD "${avdName}" was not found. Create it in Android Studio and retry.`);
     }
+    const offlineMatch = await findConnectedEmulatorByAvdName(avdName, { includeOffline: true });
+    if (offlineMatch?.state === "offline") {
+        throw offlineEmulatorError(avdName);
+    }
     const baseline = await listConnectedDevices();
     const baselineReadyEmulators = new Set(baseline.filter((entry) => entry.state === "device" && entry.id.startsWith("emulator-")).map((entry) => entry.id));
     log(`Launching Android emulator "${avdName}"...`);
@@ -128,12 +159,16 @@ export async function connectToDevice(deviceTargetId, options = {}) {
     const readyDevices = devices.filter((entry) => entry.state === "device");
     if (parsedTarget.kind === "auto") {
         if (readyDevices.length === 0) {
+            const offlineEmulator = devices.find((entry) => entry.state === "offline" && entry.id.startsWith("emulator-"));
+            const message = offlineEmulator
+                ? "Android emulator is running but offline. Restart adb or cold boot the emulator, then retry."
+                : "No ready Android devices found. Connect a device (or start an emulator), authorize adb, and retry.";
             emitDesktopDebug("device.error", "device", {}, {
                 platform: "android",
                 operation: "connect",
-                message: "No ready Android devices detected."
+                message
             });
-            throw new Error("No ready Android devices found. Connect a device (or start an emulator), authorize adb, and retry.");
+            throw new Error(message);
         }
         const selected = readyDevices[0].id;
         log(`Using connected Android device: ${selected}`);
@@ -142,15 +177,18 @@ export async function connectToDevice(deviceTargetId, options = {}) {
     }
     if (parsedTarget.kind === "avd") {
         const deadline = Date.now() + AVD_READY_TIMEOUT_MS;
-        const alreadyRunning = await findRunningEmulatorByAvdName(parsedTarget.avdName);
-        if (alreadyRunning) {
-            const ready = await waitForWindowServiceReady(alreadyRunning, remainingTimeoutMs(deadline));
+        const existingEmulator = await findConnectedEmulatorByAvdName(parsedTarget.avdName, { includeOffline: true });
+        if (existingEmulator?.state === "offline") {
+            throw offlineEmulatorError(parsedTarget.avdName);
+        }
+        if (existingEmulator?.state === "device") {
+            const ready = await waitForWindowServiceReady(existingEmulator.id, remainingTimeoutMs(deadline));
             if (!ready) {
                 throw emulatorLaunchTimeoutError();
             }
-            log(`Using already-running emulator for AVD "${parsedTarget.avdName}": ${alreadyRunning}`);
-            emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: alreadyRunning, reused: true });
-            return alreadyRunning;
+            log(`Using already-running emulator for AVD "${parsedTarget.avdName}": ${existingEmulator.id}`);
+            emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: existingEmulator.id, reused: true });
+            return existingEmulator.id;
         }
         const launchedId = await launchAndWaitForAvd(parsedTarget.avdName, remainingTimeoutMs(deadline), { log });
         const ready = await waitForWindowServiceReady(launchedId, remainingTimeoutMs(deadline));
@@ -179,19 +217,16 @@ export async function connectToDevice(deviceTargetId, options = {}) {
         return targetId;
     }
     if (parsedTarget.kind === "legacy" && targetId) {
-        const runningLegacyAvd = await findRunningEmulatorByAvdName(targetId);
-        if (runningLegacyAvd) {
-            emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: runningLegacyAvd, reused: true });
-            return runningLegacyAvd;
+        const matchedLegacyAvd = await findConnectedEmulatorByAvdName(targetId, { includeOffline: true });
+        if (matchedLegacyAvd?.state === "offline") {
+            throw offlineEmulatorError(targetId);
+        }
+        if (matchedLegacyAvd?.state === "device") {
+            emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: matchedLegacyAvd.id, reused: true });
+            return matchedLegacyAvd.id;
         }
     }
-    let message = "Selected device is no longer connected. Refresh and select again.";
-    if (state === "offline") {
-        message = "Device is offline. Reconnect device or restart adb.";
-    }
-    else if (state === "unauthorized") {
-        message = "Authorize this computer on the device and retry.";
-    }
+    const message = getAndroidConnectErrorMessage({ state });
     emitDesktopDebug("device.error", "device", {}, { platform: "android", operation: "connect", message, targetId: targetId || deviceTargetId, state: state || "missing" });
     throw new Error(message);
 }

package/build/src/device/assertions.js

@@ -3,21 +3,28 @@
  */
 import { printCliOutput } from "../utils/console-output.js";
 export { buildAssertionSystemPrompt } from "../prompts/execution.js";
+const ASSERTION_PREFIXES = ["assert", "verify", "validate", "ensure"];
+function hasAssertionPrefix(lower) {
+    return ASSERTION_PREFIXES.some((prefix) => lower === prefix || lower.startsWith(`${prefix}:`) || lower.startsWith(`${prefix} `));
+}
 export function isAssertion(userInput) {
     const trimmed = userInput.trim();
     const lower = trimmed.toLowerCase();
-    return lower.startsWith("assert:") || lower.startsWith("assert ");
+    return hasAssertionPrefix(lower);
 }
 export function extractAssertionPrompt(userInput) {
     const trimmed = userInput.trim();
     const lower = trimmed.toLowerCase();
-    // Handle "assert:" or "Assert:"
-    if (lower.startsWith("assert:")) {
-        return trimmed.substring("assert:".length).trim();
-    }
-    // Handle "assert " or "Assert "
-    if (lower.startsWith("assert ")) {
-        return trimmed.substring("assert".length).trim();
+    for (const prefix of ASSERTION_PREFIXES) {
+        if (lower === prefix) {
+            return trimmed;
+        }
+        if (lower.startsWith(`${prefix}:`)) {
+            return trimmed.substring(prefix.length + 1).trim();
+        }
+        if (lower.startsWith(`${prefix} `)) {
+            return trimmed.substring(prefix.length).trim();
+        }
     }
     return trimmed;
 }

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

@@ -14,11 +14,11 @@ const execAsync = promisify(exec);
 // Active session state
 let activeSession = null;
 /**
- * Get simulator UDID by name (prefers already-booted simulator)
- * @param {string} simulatorName
- * @returns {Promise<string|null>}
+ * Resolve simulator by UDID or name (name matches prefer already-booted simulators).
+ * @param {string} simulatorNameOrUdid
+ * @returns {Promise<{name: string, udid: string, state: string}|null>}
  */
-async function getSimulatorUDID(simulatorName) {
+async function resolveSimulator(simulatorNameOrUdid) {
     try {
         const { stdout } = await execAsync("xcrun simctl list devices --json");
         const data = JSON.parse(stdout);
@@ -26,25 +26,31 @@ async function getSimulatorUDID(simulatorName) {
         let bootedMatch = null;
         for (const runtime of Object.values(data.devices)) {
             for (const device of runtime) {
-                if (device.name === simulatorName && device.isAvailable) {
+                if (!device.isAvailable) {
+                    continue;
+                }
+                if (device.udid === simulatorNameOrUdid) {
+                    return { name: device.name, udid: device.udid, state: device.state };
+                }
+                if (device.name === simulatorNameOrUdid) {
+                    const match = { name: device.name, udid: device.udid, state: device.state };
                     if (!firstMatch) {
-                        firstMatch = device.udid;
+                        firstMatch = match;
                     }
-                    // Prefer the already-booted one
                     if (device.state === "Booted") {
-                        bootedMatch = device.udid;
+                        bootedMatch = match;
                     }
                 }
             }
         }
         if (bootedMatch) {
-            logger.debug(`Found booted simulator: ${bootedMatch}`);
+            logger.debug(`Found booted simulator: ${bootedMatch.udid}`);
             return bootedMatch;
         }
         return firstMatch;
     }
     catch (error) {
-        logger.error("Failed to get simulator UDID", { error: error.message });
+        logger.error("Failed to resolve simulator", { error: error.message });
     }
     return null;
 }
@@ -84,33 +90,33 @@ async function findAnySimulator() {
  */
 async function bootSimulator(simulatorName, options = {}) {
     const log = options.log || console.log;
-    const udid = await getSimulatorUDID(simulatorName);
-    if (!udid) {
+    const simulator = await resolveSimulator(simulatorName);
+    if (!simulator) {
         throw new Error(`Simulator "${simulatorName}" not found. Run "xcrun simctl list devices" to see available simulators.`);
     }
-    log(`Found simulator "${simulatorName}" with UDID: ${udid}`);
+    log(`Found simulator "${simulator.name}" with UDID: ${simulator.udid}`);
     // Check if already booted
     const { stdout } = await execAsync("xcrun simctl list devices --json");
     const data = JSON.parse(stdout);
     for (const runtime of Object.values(data.devices)) {
         for (const device of runtime) {
-            if (device.udid === udid) {
+            if (device.udid === simulator.udid) {
                 if (device.state === "Booted") {
-                    log(`Simulator "${simulatorName}" is already booted`);
-                    return udid;
+                    log(`Simulator "${simulator.name}" is already booted`);
+                    return simulator;
                 }
                 break;
             }
         }
     }
-    log(`Booting simulator "${simulatorName}"...`);
-    await execAsync(`xcrun simctl boot ${udid}`);
+    log(`Booting simulator "${simulator.name}"...`);
+    await execAsync(`xcrun simctl boot ${simulator.udid}`);
     // Open Simulator app to show the device
     await execAsync("open -a Simulator");
     // Wait for boot to complete
-    await waitForSimulatorBoot(udid);
-    log(`Simulator "${simulatorName}" is fully booted`);
-    return udid;
+    await waitForSimulatorBoot(simulator.udid);
+    log(`Simulator "${simulator.name}" is fully booted`);
+    return simulator;
 }
 /**
  * Wait for simulator to finish booting
@@ -163,30 +169,30 @@ export async function connectToDevice(simulatorName, options = {}) {
         log(`No simulator specified, using: ${simulatorName}`);
     }
     // Boot simulator
-    const udid = await bootSimulator(simulatorName, { log });
+    const simulator = await bootSimulator(simulatorName, { log });
     // Create Appium session
     log("Creating Appium session...");
     const session = await appium.createSession({
         platformName: "iOS",
         "appium:automationName": "XCUITest",
-        "appium:deviceName": simulatorName,
-        "appium:udid": udid,
+        "appium:deviceName": simulator.name,
+        "appium:udid": simulator.udid,
         "appium:noReset": true,
         "appium:shouldTerminateApp": false,
     });
     activeSession = {
         sessionId: session.sessionId,
-        udid,
-        simulatorName,
+        udid: simulator.udid,
+        simulatorName: simulator.name,
     };
-    log(`Connected to simulator "${simulatorName}" (${udid})`);
+    log(`Connected to simulator "${simulator.name}" (${simulator.udid})`);
     emitDesktopDebug("device.connect", "device", {}, {
         platform: "ios",
         stage: "success",
-        simulatorName,
-        udid
+        simulatorName: simulator.name,
+        udid: simulator.udid
     });
-    return udid;
+    return simulator.udid;
 }
 /**
  * Get device info (screen dimensions and scale)