@loadmill/droid-cua 2.24.0 → 2.26.0

package/build/src/device/cloud/loadmill-cloud/artifact-downloader.js

@@ -0,0 +1,191 @@
+import path from "node:path";
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { isTimingEnabled, timingLog } from "./timing.js";
+// Mirrors the server-side caps: per-artifact 1 GiB (video/deviceLog/appiumLog),
+// 4 GiB cumulative across a single download batch.
+export const ARTIFACT_KINDS = ["video", "deviceLog", "appiumLog"];
+export const PER_ARTIFACT_CAP_BYTES = 1 * 1024 * 1024 * 1024;
+export const CUMULATIVE_CAP_BYTES = 4 * 1024 * 1024 * 1024;
+export const DOWNLOAD_TIMEOUT_MS = 10 * 60 * 1000;
+const KIND_DEFAULT_FILENAMES = {
+    video: "video.mp4",
+    deviceLog: "device.log",
+    appiumLog: "appium.log",
+};
+function normalizeKinds(kinds) {
+    if (kinds == null || kinds === "all") {
+        return [...ARTIFACT_KINDS];
+    }
+    if (Array.isArray(kinds)) {
+        return kinds;
+    }
+    return [kinds];
+}
+function deriveFileName(kind, url) {
+    const defaultName = KIND_DEFAULT_FILENAMES[kind] || `${kind}.bin`;
+    try {
+        const parsed = new URL(url);
+        const base = path.basename(parsed.pathname);
+        const ext = path.extname(base);
+        // Allows extensions like ".logcat" (6 chars) — DF's device-log artifact
+        // URLs use that extension and must not be forced to the ".log" default.
+        if (/^\.[a-zA-Z0-9]{1,8}$/.test(ext)) {
+            const stem = defaultName.includes(".") ? defaultName.slice(0, defaultName.lastIndexOf(".")) : defaultName;
+            return `${stem}${ext}`;
+        }
+    }
+    catch {
+        // Not a parseable URL — fall back to the default name below.
+    }
+    return defaultName;
+}
+// Truncates the stream in-place at `cap` bytes: chunks past the cap are
+// dropped (not pushed downstream), so the write stream stops growing while
+// upstream reads still drain to completion. Also fires an optional
+// `onProgress(bytesWritten)` callback, throttled to roughly `throttleMs`
+// (always fired on the first chunk and on the final flush), for CLI
+// per-file download progress.
+class CappingTransform extends Transform {
+    constructor({ cap, onCapped, onProgress, throttleMs = 100 }) {
+        super();
+        this.cap = cap;
+        this.written = 0;
+        this.capped = false;
+        this.onCapped = onCapped;
+        this.onProgress = onProgress;
+        this.throttleMs = throttleMs;
+        this.lastReportAt = 0;
+    }
+    _reportProgress(force = false) {
+        if (!this.onProgress) {
+            return;
+        }
+        const now = Date.now();
+        if (force || this.lastReportAt === 0 || now - this.lastReportAt >= this.throttleMs) {
+            this.lastReportAt = now;
+            this.onProgress(this.written);
+        }
+    }
+    _transform(chunk, _encoding, callback) {
+        if (this.capped) {
+            callback();
+            return;
+        }
+        const remaining = this.cap - this.written;
+        if (chunk.length <= remaining) {
+            this.written += chunk.length;
+            this._reportProgress();
+            callback(null, chunk);
+            return;
+        }
+        const truncatedChunk = chunk.subarray(0, Math.max(0, remaining));
+        this.written += truncatedChunk.length;
+        this.capped = true;
+        this.onCapped?.();
+        this._reportProgress(true);
+        callback(null, truncatedChunk);
+    }
+    _flush(callback) {
+        this._reportProgress(true);
+        callback();
+    }
+}
+/**
+ * Streams the requested artifact kinds to destDir. Never buffers a whole
+ * file in memory. Returns a summary of what was written.
+ *
+ * @returns {Promise<Array<{ kind: string, filePath: string, bytesWritten: number, truncated: boolean }>>}
+ */
+export async function downloadArtifacts({ artifacts, kinds, destDir, onNote, 
+// Fires (kind, fileName, bytesWritten, totalBytes|null) roughly every 100ms
+// while a file streams to disk, plus once at start (0 bytes) and once at
+// completion. totalBytes is null when the server didn't send Content-Length.
+onProgress, 
+// Optional bookkeeping hooks around a single file's download, so a caller
+// (e.g. the CLI status line) can open/close a "step" per file.
+onFileStart, onFileDone, 
+// Test-only overrides — production callers rely on the exported defaults.
+perArtifactCapBytes = PER_ARTIFACT_CAP_BYTES, cumulativeCapBytes = CUMULATIVE_CAP_BYTES, downloadTimeoutMs = DOWNLOAD_TIMEOUT_MS, } = {}) {
+    const requestedKinds = new Set(normalizeKinds(kinds));
+    const list = Array.isArray(artifacts) ? artifacts : [];
+    const filtered = list.filter((artifact) => artifact && requestedKinds.has(artifact.kind));
+    if (filtered.length === 0) {
+        return [];
+    }
+    await mkdir(destDir, { recursive: true });
+    const summary = [];
+    let cumulativeBytes = 0;
+    for (const artifact of filtered) {
+        if (cumulativeBytes >= cumulativeCapBytes) {
+            onNote?.(`WARNING: ${artifact.kind} skipped — cumulative artifact cap (${cumulativeCapBytes} bytes) reached`);
+            continue;
+        }
+        const perArtifactCap = Math.min(perArtifactCapBytes, cumulativeCapBytes - cumulativeBytes);
+        if (typeof artifact.bytes === "number" && artifact.bytes > perArtifactCap) {
+            onNote?.(`WARNING: ${artifact.kind} is ${artifact.bytes} bytes, exceeds the ${perArtifactCap} byte cap and will be truncated`);
+        }
+        const fileName = deriveFileName(artifact.kind, artifact.presignedGetUrl);
+        const filePath = path.join(destDir, fileName);
+        const downloadStartedAt = Date.now();
+        timingLog(`download start: kind=${artifact.kind} url=${artifact.presignedGetUrl}`);
+        const controller = new AbortController();
+        const deadline = setTimeout(() => controller.abort(new Error(`download of ${artifact.kind} timed out after ${downloadTimeoutMs}ms`)), downloadTimeoutMs);
+        let response;
+        try {
+            response = await fetch(artifact.presignedGetUrl, { signal: controller.signal });
+        }
+        catch (error) {
+            clearTimeout(deadline);
+            onNote?.(`WARNING: failed to download ${artifact.kind} (${error?.message ?? error})`);
+            continue;
+        }
+        if (!response.ok || !response.body) {
+            clearTimeout(deadline);
+            onNote?.(`WARNING: failed to download ${artifact.kind} (HTTP ${response.status})`);
+            continue;
+        }
+        const lastModified = response.headers?.get("last-modified") ?? null;
+        const contentLength = response.headers?.get("content-length") ?? null;
+        const totalBytes = contentLength != null && contentLength !== "" ? Number(contentLength) : null;
+        timingLog(`download headers: kind=${artifact.kind} Last-Modified=${lastModified ?? "null"} Content-Length=${contentLength ?? "null"}`);
+        onFileStart?.(artifact.kind, fileName, totalBytes);
+        onProgress?.(artifact.kind, fileName, 0, totalBytes);
+        let truncated = false;
+        const capper = new CappingTransform({
+            cap: perArtifactCap,
+            onCapped: () => {
+                truncated = true;
+            },
+            onProgress: onProgress ? (bytesWritten) => onProgress(artifact.kind, fileName, bytesWritten, totalBytes) : undefined,
+        });
+        try {
+            await pipeline(Readable.fromWeb(response.body), capper, createWriteStream(filePath), {
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            onNote?.(`WARNING: failed to download ${artifact.kind} (${error?.message ?? error})`);
+            continue;
+        }
+        finally {
+            clearTimeout(deadline);
+        }
+        onFileDone?.(artifact.kind, fileName, capper.written, Date.now() - downloadStartedAt, truncated);
+        if (truncated) {
+            onNote?.(`WARNING: ${artifact.kind} truncated at ${capper.written} bytes (cap)`);
+        }
+        timingLog(`download complete: kind=${artifact.kind} bytes=${capper.written} durationMs=${Date.now() - downloadStartedAt}`);
+        cumulativeBytes += capper.written;
+        summary.push({ kind: artifact.kind, filePath, bytesWritten: capper.written, truncated, lastModified });
+    }
+    if (isTimingEnabled() && summary.length > 0) {
+        const table = summary
+            .map((item) => `${item.kind} → ${item.lastModified ?? "null"} → ${item.bytesWritten}`)
+            .join(" | ");
+        timingLog(`artifact summary (kind → lastModified → bytes): ${table}`);
+    }
+    return summary;
+}

package/build/src/device/cloud/loadmill-cloud/control-plane-client.js

@@ -0,0 +1,423 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+const DEFAULT_BASE_URL = "https://app.loadmill.com";
+const MOBILE_TESTING_PATH = "/mobile-testing-cloud/v1";
+const LOADMILL_CLIENT_HEADER_VALUE = "cli";
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+// The binary PUT carries the actual app file (tens to low-hundreds of MB) and needs a
+// much larger budget than the small JSON control-plane calls — 30s isn't enough time
+// for a real transfer even on a healthy connection.
+const DEFAULT_UPLOAD_TIMEOUT_MS = 180_000;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const POLL_FALLBACK_INTERVAL_MS = 3_000;
+const SSE_RETRY_INTERVAL_MS = 5_000;
+// Server sends a `: ping` keepalive every 25s; treat total silence this long as a wedged connection.
+const SSE_IDLE_TIMEOUT_MS = 60_000;
+// This control plane mounts at /mobile-testing-cloud/v1, not under /api — do not append /api.
+function normalizeApiBaseUrl(rawBaseUrl) {
+    const candidate = (rawBaseUrl || DEFAULT_BASE_URL).trim();
+    if (!candidate) {
+        return DEFAULT_BASE_URL;
+    }
+    try {
+        const parsed = new URL(candidate);
+        parsed.pathname = parsed.pathname
+            .replace(/\/+$/, "")
+            .replace(/\/api$/, "")
+            .replace(/\/llm\/v1$/, "")
+            .replace(/\/llm$/, "");
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString().replace(/\/$/, "");
+    }
+    catch {
+        return DEFAULT_BASE_URL;
+    }
+}
+function requestTimeoutError(label, timeoutMs) {
+    const error = new Error(`Loadmill Cloud API request timed out after ${timeoutMs}ms: ${label}`);
+    error.code = "request_timeout";
+    return error;
+}
+function requestAbortedError(label) {
+    const error = new Error(`Loadmill Cloud API request aborted: ${label}`);
+    error.code = "request_aborted";
+    return error;
+}
+async function buildResponseError(response) {
+    let payload = null;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        // non-JSON error body
+    }
+    const envelope = (payload?.error && typeof payload.error === "object" && payload.error) ||
+        (payload?.payload && typeof payload.payload === "object" && payload.payload) ||
+        payload;
+    const message = (envelope && typeof envelope.message === "string" && envelope.message) ||
+        (payload && typeof payload.err === "string" && payload.err) ||
+        `Loadmill Cloud API error (${response.status})`;
+    const error = new Error(message);
+    error.status = response.status;
+    error.code = envelope?.code;
+    error.type = envelope?.type;
+    error.param = envelope?.param;
+    return error;
+}
+export class LoadmillCloudControlPlaneClient {
+    /**
+     * @param {{ bearerToken: string, baseUrl?: string, requestTimeoutMs?: number, uploadTimeoutMs?: number }} [options]
+     */
+    constructor({ bearerToken, baseUrl, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, uploadTimeoutMs = DEFAULT_UPLOAD_TIMEOUT_MS, } = {}) {
+        if (!bearerToken || typeof bearerToken !== "string" || !bearerToken.trim()) {
+            throw new Error("LoadmillCloudControlPlaneClient requires a bearerToken.");
+        }
+        this.bearerToken = bearerToken.trim();
+        this.baseUrl = normalizeApiBaseUrl(baseUrl);
+        this.requestTimeoutMs = requestTimeoutMs;
+        this.uploadTimeoutMs = uploadTimeoutMs;
+        this._heartbeatTimer = null;
+    }
+    _url(pathSuffix) {
+        return `${this.baseUrl}${MOBILE_TESTING_PATH}${pathSuffix}`;
+    }
+    _authHeaders(extra = {}) {
+        return {
+            Authorization: `Bearer ${this.bearerToken}`,
+            "X-Loadmill-Client": LOADMILL_CLIENT_HEADER_VALUE,
+            ...extra,
+        };
+    }
+    async _request(pathSuffix, { method = "GET", headers = {}, body, signal: callerSignal } = {}) {
+        const timeoutSignal = AbortSignal.timeout(this.requestTimeoutMs);
+        const signal = callerSignal ? AbortSignal.any([timeoutSignal, callerSignal]) : timeoutSignal;
+        let response;
+        try {
+            response = await fetch(this._url(pathSuffix), {
+                method,
+                signal,
+                headers: {
+                    ...this._authHeaders(headers),
+                    ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+        }
+        catch (error) {
+            if (timeoutSignal.aborted) {
+                throw requestTimeoutError(pathSuffix, this.requestTimeoutMs);
+            }
+            if (callerSignal?.aborted) {
+                throw requestAbortedError(pathSuffix);
+            }
+            throw error;
+        }
+        if (!response.ok) {
+            throw await buildResponseError(response);
+        }
+        if (response.status === 204) {
+            return null;
+        }
+        return response.json();
+    }
+    async getDevices({ platform } = {}) {
+        const query = platform ? `?platform=${encodeURIComponent(platform)}` : "";
+        return this._request(`/devices${query}`);
+    }
+    async getUsage() {
+        return this._request("/usage");
+    }
+    async initRun({ platform, deviceName, osVersion }) {
+        return this._request("/runs", {
+            method: "POST",
+            headers: { "x-loadmill-request-id": randomUUID() },
+            body: { platform, deviceName, osVersion },
+        });
+    }
+    async registerApp(sessionId, { sha256, platform, fileName }) {
+        return this._request(`/runs/${encodeURIComponent(sessionId)}/app`, {
+            method: "POST",
+            body: { sha256, platform, fileName },
+        });
+    }
+    async uploadBinary(presignedPutUrl, filePath, { signal: callerSignal } = {}) {
+        const timeoutSignal = AbortSignal.timeout(this.uploadTimeoutMs);
+        const signal = callerSignal ? AbortSignal.any([timeoutSignal, callerSignal]) : timeoutSignal;
+        const label = "upload";
+        let response;
+        try {
+            // Buffer the whole file: undici streams bodies as chunked transfer, which S3 presigned PUTs reject.
+            // Content-Type must match the value the presigned URL signed, or S3 returns 403 SignatureDoesNotMatch.
+            response = await fetch(presignedPutUrl, {
+                method: "PUT",
+                signal,
+                headers: { "Content-Type": "application/octet-stream" },
+                body: await readFile(filePath),
+            });
+        }
+        catch (error) {
+            if (timeoutSignal.aborted) {
+                throw requestTimeoutError(label, this.uploadTimeoutMs);
+            }
+            if (callerSignal?.aborted) {
+                throw requestAbortedError(label);
+            }
+            throw error;
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            throw new Error(`Loadmill Cloud app upload failed (HTTP ${response.status}): ${text}`);
+        }
+    }
+    async stopRun(sessionId, { signal } = {}) {
+        return this._request(`/runs/${encodeURIComponent(sessionId)}/stop`, { method: "POST", signal });
+    }
+    async heartbeat(sessionId, { signal } = {}) {
+        return this._request(`/runs/${encodeURIComponent(sessionId)}/heartbeat`, { method: "POST", signal });
+    }
+    async getRunState(sessionId) {
+        return this._request(`/runs/${encodeURIComponent(sessionId)}`);
+    }
+    async getArtifacts(sessionId) {
+        return this._request(`/runs/${encodeURIComponent(sessionId)}/artifacts`);
+    }
+    async reportStatus(sessionId, state, error) {
+        return this._request(`/runs/${encodeURIComponent(sessionId)}/status`, {
+            method: "POST",
+            body: error ? { state, error } : { state },
+        });
+    }
+    // Server reaps at 90s of missed heartbeats, so individual failures are swallowed.
+    startHeartbeat(sessionId) {
+        this.stopHeartbeat();
+        this._heartbeatTimer = setInterval(() => {
+            this.heartbeat(sessionId).catch((error) => {
+                console.error(`[loadmill-cloud] heartbeat failed for session ${sessionId}: ${error.message}`);
+            });
+        }, HEARTBEAT_INTERVAL_MS);
+        if (typeof this._heartbeatTimer.unref === "function") {
+            this._heartbeatTimer.unref();
+        }
+    }
+    stopHeartbeat() {
+        if (this._heartbeatTimer) {
+            clearInterval(this._heartbeatTimer);
+            this._heartbeatTimer = null;
+        }
+    }
+    async watchRun(sessionId, onState, { signal } = {}) {
+        let stopped = false;
+        const onAbort = () => {
+            stopped = true;
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const sseState = { healthy: false, target: new EventTarget() };
+        const setSseHealthy = (value) => {
+            if (sseState.healthy === value) {
+                return;
+            }
+            sseState.healthy = value;
+            sseState.target.dispatchEvent(new Event("change"));
+        };
+        const pollLoop = (async () => {
+            while (!stopped && !signal?.aborted) {
+                if (sseState.healthy) {
+                    const waiter = this._waitForSseChange(sseState, signal);
+                    await waiter.promise;
+                    waiter.cancel();
+                    continue;
+                }
+                try {
+                    const state = await this.getRunState(sessionId);
+                    if (stopped || signal?.aborted)
+                        break;
+                    onState(state);
+                }
+                catch (error) {
+                    console.error(`[loadmill-cloud] poll fallback failed for session ${sessionId}: ${error.message}`);
+                }
+                if (sseState.healthy) {
+                    continue;
+                }
+                // waiter.cancel() is required: the losing side of the race would otherwise leak a listener per poll iteration.
+                const waiter = this._waitForSseChange(sseState, signal);
+                await Promise.race([this._sleep(POLL_FALLBACK_INTERVAL_MS, signal), waiter.promise]);
+                waiter.cancel();
+            }
+        })();
+        const sseLoop = (async () => {
+            while (!stopped && !signal?.aborted) {
+                try {
+                    await this._consumeSse(sessionId, onState, signal, setSseHealthy);
+                }
+                catch (error) {
+                    if (this._isAbortError(error, signal)) {
+                        break;
+                    }
+                    console.error(`[loadmill-cloud] SSE stream failed for session ${sessionId}: ${error.message}`);
+                }
+                finally {
+                    setSseHealthy(false);
+                }
+                if (stopped || signal?.aborted)
+                    break;
+                await this._sleep(SSE_RETRY_INTERVAL_MS, signal);
+            }
+        })();
+        await Promise.all([pollLoop, sseLoop]).catch(() => { });
+    }
+    _waitForSseChange(sseState, signal) {
+        if (signal?.aborted) {
+            return { promise: Promise.resolve(), cancel: () => { } };
+        }
+        let resolvePromise;
+        const promise = new Promise((resolve) => {
+            resolvePromise = resolve;
+        });
+        const cleanup = () => {
+            sseState.target.removeEventListener("change", onChange);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onChange = () => {
+            cleanup();
+            resolvePromise();
+        };
+        const onAbort = () => {
+            cleanup();
+            resolvePromise();
+        };
+        sseState.target.addEventListener("change", onChange, { once: true });
+        signal?.addEventListener("abort", onAbort, { once: true });
+        return { promise, cancel: cleanup };
+    }
+    _isAbortError(error, signal) {
+        return Boolean(signal?.aborted ||
+            error?.name === "AbortError" ||
+            /aborted/i.test(error?.message || ""));
+    }
+    _sleep(ms, signal) {
+        if (signal?.aborted)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    async _consumeSse(sessionId, onState, signal, setSseHealthy) {
+        const response = await fetch(this._url(`/runs/${encodeURIComponent(sessionId)}/events`), {
+            method: "GET",
+            signal,
+            headers: this._authHeaders({ Accept: "text/event-stream" }),
+        });
+        if (!response.ok) {
+            throw await buildResponseError(response);
+        }
+        if (!response.body) {
+            throw new Error("SSE response had no readable body.");
+        }
+        setSseHealthy?.(true);
+        const idleController = new AbortController();
+        const onOuterAbort = () => idleController.abort(signal?.reason);
+        if (signal?.aborted) {
+            idleController.abort(signal.reason);
+        }
+        else {
+            signal?.addEventListener("abort", onOuterAbort, { once: true });
+        }
+        let idleTimer = null;
+        const armIdleTimer = () => {
+            clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                setSseHealthy?.(false);
+                idleController.abort(new Error(`SSE stream idle for ${SSE_IDLE_TIMEOUT_MS}ms (no bytes received) — reconnecting.`));
+            }, SSE_IDLE_TIMEOUT_MS);
+            if (typeof idleTimer.unref === "function") {
+                idleTimer.unref();
+            }
+        };
+        armIdleTimer();
+        try {
+            await parseSseStream(response.body, onState, {
+                signal: idleController.signal,
+                onActivity: armIdleTimer,
+            });
+        }
+        finally {
+            clearTimeout(idleTimer);
+            signal?.removeEventListener("abort", onOuterAbort);
+        }
+    }
+}
+// An abort signal cannot interrupt an in-flight reader.read(), so race the read against it.
+function readOrAbort(reader, signal) {
+    if (!signal) {
+        return reader.read();
+    }
+    if (signal.aborted) {
+        return Promise.reject(signal.reason ?? new Error("SSE read aborted."));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reject(signal.reason ?? new Error("SSE read aborted."));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        reader.read().then((result) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(result);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+export async function parseSseStream(body, onState, { signal, onActivity } = {}) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    try {
+        for (;;) {
+            const { done, value } = await readOrAbort(reader, signal);
+            if (done)
+                break;
+            onActivity?.();
+            buffer += decoder.decode(value, { stream: true });
+            let match;
+            while ((match = buffer.match(/\r?\n\r?\n/)) !== null) {
+                const rawEvent = buffer.slice(0, match.index);
+                buffer = buffer.slice(match.index + match[0].length);
+                emitSseEvent(rawEvent, onState);
+            }
+        }
+        if (buffer.trim()) {
+            emitSseEvent(buffer, onState);
+        }
+    }
+    finally {
+        await reader.cancel?.().catch(() => { });
+    }
+}
+function emitSseEvent(rawEvent, onState) {
+    const dataLines = rawEvent
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice("data:".length).trimStart().replace(/\r$/, ""));
+    if (dataLines.length === 0) {
+        return;
+    }
+    const payload = dataLines.join("\n");
+    try {
+        const state = JSON.parse(payload);
+        onState(state);
+    }
+    catch (error) {
+        console.error(`[loadmill-cloud] failed to parse SSE event payload: ${error.message}`);
+    }
+}

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

@@ -0,0 +1,16 @@
+export const LOADMILL_CLOUD_USAGE_LIMIT_ERROR_CODES = new Set([
+    "mobile_testing_day_minute_quota_exceeded",
+    "mobile_testing_week_minute_quota_exceeded",
+    "mobile_testing_fixed_budget_minute_quota_exceeded",
+    "mobile_testing_concurrency_exceeded",
+    "mobile_testing_rate_limit_exceeded",
+]);
+export function isLoadmillCloudUsageLimitError(err) {
+    if (!err || typeof err !== "object") {
+        return false;
+    }
+    if (typeof err.code === "string" && LOADMILL_CLOUD_USAGE_LIMIT_ERROR_CODES.has(err.code)) {
+        return true;
+    }
+    return err.status === 429 && err.type === "rate_limit_error";
+}

package/build/src/device/cloud/loadmill-cloud/format-bytes.js

@@ -0,0 +1,18 @@
+// Human-readable byte sizes for CLI progress/summary output. One decimal,
+// KB/MB/GB — matches the artifact-download progress UX spec.
+export function formatBytes(bytes) {
+    const value = Number(bytes) || 0;
+    if (value < 1024) {
+        return `${value} B`;
+    }
+    const kb = value / 1024;
+    if (kb < 1024) {
+        return `${kb.toFixed(1)} KB`;
+    }
+    const mb = kb / 1024;
+    if (mb < 1024) {
+        return `${mb.toFixed(1)} MB`;
+    }
+    const gb = mb / 1024;
+    return `${gb.toFixed(1)} GB`;
+}

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

@@ -0,0 +1,14 @@
+// Opt-in timing instrumentation for decomposing the post-stop artifact wait.
+// Zero-cost/zero-output unless LOADMILL_CLOUD_TIMING=1 is set in the
+// environment: everything writes to stderr so it never pollutes stdout
+// output the CLI relies on.
+const ENV_VAR = "LOADMILL_CLOUD_TIMING";
+export function isTimingEnabled() {
+    return process.env[ENV_VAR] === "1";
+}
+export function timingLog(message) {
+    if (!isTimingEnabled()) {
+        return;
+    }
+    process.stderr.write(`[loadmill-cloud-timing] ${new Date().toISOString()} ${message}\n`);
+}