@loadmill/droid-cua 2.19.0 → 2.21.0

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

@@ -37,18 +37,25 @@ function normalizeBrowser(value) {
     }
     throw new Error("--browser must be one of: chrome, edge.");
 }
+const CLOUD_SOURCE_DISPLAY_NAMES = {
+    lambdatest: "LambdaTest",
+    "aws-device-farm": "AWS Device Farm",
+};
+function isCloudDeviceSource(deviceSource) {
+    return Object.hasOwn(CLOUD_SOURCE_DISPLAY_NAMES, deviceSource);
+}
 function normalizeDeviceSource(value) {
     if (value == null || value === "") {
         return "local";
     }
     if (typeof value !== "string") {
-        throw new Error("--device-source must be one of: local, lambdatest.");
+        throw new Error("--device-source must be one of: local, lambdatest, aws-device-farm.");
     }
     const normalized = value.trim().toLowerCase();
-    if (normalized === "local" || normalized === "lambdatest") {
+    if (normalized === "local" || isCloudDeviceSource(normalized)) {
         return normalized;
     }
-    throw new Error("--device-source must be one of: local, lambdatest.");
+    throw new Error("--device-source must be one of: local, lambdatest, aws-device-farm.");
 }
 function normalizeMobilePlatform(value, label) {
     if (!hasNonEmptyString(value)) {
@@ -72,31 +79,38 @@ function readNonEmptyCliValue(value) {
     }
     return null;
 }
-function assertNoLambdaTestFlags(args) {
-    const lambdaTestFlags = [
+function assertNoCloudFlags(args) {
+    const cloudFlags = [
         ["device-name", "--device-name"],
         ["os-version", "--os-version"],
         ["app", "--app"],
     ];
-    for (const [key, label] of lambdaTestFlags) {
+    for (const [key, label] of cloudFlags) {
         if (args[key] != null) {
-            throw new Error(`${label} can only be used with --device-source lambdatest.`);
+            throw new Error(`${label} can only be used with a cloud --device-source.`);
         }
     }
 }
-function normalizeLambdaTestAppPath(value) {
+function normalizeCloudAppPath(value, platform, deviceSource) {
     if (!hasNonEmptyString(value)) {
         return null;
     }
+    const displayName = CLOUD_SOURCE_DISPLAY_NAMES[deviceSource];
     const appPath = value.trim();
     const lower = appPath.toLowerCase();
-    if (lower.endsWith(".apk") || lower.endsWith(".ipa")) {
-        return appPath;
-    }
     if (lower.endsWith(".app")) {
-        throw new Error("LambdaTest real-device sessions require an .apk for Android or an .ipa for iOS. .app bundles are not supported.");
+        throw new Error(`${displayName} real-device sessions require an .apk for Android or an .ipa for iOS. .app bundles are not supported.`);
+    }
+    if (!lower.endsWith(".apk") && !lower.endsWith(".ipa")) {
+        throw new Error(`--app must point to an .apk or .ipa file for ${displayName} runs.`);
+    }
+    if (platform === "android" && !lower.endsWith(".apk")) {
+        throw new Error(`${displayName} Android sessions require an .apk build.`);
+    }
+    if (platform === "ios" && !lower.endsWith(".ipa")) {
+        throw new Error(`${displayName} iOS sessions require an .ipa build.`);
     }
-    throw new Error("--app must point to an .apk or .ipa file for LambdaTest runs.");
+    return appPath;
 }
 export function resolveHeadlessTarget(args = {}) {
     const target = normalizeTarget(args.target);
@@ -104,6 +118,9 @@ export function resolveHeadlessTarget(args = {}) {
     const avdName = hasNonEmptyString(args.avd) ? args.avd.trim() : null;
     const platform = normalizeMobilePlatform(args.platform, "--platform");
     const deviceSource = normalizeDeviceSource(args["device-source"]);
+    if (args["list-devices"] != null && deviceSource !== "aws-device-farm") {
+        throw new Error("--list-devices can only be used with --device-source aws-device-farm.");
+    }
     if (target === "web") {
         if (avdName || platform) {
             throw new Error("--avd and --platform cannot be used with --target web.");
@@ -111,7 +128,7 @@ export function resolveHeadlessTarget(args = {}) {
         if (deviceSource !== "local") {
             throw new Error("--device-source can only be used with --target mobile.");
         }
-        assertNoLambdaTestFlags(args);
+        assertNoCloudFlags(args);
         return {
             target,
             sessionMode,
@@ -122,6 +139,7 @@ export function resolveHeadlessTarget(args = {}) {
             deviceName: null,
             osVersion: null,
             appPath: null,
+            listDevices: false,
         };
     }
     if (args["session-mode"] != null) {
@@ -130,27 +148,42 @@ export function resolveHeadlessTarget(args = {}) {
     if (args.browser != null) {
         throw new Error("--browser can only be used with --target web.");
     }
+    // --list-devices only needs credentials — no device/app flags required.
+    if (args["list-devices"] != null) {
+        return {
+            target,
+            sessionMode: null,
+            browserFamily: null,
+            deviceSource,
+            avdName: null,
+            platform: null,
+            deviceName: null,
+            osVersion: null,
+            appPath: null,
+            listDevices: true,
+        };
+    }
     if (deviceSource === "local") {
-        assertNoLambdaTestFlags(args);
+        assertNoCloudFlags(args);
     }
-    if (deviceSource === "lambdatest") {
+    if (isCloudDeviceSource(deviceSource)) {
         const deviceName = hasNonEmptyString(args["device-name"]) ? args["device-name"].trim() : null;
         const osVersion = readNonEmptyCliValue(args["os-version"]);
-        const appPath = normalizeLambdaTestAppPath(args.app);
+        const appPath = normalizeCloudAppPath(args.app, platform, deviceSource);
         if (avdName) {
-            throw new Error("--avd cannot be used with --device-source lambdatest.");
+            throw new Error(`--avd cannot be used with --device-source ${deviceSource}.`);
         }
         if (!platform) {
-            throw new Error("--platform is required with --device-source lambdatest.");
+            throw new Error(`--platform is required with --device-source ${deviceSource}.`);
         }
         if (!deviceName) {
-            throw new Error("--device-name is required with --device-source lambdatest.");
+            throw new Error(`--device-name is required with --device-source ${deviceSource}.`);
         }
         if (!osVersion) {
-            throw new Error("--os-version is required with --device-source lambdatest.");
+            throw new Error(`--os-version is required with --device-source ${deviceSource}.`);
         }
         if (!appPath) {
-            throw new Error("--app is required with --device-source lambdatest.");
+            throw new Error(`--app is required with --device-source ${deviceSource}.`);
         }
         return {
             target,
@@ -162,6 +195,7 @@ export function resolveHeadlessTarget(args = {}) {
             deviceName,
             osVersion,
             appPath,
+            listDevices: false,
         };
     }
     return {
@@ -174,5 +208,6 @@ export function resolveHeadlessTarget(args = {}) {
         deviceName: null,
         osVersion: null,
         appPath: null,
+        listDevices: false,
     };
 }

package/build/src/commands/loadmill.js

@@ -2,7 +2,7 @@
  * Loadmill command handler
  */
 import { createLoadmillApiClient, executeLoadmillCommand, getApiToken } from "../integrations/loadmill/index.js";
-import { createResolvedLlmClient, resolveRuntimeConfigFromEnv, resolveRuntimeCredentialsFromEnv, } from "../core/runtime-config.js";
+import { createResolvedLlmClient, resolveEffectiveHelperModel, resolveRuntimeConfigFromEnv, resolveRuntimeCredentialsFromEnv, } from "../core/runtime-config.js";
 /**
  * Handle /loadmill command
  * @param {string} args - Command arguments (natural language command)
@@ -60,10 +60,17 @@ export async function handleLoadmill(args, session, context) {
             credentials: runtimeCredentials,
             clientName: "cli",
         });
+        const helperModel = runtimeConfig.llmProviderMode === "openai"
+            ? resolveEffectiveHelperModel({
+                llmProviderMode: runtimeConfig.llmProviderMode,
+                cuaModel: runtimeConfig.cuaModel,
+            })
+            : null;
         // Execute the command
         const result = await executeLoadmillCommand(command, {
             loadmillClient,
             openAiClient,
+            helperModel,
             onProgress: ({ message }) => {
                 addOutput({ type: 'info', text: `[Loadmill] ${message}` });
             }

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

@@ -34,6 +34,10 @@ export function mediaKindOf(line) {
 export function isHiddenExecutionLogEvent(line) {
     if (line.eventType === "run_paused")
         return true;
+    // Connecting markers drive renderer state (isConnecting) but carry no
+    // user-facing content beyond the cloud progress lines already shown.
+    if (line.eventType === "run_connecting" || line.eventType === "run_connected")
+        return true;
     return mediaKindOf(line) === "hidden-debug";
 }
 export function isGalleryMediaEvent(line) {

package/build/src/device/cloud/aws-device-farm/adapter.js

@@ -0,0 +1,388 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { CreateProjectCommand, CreateRemoteAccessSessionCommand, CreateUploadCommand, DeleteUploadCommand, DeviceFarmClient, GetAccountSettingsCommand, GetRemoteAccessSessionCommand, GetUploadCommand, ListDevicesCommand, ListProjectsCommand, StopRemoteAccessSessionCommand } from "@aws-sdk/client-device-farm";
+import { reportCloudNote, reportCloudPhase, reportCloudProgress } from "../progress.js";
+const REGION = "us-west-2";
+// Documented default remote-access concurrency quota.
+const REMOTE_ACCESS_PARALLEL_LIMIT = 2;
+// Statuses that mean an upload or remote-access session will NEVER reach the
+// state we're waiting for. Hitting one stops polling immediately instead of
+// spinning until the timeout.
+const TERMINAL_FAILURE_STATUSES = new Set(["FAILED", "ERRORED", "STOPPING", "STOPPED"]);
+// Poll budgets. Provisioning is documented at ~1 min; uploads process in
+// seconds; these caps are generous backstops so a stuck AWS resource surfaces
+// an error instead of hanging the CLI/desktop forever.
+const PROVISION_TIMEOUT_MS = 5 * 60 * 1000; // wait for session RUNNING
+const UPLOAD_TIMEOUT_MS = 3 * 60 * 1000; // wait for upload processing
+const RELEASE_TIMEOUT_MS = 5 * 60 * 1000; // wait for session COMPLETED
+// Single session, mirrors the activeSession design in connection.js.
+let activeRemoteSession = null; // { sessionArn, hubUrl }
+function makeClient(creds) {
+    return new DeviceFarmClient({
+        region: REGION,
+        credentials: {
+            accessKeyId: creds.username,
+            secretAccessKey: creds.accessKey
+        }
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// sleep() that rejects the instant `signal` aborts, so a Stop during the
+// provisioning poll wakes the wait immediately instead of waiting out the full
+// interval. With no signal it behaves exactly like sleep().
+function abortableSleep(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(signal.reason ?? new Error("Provisioning cancelled."));
+    }
+    if (!signal) {
+        return sleep(ms);
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error("Provisioning cancelled."));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Polls `fetchResult()` every `intervalMs` until `isDone(status)` is true,
+ * returning the full result. Throws once `maxWaitMs` elapses, and — unless
+ * `treatTerminalAsDone` is set — as soon as a terminal-failure status appears.
+ * `statusOf` extracts the status string from each result; `onStatus` reports it
+ * for progress lines. An optional `signal` aborts the poll: it's checked at the
+ * top of each iteration and the inter-poll wait wakes immediately on abort.
+ */
+async function pollUntil(fetchResult, { statusOf, isDone, intervalMs, maxWaitMs, label, onStatus, treatTerminalAsDone = false, signal }) {
+    const deadline = Date.now() + maxWaitMs;
+    for (;;) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error(`${label} cancelled.`);
+        }
+        const result = await fetchResult();
+        const status = statusOf(result);
+        onStatus?.(status);
+        if (isDone(status)) {
+            return result;
+        }
+        if (TERMINAL_FAILURE_STATUSES.has(status)) {
+            if (treatTerminalAsDone) {
+                return result;
+            }
+            throw new Error(`${label} entered terminal state "${status}".`);
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`${label} timed out after ${Math.round(maxWaitMs / 1000)}s (last status "${status}").`);
+        }
+        await abortableSleep(intervalMs, signal);
+    }
+}
+// Statuses that mean a remote-access session is already terminating or gone — no
+// further Stop is needed.
+const SESSION_TERMINATING_STATUSES = new Set(["STOPPING", "STOPPED", "COMPLETED"]);
+// AWS ignores StopRemoteAccessSession on a session that is still provisioning
+// (PENDING/PREPARING): a single Stop there is a no-op, the session finishes
+// provisioning, and it leaks as RUNNING — billed up to the session's max
+// duration. So after a cancel mid-provisioning, reconcile until the session is
+// confirmed terminating: a session only becomes stoppable once it reaches
+// RUNNING, so re-issue Stop each tick until GetRemoteAccessSession reports a
+// terminating status (or a bounded wait elapses). Never throws — it's a
+// best-effort background cleanup so the cancel itself stays instant.
+async function ensureRemoteAccessSessionStopped(client, arn, { timeoutMs = PROVISION_TIMEOUT_MS, intervalMs = 3000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        let status;
+        try {
+            const { remoteAccessSession } = await client.send(new GetRemoteAccessSessionCommand({ arn }));
+            status = remoteAccessSession?.status;
+        }
+        catch {
+            // Can't read state — fire one best-effort Stop and give up reconciling.
+            await client.send(new StopRemoteAccessSessionCommand({ arn })).catch(() => { });
+            return;
+        }
+        if (!status || SESSION_TERMINATING_STATUSES.has(status)) {
+            return;
+        }
+        await client.send(new StopRemoteAccessSessionCommand({ arn })).catch(() => { });
+        if (Date.now() >= deadline) {
+            return;
+        }
+        await sleep(intervalMs);
+    }
+}
+// ListDevices is paginated (~15 devices/page). Callers that match a specific
+// device client-side MUST page through every result, or devices on later pages
+// are invisible.
+async function listAllDevices(client, filters) {
+    const devices = [];
+    let nextToken;
+    do {
+        const response = await client.send(new ListDevicesCommand({ filters, nextToken }));
+        devices.push(...(response.devices ?? []));
+        nextToken = response.nextToken;
+    } while (nextToken);
+    return devices;
+}
+async function requestAccountInfo(creds) {
+    const { accountSettings } = await makeClient(creds).send(new GetAccountSettingsCommand({}));
+    const trialMinutes = accountSettings?.trialMinutes;
+    const remaining = typeof trialMinutes?.remaining === "number" ? trialMinutes.remaining : null;
+    const total = typeof trialMinutes?.total === "number" ? trialMinutes.total : null;
+    // Some accounts report no trial allotment (fields absent). Surface plain
+    // metered billing instead of throwing on `.remaining.toFixed(...)` — a throw
+    // here makes validateCredentials report valid credentials as invalid.
+    const summary = remaining !== null && total !== null
+        ? `Metered billing — ${remaining.toFixed(0)} of ${total} free trial minutes remaining.`
+        : "Metered billing.";
+    return {
+        plan: "Metered",
+        parallelLimit: REMOTE_ACCESS_PARALLEL_LIMIT,
+        ...(remaining !== null ? { trialMinutesRemaining: remaining } : {}),
+        summary
+    };
+}
+/** @type {import("../adapter").CloudProviderAdapter} */
+export const awsDeviceFarmAdapter = {
+    id: "aws-device-farm",
+    displayName: "AWS Device Farm",
+    async validateCredentials(creds) {
+        try {
+            const account = await requestAccountInfo(creds);
+            return {
+                ok: true,
+                message: account.summary,
+                account
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                message: error instanceof Error ? error.message : "Failed to validate AWS Device Farm credentials."
+            };
+        }
+    },
+    async getAccountInfo(creds) {
+        return requestAccountInfo(creds);
+    },
+    async ensureProject(creds) {
+        const client = makeClient(creds);
+        let nextToken;
+        do {
+            const { projects = [], nextToken: token } = await client.send(new ListProjectsCommand({ nextToken }));
+            const existing = projects.find((project) => project.name === "droid-cua");
+            if (existing) {
+                return existing.arn;
+            }
+            nextToken = token;
+        } while (nextToken);
+        const { project } = await client.send(new CreateProjectCommand({ name: "droid-cua" }));
+        return project.arn;
+    },
+    async getAvailableDevices(creds) {
+        const client = makeClient(creds);
+        const rawDevices = await listAllDevices(client, [
+            { attribute: "REMOTE_ACCESS_ENABLED", operator: "EQUALS", values: ["TRUE"] }
+        ]);
+        return rawDevices
+            .map((device) => ({
+            id: device.arn,
+            name: device.name,
+            deviceName: device.name,
+            platform: device.platform.toLowerCase(),
+            osVersion: device.os,
+            arn: device.arn
+        }))
+            .sort((left, right) => {
+            if (left.platform !== right.platform) {
+                return left.platform.localeCompare(right.platform);
+            }
+            if (left.name !== right.name) {
+                return left.name.localeCompare(right.name);
+            }
+            return right.osVersion.localeCompare(left.osVersion, undefined, { numeric: true, sensitivity: "base" });
+        });
+    },
+    async uploadApp(creds, localPath) {
+        const client = makeClient(creds);
+        reportCloudPhase("create upload");
+        const { upload } = await client.send(new CreateUploadCommand({
+            projectArn: creds.projectArn,
+            name: path.basename(localPath),
+            type: localPath.toLowerCase().endsWith(".ipa") ? "IOS_APP" : "ANDROID_APP",
+            contentType: "application/octet-stream"
+        }));
+        reportCloudPhase(`upload ${path.basename(localPath)} to S3`);
+        const putResponse = await fetch(upload.url, {
+            method: "PUT",
+            headers: { "Content-Type": "application/octet-stream" },
+            body: await readFile(localPath)
+        });
+        // A failed PUT leaves the binary absent; AWS keeps the upload at INITIALIZED
+        // forever, so without this check the processing poll never terminates.
+        if (!putResponse.ok) {
+            throw new Error(`Device Farm S3 upload failed (HTTP ${putResponse.status}) for ${path.basename(localPath)}.`);
+        }
+        reportCloudPhase("wait for upload processing");
+        // SUCCEEDED resolves; FAILED is in TERMINAL_FAILURE_STATUSES so pollUntil
+        // throws on it (e.g. wrong upload type for the binary).
+        await pollUntil(() => client.send(new GetUploadCommand({ arn: upload.arn })), {
+            statusOf: (result) => result.upload.status,
+            isDone: (status) => status === "SUCCEEDED",
+            intervalMs: 3000,
+            maxWaitMs: UPLOAD_TIMEOUT_MS,
+            label: `Device Farm upload processing for ${path.basename(localPath)}`,
+            onStatus: (status) => reportCloudProgress(`upload status: ${status}`)
+        });
+        return { id: upload.arn, remotePath: upload.arn };
+    },
+    async getAppStatus(creds, ref) {
+        const { upload } = await makeClient(creds).send(new GetUploadCommand({ arn: ref.id }));
+        if (upload.status === "SUCCEEDED") {
+            return { status: "uploaded" };
+        }
+        if (upload.status === "INITIALIZED" || upload.status === "PROCESSING") {
+            return { status: "processing" };
+        }
+        return { status: "missing" };
+    },
+    async deleteApp(creds, ref) {
+        await makeClient(creds).send(new DeleteUploadCommand({ arn: ref.id }));
+    },
+    async prepareSession(creds, opts, { signal } = {}) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error("Provisioning cancelled.");
+        }
+        const client = makeClient(creds);
+        reportCloudPhase("resolve device ARN");
+        reportCloudProgress(`locating "${opts.deviceName}" (${opts.osVersion}) in the device catalog...`);
+        // AWS's OS_VERSION filter does NOT match the device `os` field (EQUALS on a
+        // real version like "17.3.1" returns nothing), and names repeat across OS
+        // versions (e.g. two "Apple iPad (2022)" entries at 16.4 and 17.3.1). So page
+        // through the remote-access catalog and match on name + osVersion client-side
+        // — the exact pairing getAvailableDevices surfaced for selection.
+        const devices = await listAllDevices(client, [
+            { attribute: "PLATFORM", operator: "EQUALS", values: [opts.platform.toUpperCase()] },
+            { attribute: "REMOTE_ACCESS_ENABLED", operator: "EQUALS", values: ["TRUE"] }
+        ]);
+        const device = devices.find((entry) => entry.name === opts.deviceName && entry.os === opts.osVersion);
+        if (!device) {
+            const sameName = devices.filter((entry) => entry.name === opts.deviceName);
+            if (sameName.length > 0) {
+                // The device name exists, just not at the requested OS version. Don't
+                // silently provision a different OS (a CLI --os-version typo would then
+                // run somewhere unexpected) — list the valid versions so the caller can
+                // re-run correctly.
+                const available = [...new Set(sameName.map((entry) => entry.os))]
+                    .sort((left, right) => left.localeCompare(right, undefined, { numeric: true }))
+                    .join(", ");
+                throw new Error(`No remote-access-enabled "${opts.deviceName}" runs ${opts.platform.toUpperCase()} ${opts.osVersion}. ` +
+                    `Available OS versions for this device: ${available}.`);
+            }
+            throw new Error(`No remote-access-enabled ${opts.platform.toUpperCase()} device matches "${opts.deviceName}" (${opts.osVersion}). ` +
+                "It may have left the Device Farm fleet — refresh Available Devices and pick another.");
+        }
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error("Provisioning cancelled.");
+        }
+        reportCloudPhase("create remote access session");
+        const { remoteAccessSession: created } = await client.send(new CreateRemoteAccessSessionCommand({
+            projectArn: creds.projectArn,
+            deviceArn: device.arn,
+            appArn: opts.app,
+            name: opts.sessionName,
+            configuration: { billingMethod: "METERED" }
+        }));
+        reportCloudPhase("wait for session RUNNING");
+        let session;
+        try {
+            ({ remoteAccessSession: session } = await pollUntil(() => client.send(new GetRemoteAccessSessionCommand({ arn: created.arn })), {
+                statusOf: (result) => result.remoteAccessSession.status,
+                isDone: (status) => status === "RUNNING",
+                intervalMs: 5000,
+                maxWaitMs: PROVISION_TIMEOUT_MS,
+                label: `Device Farm provisioning for "${opts.deviceName}" (${opts.osVersion})`,
+                onStatus: (status) => reportCloudProgress(`remote access session status: ${status}`),
+                signal
+            }));
+        }
+        catch (error) {
+            // The session was created but never reached RUNNING (cancel/timeout/terminal
+            // failure). activeRemoteSession was never set and prepareSession is now
+            // throwing, so connection.js's connect-failure cleanup can't reach it.
+            // A single Stop is unreliable here: AWS ignores StopRemoteAccessSession on a
+            // still-provisioning (PENDING/PREPARING) session, which then finishes
+            // provisioning and leaks as RUNNING. Reconcile before returning so callers
+            // can safely exit after this promise rejects.
+            reportCloudPhase("stop remote access session");
+            await ensureRemoteAccessSessionStopped(client, created.arn);
+            throw error;
+        }
+        activeRemoteSession = {
+            sessionArn: session.arn,
+            hubUrl: session.endpoints.remoteDriverEndpoint.replace(/\/+$/, "")
+        };
+    },
+    async releaseSession(creds, { waitForCompletion = true } = {}) {
+        if (!activeRemoteSession) {
+            return;
+        }
+        const client = makeClient(creds);
+        const sessionArn = activeRemoteSession.sessionArn;
+        reportCloudPhase("stop remote access session");
+        await client.send(new StopRemoteAccessSessionCommand({ arn: sessionArn }));
+        // Stop accepted → billing stopped and the session is released. Clear state
+        // now so a slow/failed COMPLETED wait below can't leave it stale.
+        activeRemoteSession = null;
+        // Billing stops the moment the stop request is accepted; waiting for
+        // COMPLETED (and the billed-minutes report) adds ~2+ minutes, so
+        // user-facing flows (the CLI) skip it.
+        if (!waitForCompletion) {
+            reportCloudProgress("session stop requested — billing stopped");
+            return;
+        }
+        // This flow runs rarely (development/debugging), so waiting for the
+        // session to fully COMPLETE to surface the billed device-minutes is
+        // worth the extra ~1-2 minutes of wall time. The stop is already in
+        // flight, so any terminal state (STOPPED/COMPLETED) counts as done.
+        reportCloudPhase("wait for session COMPLETED");
+        const { remoteAccessSession: session } = await pollUntil(() => client.send(new GetRemoteAccessSessionCommand({ arn: sessionArn })), {
+            statusOf: (result) => result.remoteAccessSession.status,
+            isDone: (status) => status === "COMPLETED",
+            intervalMs: 5000,
+            maxWaitMs: RELEASE_TIMEOUT_MS,
+            label: "Device Farm session teardown",
+            onStatus: (status) => reportCloudProgress(`remote access session status: ${status}`),
+            treatTerminalAsDone: true
+        });
+        reportCloudNote(`billed deviceMinutes: ${JSON.stringify(session.deviceMinutes)}`);
+    },
+    buildCapabilities(opts) {
+        // Device & app are bound at remote-access-session creation, not via capabilities;
+        // udid/platformVersion caps can break session creation against Device Farm.
+        return {
+            platformName: opts.platform,
+            "appium:automationName": opts.platform === "ios" ? "XCUITest" : "UiAutomator2",
+            "appium:newCommandTimeout": 240
+        };
+    },
+    getHubUrl() {
+        return activeRemoteSession.hubUrl;
+    },
+    getAuthHeader() {
+        // The hub endpoint is a presigned capability URL — no auth header needed.
+        return "";
+    },
+    async getSessionArtifacts() {
+        return {};
+    },
+    async setSessionStatus() {
+        // Device Farm has no session pass/fail status equivalent.
+    }
+};

package/build/src/device/cloud/aws-device-farm/upload-cache.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { createReadStream, existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { reportCloudProgress } from "../progress.js";
+export const DEFAULT_UPLOAD_CACHE_PATH = path.join(os.tmpdir(), "droid-cua", "aws-device-farm-upload-cache.json");
+// Stream the binary through the hash rather than buffering the whole .apk/.ipa
+// (tens–hundreds of MB) in one allocation just to checksum it.
+async function hashFile(filePath) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+/**
+ * Device Farm has no server-side upload dedup — the upload ARN itself is the
+ * cache (reusable for ~30 days), keyed by sha256(binary)+projectArn. Cached
+ * ARNs are liveness-checked via getAppStatus before reuse; uploads are never
+ * deleted here, stale ones age out via the 30-day expiry.
+ *
+ * @returns {Promise<{ app: { id: string, remotePath: string }, status: { status: string } }>}
+ */
+export async function resolveUploadedApp({ adapter, credentials, appPath, cachePath = DEFAULT_UPLOAD_CACHE_PATH }) {
+    const sha256 = await hashFile(appPath);
+    const cacheKey = `${sha256}:${credentials.projectArn}`;
+    const cache = existsSync(cachePath) ? JSON.parse(await readFile(cachePath, "utf8")) : {};
+    if (cache[cacheKey]) {
+        const cachedApp = { id: cache[cacheKey], remotePath: cache[cacheKey] };
+        const cachedStatus = await adapter.getAppStatus(credentials, cachedApp);
+        if (cachedStatus.status === "uploaded") {
+            reportCloudProgress("upload cache hit — reusing existing upload ARN");
+            return { app: cachedApp, status: cachedStatus };
+        }
+    }
+    const app = await adapter.uploadApp(credentials, appPath);
+    cache[cacheKey] = app.remotePath;
+    await mkdir(path.dirname(cachePath), { recursive: true });
+    await writeFile(cachePath, JSON.stringify(cache, null, 2));
+    return { app, status: await adapter.getAppStatus(credentials, app) };
+}

package/build/src/device/cloud/cloud-appium-client.js

@@ -8,10 +8,11 @@ export class CloudAppiumClient {
         this.creds = creds;
     }
     async request(method, path, body = null) {
+        const authHeader = this.provider.getAuthHeader(this.creds);
         const response = await fetch(`${this.provider.getHubUrl()}${path}`, {
             method,
             headers: {
-                Authorization: this.provider.getAuthHeader(this.creds),
+                ...(authHeader ? { Authorization: authHeader } : {}),
                 ...(body ? { "Content-Type": "application/json" } : {})
             },
             body: body ? JSON.stringify(body) : undefined