@loadmill/droid-cua 2.25.0 → 2.26.0

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

@@ -18,10 +18,13 @@ const MODEL_PRICING = Object.freeze({
     "gpt-5.4": Object.freeze({
         ...OPENAI_GPT_5_4_PRICING,
     }),
-    // Loadmill Smart currently routes to GPT-5.4 behind the Loadmill LLM gateway.
+    // Loadmill Smart currently routes to GPT-5.6 Terra behind the Loadmill LLM gateway.
     // Keep this explicit so pricing can be updated here if the backing model changes.
     "loadmill-smart": Object.freeze({
-        ...OPENAI_GPT_5_4_PRICING,
+        ...OPENAI_GPT_5_6_TERRA_PRICING,
+    }),
+    "loadmill-pulse": Object.freeze({
+        ...OPENAI_GPT_5_6_LUNA_PRICING,
     }),
 });
 function finiteNumber(value) {
@@ -50,6 +53,9 @@ export function normalizeDroidCuaCostModel(model) {
     if (model === "loadmill-smart" || model === "smart") {
         return "loadmill-smart";
     }
+    if (model === "loadmill-pulse" || model === "pulse") {
+        return "loadmill-pulse";
+    }
     return null;
 }
 export function createDroidCuaRunUsageTotals({ model = null } = {}) {

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

@@ -251,6 +251,7 @@ export class ExecutionEngine {
         this.navigateToUrl = options.navigateToUrl || navigateBrowserToUrl;
         this.closeCurrentTab = options.closeCurrentTab || closeCurrentBrowserTab;
         this.executeLoadmillInstruction = options.executeLoadmillInstruction || executeLoadmillInstruction;
+        this.connectToDevice = options.connectToDevice || null;
         this.toolCapabilities = options.toolCapabilities || {};
         this.secretsByKey = options.secretsByKey && typeof options.secretsByKey === "object" ? options.secretsByKey : {};
         this.baseSystemPrompt = options.baseSystemPrompt || session?.systemPrompt || null;

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

@@ -7,6 +7,7 @@ export const LOADMILL_MODEL_ALIASES = Object.freeze({
     DEFAULT_AGENT_MODEL: "default-agent-model",
     FAST: "fast",
     SMART: "smart",
+    PULSE: "pulse",
     BEACON: "beacon",
 });
 const LOADMILL_MODEL_ALIAS_SET = new Set(Object.values(LOADMILL_MODEL_ALIASES));
@@ -90,9 +91,13 @@ export function inferLlmProviderModeFromCredentials(credentials = {}) {
 }
 export function resolveGatewayCuaModelAlias({ cuaModel } = {}) {
     const normalizedCuaModel = resolveCuaModel(cuaModel);
-    return normalizedCuaModel === "loadmill-beacon"
-        ? LOADMILL_MODEL_ALIASES.BEACON
-        : LOADMILL_MODEL_ALIASES.SMART;
+    if (normalizedCuaModel === "loadmill-pulse") {
+        return LOADMILL_MODEL_ALIASES.PULSE;
+    }
+    if (normalizedCuaModel === "loadmill-beacon") {
+        return LOADMILL_MODEL_ALIASES.BEACON;
+    }
+    return LOADMILL_MODEL_ALIASES.SMART;
 }
 export function resolveEffectiveCuaModel({ llmProviderMode = null, cuaModel = null, } = {}) {
     const providerMode = resolveLlmProviderMode(llmProviderMode);

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

@@ -7,7 +7,7 @@ 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) {
+export async function hashFile(filePath) {
     const hash = createHash("sha256");
     for await (const chunk of createReadStream(filePath)) {
         hash.update(chunk);

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

@@ -4,7 +4,7 @@ import { CloudAppiumClient } from "./cloud-appium-client.js";
 import { reportCloudPhase } from "./progress.js";
 let activeSession = null;
 function buildCloudCapabilities(options) {
-    const { providerId, platform, deviceName, osVersion, appRef, credentials, buildName, sessionName } = options;
+    const { providerId, platform, deviceName, osVersion, appRef, credentials, buildName, sessionName, cloudSessionId, artifacts } = options;
     const adapter = getCloudProviderAdapter(providerId);
     if (!adapter) {
         throw new Error(`Cloud provider "${providerId}" is not registered.`);
@@ -20,7 +20,9 @@ function buildCloudCapabilities(options) {
             accessKey: credentials?.accessKey,
             projectName: "droid-cua",
             buildName: buildName || `desktop-${new Date().toISOString().slice(0, 10)}`,
-            sessionName: sessionName || `${deviceName} (${platform})`
+            sessionName: sessionName || `${deviceName} (${platform})`,
+            cloudSessionId,
+            artifacts
         }
     };
 }
@@ -29,11 +31,19 @@ export async function connectToDevice(options, logOptions = {}) {
     if (!options || typeof options !== "object") {
         throw new Error("Cloud device connection requires a provider payload.");
     }
-    const { providerId, platform, deviceName, osVersion, appRef, credentials, buildName, sessionName } = options;
-    if (!providerId || !platform || !deviceName || !osVersion || !appRef) {
+    const { providerId, platform, deviceName, osVersion, appRef, credentials, buildName, sessionName, cloudSessionId, artifacts } = options;
+    const isReconnect = providerId === "loadmill-cloud" && Boolean(cloudSessionId);
+    if (!providerId ||
+        (!isReconnect && (!platform || !deviceName || !osVersion)) ||
+        (!appRef && !isReconnect)) {
         throw new Error("Cloud device connection is missing required session details.");
     }
-    if (!credentials?.username || !credentials?.accessKey) {
+    if (providerId === "loadmill-cloud") {
+        if (!credentials?.bearerToken) {
+            throw new Error("Loadmill Cloud connection is missing a Loadmill API token.");
+        }
+    }
+    else if (!credentials?.username || !credentials?.accessKey) {
         throw new Error("Cloud device connection is missing provider credentials.");
     }
     const { adapter, capabilities } = buildCloudCapabilities({
@@ -44,7 +54,9 @@ export async function connectToDevice(options, logOptions = {}) {
         appRef,
         credentials,
         buildName,
-        sessionName
+        sessionName,
+        cloudSessionId,
+        artifacts
     });
     // Optional AbortSignal (Stop/Pause during provisioning). It rides inside the
     // cloud-options object — see the facade in src/device/connection.js — so no

package/build/src/device/cloud/loadmill-cloud/adapter.js

@@ -0,0 +1,537 @@
+import path from "node:path";
+import { hashFile } from "../aws-device-farm/upload-cache.js";
+import { reportCloudNote, reportCloudPhase, reportCloudPhaseCloseText, reportCloudPhaseFlush, reportCloudPrint, reportCloudProgress } from "../progress.js";
+import { LoadmillCloudControlPlaneClient } from "./control-plane-client.js";
+import { downloadArtifacts } from "./artifact-downloader.js";
+import { formatBytes } from "./format-bytes.js";
+import { timingLog } from "./timing.js";
+const RESUMABLE_STATUSES = new Set(["PROVISIONED", "CONNECTED", "RUNNING"]);
+const TERMINAL_STATUSES = new Set(["COMPLETED", "CANCELLED", "ERROR"]);
+// Artifacts are readable from DF while a run is still tearing down
+// (STOPPING), not just once it reaches a true terminal state. Mirrors the
+// server's ARTIFACT_READY_STATES.
+const ARTIFACT_READY_STATUSES = new Set(["STOPPING", ...TERMINAL_STATUSES]);
+const SLOT_HELD_STATUSES = new Set(["PREPARING", "PROVISIONED", "CONNECTED", "RUNNING"]);
+const ARTIFACT_POLL_BUDGET_MS = 3 * 60_000;
+const ARTIFACT_POLL_INTERVAL_MS = 5_000;
+const TEARDOWN_STOP_BUDGET_MS = 1_500;
+function formatSecondsOneDecimal(ms) {
+    return (Math.max(0, ms) / 1000).toFixed(1);
+}
+const DEVICE_CACHE_TTL_MS = 5 * 60 * 1000;
+const deviceCacheByKey = new Map();
+function deviceCacheKey(creds) {
+    return `${creds?.baseUrl || ""}::${creds?.bearerToken || ""}`;
+}
+let activeRun = null;
+function makeClient(creds) {
+    return new LoadmillCloudControlPlaneClient({ bearerToken: creds.bearerToken, baseUrl: creds.baseUrl });
+}
+function mapDevice(device) {
+    return {
+        id: `${device.platform}:${device.deviceName}:${device.osVersion}`,
+        name: device.deviceName,
+        deviceName: device.deviceName,
+        platform: device.platform,
+        osVersion: device.osVersion,
+    };
+}
+async function timedStopRun(client, sessionId, { signal } = {}) {
+    timingLog(`stopRun invoked: session=${sessionId}`);
+    try {
+        const result = await client.stopRun(sessionId, { signal });
+        timingLog(`stopRun resolved: session=${sessionId}`);
+        return result;
+    }
+    catch (error) {
+        timingLog(`stopRun resolved (error): session=${sessionId} error=${error.message}`);
+        throw error;
+    }
+}
+function abortableSleep(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(signal.reason ?? new Error("Provisioning cancelled."));
+    }
+    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 });
+    });
+}
+function formatQueueMessage(state) {
+    const parts = [];
+    if (typeof state.queuePosition === "number") {
+        parts.push(`queue position ${state.queuePosition}`);
+    }
+    if (typeof state.etaSeconds === "number") {
+        parts.push(`up to ${Math.max(1, Math.round(state.etaSeconds / 60))}m`);
+    }
+    return parts.length > 0 ? parts.join(", ") : "waiting for a device slot";
+}
+async function waitForProvisioned(client, sessionId, { signal, onSlotHeld } = {}) {
+    const watchAbort = new AbortController();
+    let rejectOuter = null;
+    const forwardAbort = () => {
+        watchAbort.abort(signal.reason);
+        rejectOuter?.(signal.reason ?? new Error("Provisioning cancelled."));
+    };
+    signal?.addEventListener("abort", forwardAbort, { once: true });
+    let lastStatus = null;
+    let webdriverEndpoint = null;
+    let slotHeldReported = false;
+    try {
+        await new Promise((resolve, reject) => {
+            rejectOuter = reject;
+            client
+                .watchRun(sessionId, (state) => {
+                if (!state || typeof state !== "object") {
+                    return;
+                }
+                if (!slotHeldReported && SLOT_HELD_STATUSES.has(state.status)) {
+                    slotHeldReported = true;
+                    onSlotHeld?.();
+                }
+                if (state.status && state.status !== lastStatus) {
+                    lastStatus = state.status;
+                    reportCloudPhase(state.status.toLowerCase());
+                }
+                if (state.status === "PENDING") {
+                    reportCloudProgress(formatQueueMessage(state));
+                }
+                if (state.status === "PROVISIONED" && state.webdriverEndpoint) {
+                    webdriverEndpoint = state.webdriverEndpoint;
+                    watchAbort.abort();
+                    resolve();
+                    return;
+                }
+                if (state.status === "ERROR") {
+                    const message = state.error?.message || "Loadmill Cloud run failed while provisioning.";
+                    const error = new Error(message);
+                    error.code = state.error?.code;
+                    watchAbort.abort();
+                    reject(error);
+                    return;
+                }
+                if (state.status === "CANCELLED") {
+                    const error = new Error("Loadmill Cloud run was cancelled.");
+                    watchAbort.abort();
+                    reject(error);
+                }
+            }, { signal: watchAbort.signal })
+                .catch(() => { });
+            if (signal?.aborted) {
+                watchAbort.abort();
+                reject(signal.reason ?? new Error("Provisioning cancelled."));
+            }
+        });
+    }
+    finally {
+        signal?.removeEventListener("abort", forwardAbort);
+    }
+    return webdriverEndpoint;
+}
+// Number of consecutive polls with an unchanged (but still incomplete)
+// artifact list, with at least one requested kind already present, before we
+// give up early on the remaining kinds instead of burning the full budget.
+// Artifacts appear incrementally while the run is still STOPPING (unlike the
+// old terminal-only flow), so this is generous (~30s) to avoid a premature
+// partial exit just because one kind hasn't shown up yet.
+const UNCHANGED_POLL_EARLY_EXIT_LIMIT = 6;
+function artifactSignature(artifacts) {
+    return artifacts
+        .map((artifact) => `${artifact.kind}:${artifact.presignedGetUrl}`)
+        .sort()
+        .join("|");
+}
+// Retries on the server's 409 artifacts_not_ready envelope, and while any
+// requested kind is still missing from the response (DF's video upload lags
+// completion). Returns whatever is present once the budget is exhausted, or
+// early once the artifact list stops changing for UNCHANGED_POLL_EARLY_EXIT_LIMIT
+// consecutive polls while at least one requested kind is already available —
+// this avoids waiting out the full budget for a kind that will never appear
+// (e.g. a mismatched/unmapped artifact type on the server side).
+async function pollForArtifacts(client, sessionId, kinds, { budgetMs, intervalMs = ARTIFACT_POLL_INTERVAL_MS, unchangedPollLimit = UNCHANGED_POLL_EARLY_EXIT_LIMIT } = {}) {
+    const startedAt = Date.now();
+    const deadline = startedAt + budgetMs;
+    let lastArtifacts = [];
+    let lastSignature = null;
+    let unchangedCount = 0;
+    let pollNumber = 0;
+    for (;;) {
+        pollNumber += 1;
+        reportCloudProgress(`artifacts are being prepared…`);
+        try {
+            const result = await client.getArtifacts(sessionId);
+            lastArtifacts = Array.isArray(result?.artifacts) ? result.artifacts : [];
+            const presentKinds = new Set(lastArtifacts.map((artifact) => artifact.kind));
+            const missingKinds = kinds.filter((kind) => !presentKinds.has(kind));
+            timingLog(`poll #${pollNumber}: kinds=[${[...presentKinds].join(",")}] missing=[${missingKinds.join(",")}]`);
+            if (missingKinds.length === 0) {
+                return { artifacts: lastArtifacts, missingKinds: [], pollCount: pollNumber, elapsedMs: Date.now() - startedAt };
+            }
+            const signature = artifactSignature(lastArtifacts);
+            if (presentKinds.size > 0 && signature === lastSignature) {
+                unchangedCount += 1;
+            }
+            else {
+                unchangedCount = presentKinds.size > 0 ? 1 : 0;
+            }
+            lastSignature = signature;
+            if (presentKinds.size > 0 && unchangedCount >= unchangedPollLimit) {
+                return { artifacts: lastArtifacts, missingKinds, pollCount: pollNumber, elapsedMs: Date.now() - startedAt };
+            }
+        }
+        catch (error) {
+            const retryable = (error?.status === 409 && error?.code === "artifacts_not_ready") ||
+                (error?.status === 502 && error?.code === "mobile_testing_artifacts_failed");
+            if (retryable) {
+                timingLog(error.status === 409
+                    ? `poll #${pollNumber}: 409 artifacts_not_ready`
+                    : `poll #${pollNumber}: 502 mobile_testing_artifacts_failed`);
+            }
+            else {
+                throw error;
+            }
+        }
+        if (Date.now() >= deadline) {
+            const presentKinds = new Set(lastArtifacts.map((artifact) => artifact.kind));
+            return {
+                artifacts: lastArtifacts,
+                missingKinds: kinds.filter((kind) => !presentKinds.has(kind)),
+                pollCount: pollNumber,
+                elapsedMs: Date.now() - startedAt,
+            };
+        }
+        await abortableSleep(intervalMs).catch(() => { });
+    }
+}
+function formatDownloadDetail(fileName, bytesWritten, totalBytes) {
+    if (typeof totalBytes === "number" && totalBytes > 0) {
+        const percent = Math.min(100, Math.round((bytesWritten / totalBytes) * 100));
+        return `downloading ${fileName} — ${formatBytes(bytesWritten)}/${formatBytes(totalBytes)} (${percent}%)`;
+    }
+    return `downloading ${fileName} — ${formatBytes(bytesWritten)}`;
+}
+async function fetchAndDownloadArtifacts({ client, sessionId, kinds }) {
+    reportCloudPhase("artifact list");
+    const { artifacts, missingKinds, elapsedMs } = await pollForArtifacts(client, sessionId, kinds, {
+        budgetMs: ARTIFACT_POLL_BUDGET_MS,
+    });
+    reportCloudPhaseCloseText(`artifacts ready (${formatSecondsOneDecimal(elapsedMs)}s)`);
+    // Flush the "artifact list" phase's "✔ artifacts ready (...)" line now,
+    // instead of leaving it to lazily flush whenever the first download's
+    // reportCloudPhase() call happens to fire — otherwise the note below
+    // (which prints immediately, unlike a phase close) would race ahead of it.
+    reportCloudPhaseFlush();
+    // Only from this point on is "fetching"/"downloading" language accurate —
+    // everything before here was still waiting on the provider to prepare them.
+    reportCloudNote("Fetching artifacts");
+    const destDir = path.resolve(process.cwd(), "droid-cua-artifacts", sessionId);
+    const summary = await downloadArtifacts({
+        artifacts,
+        kinds,
+        destDir,
+        onNote: (message) => reportCloudNote(message),
+        onFileStart: (kind, fileName, totalBytes) => {
+            reportCloudPhase(`download ${fileName}`);
+            reportCloudProgress(formatDownloadDetail(fileName, 0, totalBytes));
+        },
+        onProgress: (kind, fileName, bytesWritten, totalBytes) => {
+            reportCloudProgress(formatDownloadDetail(fileName, bytesWritten, totalBytes));
+        },
+        onFileDone: (kind, fileName, bytesWritten, elapsedFileMs) => {
+            reportCloudPhaseCloseText(`${fileName} — ${formatBytes(bytesWritten)} (${formatSecondsOneDecimal(elapsedFileMs)}s)`);
+        },
+    });
+    if (summary.length > 0) {
+        // reportCloudPrint (not console.log) so this always closes the last
+        // file's still-open phase first — otherwise its "✔ <file> — ..." line
+        // can race behind / glue onto this summary or the live spinner.
+        reportCloudPrint(`Artifacts saved to ${destDir}`);
+    }
+    if (missingKinds.length > 0) {
+        reportCloudNote(`WARNING: artifacts not ready for: ${missingKinds.join(", ")}. Retry later with: droid-cua --cloud-session-id ${sessionId} --artifacts ${kinds.join(",")}`);
+    }
+    return { downloadedKinds: summary.map((item) => item.kind), missingKinds };
+}
+async function uploadAppIfNeeded(client, sessionId, { app, platform, signal }) {
+    const fileName = path.basename(app);
+    const sha256 = await hashFile(app);
+    reportCloudPhase("register app");
+    const registration = await client.registerApp(sessionId, { sha256, platform, fileName });
+    if (registration.presignedPutUrl) {
+        reportCloudPhase("upload app");
+        reportCloudProgress(`uploading ${fileName}...`);
+        await client.uploadBinary(registration.presignedPutUrl, app, { signal });
+    }
+    else {
+        reportCloudProgress("upload cache hit — reusing existing app upload");
+    }
+    return registration.uploadRef;
+}
+/** @type {import("../adapter").CloudProviderAdapter} */
+export const loadmillCloudAdapter = {
+    id: "loadmill-cloud",
+    displayName: "Loadmill Cloud",
+    async validateCredentials(creds) {
+        try {
+            await makeClient(creds).getDevices();
+            return { ok: true, message: "Loadmill Cloud credentials are valid." };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                message: error instanceof Error ? error.message : "Failed to validate Loadmill Cloud credentials.",
+            };
+        }
+    },
+    async getAccountInfo(creds) {
+        const { meters = [] } = await makeClient(creds).getUsage();
+        return {
+            plan: "Metered",
+            summary: meters
+                .map((meter) => {
+                const minutes = meter?.minutes ?? {};
+                return `${meter.period}: ${minutes.used}/${minutes.limit} used (${minutes.left} left)`;
+            })
+                .join("; "),
+            meters,
+        };
+    },
+    async getAvailableDevices(creds) {
+        const key = deviceCacheKey(creds);
+        const cached = deviceCacheByKey.get(key);
+        if (cached && Date.now() - cached.at < DEVICE_CACHE_TTL_MS) {
+            return cached.devices;
+        }
+        const { devices = [] } = await makeClient(creds).getDevices();
+        const mapped = devices.map(mapDevice);
+        deviceCacheByKey.set(key, { at: Date.now(), devices: mapped });
+        return mapped;
+    },
+    async uploadApp(creds, localPath) {
+        if (!activeRun) {
+            throw new Error("Loadmill Cloud uploadApp requires an active session — call prepareSession first (the dedup/hash decision is server-side and scoped to a run).");
+        }
+        const client = activeRun.client;
+        const uploadRef = await uploadAppIfNeeded(client, activeRun.sessionId, {
+            app: localPath,
+            platform: activeRun.platform,
+        });
+        return { id: uploadRef, remotePath: uploadRef };
+    },
+    async getAppStatus() {
+        throw new Error("Loadmill Cloud does not expose a client-side app status check — the server owns the upload cache.");
+    },
+    async deleteApp() {
+        throw new Error("Loadmill Cloud does not support client-initiated app deletion — the server owns the upload cache.");
+    },
+    async prepareSession(creds, opts, { signal } = {}) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error("Provisioning cancelled.");
+        }
+        const client = makeClient(creds);
+        const { platform, deviceName, osVersion, app, cloudSessionId, artifacts } = opts;
+        if (cloudSessionId) {
+            // Note: no "reconnect" phase here yet — a pure artifacts-only fetch
+            // (below) never actually reconnects to anything, so that phase is
+            // deferred until we know we're doing a genuine live reattach.
+            const state = await client.getRunState(cloudSessionId);
+            if (ARTIFACT_READY_STATUSES.has(state.status) && artifacts && artifacts.length > 0) {
+                if (state.status === "STOPPING") {
+                    reportCloudNote(`Test run is finishing up on the cloud device; artifacts will be available once it completes.`);
+                }
+                else {
+                    reportCloudNote(`Loadmill Cloud session has completed`);
+                }
+                await fetchAndDownloadArtifacts({ client, sessionId: cloudSessionId, kinds: artifacts });
+                const exitError = new Error(`Loadmill Cloud artifact fetch complete.`);
+                exitError.artifactsOnlyExit = true;
+                throw exitError;
+            }
+            if (TERMINAL_STATUSES.has(state.status)) {
+                throw new Error(`Loadmill Cloud session ${cloudSessionId} is already terminal (${state.status}). Fetch its recordings/logs instead with: droid-cua --cloud-session-id ${cloudSessionId} --artifacts all`);
+            }
+            if (!RESUMABLE_STATUSES.has(state.status) || !state.webdriverEndpoint) {
+                throw new Error(`Loadmill Cloud session ${cloudSessionId} is not yet ready to reconnect (status: ${state.status}).`);
+            }
+            const resolvedPlatform = platform;
+            if (!resolvedPlatform) {
+                throw new Error(`--platform is required to reconnect to Loadmill Cloud session ${cloudSessionId}; pass --platform android|ios.`);
+            }
+            reportCloudPhase("reconnect");
+            // Server forbids PROVISIONED->RUNNING directly, so report CONNECTED now
+            // to make the first getHubUrl()'s RUNNING transition legal on attach.
+            if (state.status === "PROVISIONED") {
+                await client.reportStatus(cloudSessionId, "CONNECTED");
+            }
+            activeRun = {
+                client,
+                sessionId: cloudSessionId,
+                webdriverEndpoint: state.webdriverEndpoint,
+                // Server rejects RUNNING->RUNNING; skip getHubUrl's report if already RUNNING.
+                hubUrlServedOnce: state.status === "RUNNING",
+                platform: resolvedPlatform,
+                deviceName: deviceName || state.deviceName,
+                slotStartedAt: null,
+                attachedAt: Date.now(),
+                artifacts: artifacts || null,
+            };
+            client.startHeartbeat(cloudSessionId);
+            return;
+        }
+        reportCloudPhase("init run");
+        const initState = await client.initRun({ platform, deviceName, osVersion });
+        const sessionId = initState.sessionId;
+        reportCloudNote(`Loadmill Cloud session ${sessionId}`);
+        // Server reaper kills runs that only heartbeat after CONNECTED, so start now.
+        client.startHeartbeat(sessionId);
+        activeRun = {
+            client,
+            sessionId,
+            webdriverEndpoint: null,
+            hubUrlServedOnce: false,
+            platform,
+            deviceName,
+            slotStartedAt: null,
+            attachedAt: Date.now(),
+            artifacts: artifacts || null,
+        };
+        let abortHandled = false;
+        const onAbort = async () => {
+            abortHandled = true;
+            try {
+                await timedStopRun(client, sessionId);
+            }
+            catch {
+                // ignore
+            }
+            finally {
+                client.stopHeartbeat();
+            }
+        };
+        try {
+            if (signal?.aborted) {
+                await onAbort();
+                throw signal.reason ?? new Error("Provisioning cancelled.");
+            }
+            signal?.addEventListener("abort", onAbort, { once: true });
+            await uploadAppIfNeeded(client, sessionId, { app, platform, signal });
+            const webdriverEndpoint = await waitForProvisioned(client, sessionId, {
+                signal,
+                onSlotHeld: () => {
+                    if (activeRun && activeRun.sessionId === sessionId && activeRun.slotStartedAt == null) {
+                        activeRun.slotStartedAt = Date.now();
+                    }
+                },
+            });
+            activeRun.webdriverEndpoint = webdriverEndpoint;
+            reportCloudPhase("report status: CONNECTED");
+            await client.reportStatus(sessionId, "CONNECTED");
+        }
+        catch (error) {
+            client.stopHeartbeat();
+            activeRun = null;
+            if (!abortHandled) {
+                await timedStopRun(client, sessionId).catch(() => { });
+            }
+            throw error;
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+        }
+    },
+    buildCapabilities(opts) {
+        const platform = opts.platform || activeRun?.platform;
+        if (!platform) {
+            throw new Error("Loadmill Cloud cannot determine the target platform for WebDriver capabilities; pass --platform android|ios.");
+        }
+        return {
+            platformName: platform,
+            "appium:automationName": platform === "ios" ? "XCUITest" : "UiAutomator2",
+            "appium:newCommandTimeout": 240,
+        };
+    },
+    getHubUrl() {
+        if (!activeRun?.webdriverEndpoint) {
+            throw new Error("Loadmill Cloud session has no webdriver endpoint yet.");
+        }
+        if (!activeRun.hubUrlServedOnce) {
+            activeRun.hubUrlServedOnce = true;
+            activeRun.client.reportStatus(activeRun.sessionId, "RUNNING").catch((error) => {
+                console.error(`[loadmill-cloud] failed to report RUNNING status: ${error.message}`);
+            });
+        }
+        return activeRun.webdriverEndpoint;
+    },
+    getAuthHeader() {
+        // Presigned hub URL carries its own auth; no header needed.
+        return "";
+    },
+    async getSessionArtifacts() {
+        return {};
+    },
+    async setSessionStatus(creds, sessionId, status) {
+        if (!activeRun || activeRun.sessionId !== sessionId) {
+            return;
+        }
+        if (status === "failed" || status === "errored") {
+            await activeRun.client.reportStatus(sessionId, "ERROR", {
+                code: "client_reported_failure",
+                message: `Execution reported status: ${status}`,
+            });
+        }
+    },
+    async releaseSession(creds, { waitForCompletion = true } = {}) {
+        if (!activeRun) {
+            return;
+        }
+        const { client, sessionId, slotStartedAt, attachedAt, artifacts } = activeRun;
+        activeRun = null;
+        try {
+            reportCloudPhase("stop run");
+            if (!waitForCompletion) {
+                try {
+                    await timedStopRun(client, sessionId, { signal: AbortSignal.timeout(TEARDOWN_STOP_BUDGET_MS) });
+                }
+                catch (error) {
+                    reportCloudNote(`WARNING: stop request failed: ${error?.message ?? error}`);
+                }
+                reportCloudProgress("session stop requested");
+                return;
+            }
+            await timedStopRun(client, sessionId);
+            if (artifacts && artifacts.length > 0) {
+                try {
+                    await fetchAndDownloadArtifacts({ client, sessionId, kinds: artifacts });
+                }
+                catch (error) {
+                    reportCloudNote(`WARNING: artifact fetch failed: ${error.message}`);
+                }
+            }
+        }
+        finally {
+            client.stopHeartbeat();
+        }
+    },
+    releaseActiveSession() {
+        if (!activeRun) {
+            return Promise.resolve();
+        }
+        const { client, sessionId } = activeRun;
+        activeRun = null;
+        try {
+            client.stopHeartbeat();
+        }
+        catch {
+            // ignore
+        }
+        return timedStopRun(client, sessionId, { signal: AbortSignal.timeout(TEARDOWN_STOP_BUDGET_MS) }).catch(() => { });
+    },
+};