@devicecloud.dev/dcd 5.7.1 → 5.8.0-beta.2

package/dist/commands/cloud.d.ts

@@ -129,6 +129,11 @@ export declare const cloudCommand: import("citty").CommandDef<{
         readonly alias: ["maestroVersion"];
         readonly description: "Maestro version to run your flow against. Use \"latest\" for the most recent version. See https://docs.devicecloud.dev/configuration/maestro-versions for supported versions.";
     };
+    readonly priority: {
+        readonly type: "string";
+        readonly default: "normal";
+        readonly description: "Run priority within your organization (options: low, normal, high). Reorders only your own queued runs across your concurrency pool, for every flow in this upload; it never moves them ahead of other customers. Runs queued longer than 6 hours are promoted first, so low runs are never starved. Retries keep the same priority.";
+    };
     readonly retry: {
         readonly type: "string";
         readonly description: "Automatically retry the run up to the number of times specified (same as pressing retry in the UI) - this is free of charge";

package/dist/commands/cloud.js

@@ -42,6 +42,7 @@ const DOWNLOAD_OPTIONS = ['ALL', 'FAILED'];
 const REPORT_OPTIONS = ['allure', 'html', 'html-detailed', 'junit'];
 const ORIENTATION_OPTIONS = ['0', '90'];
 const RUNNER_TYPE_OPTIONS = ['default', 'm4', 'm1', 'gpu1', 'cpu1'];
+const PRIORITY_OPTIONS = ['low', 'normal', 'high'];
 const RENDER_ENGINE_OPTIONS = ['lavapipe', 'swiftshader'];
 /**
  * Primary CLI command for executing tests on DeviceCloud.
@@ -162,6 +163,7 @@ export const cloudCommand = defineCommand({
             const moropoApiKey = args['moropo-v1-api-key'];
             const name = args.name;
             const orientation = validateEnum(args.orientation, ORIENTATION_OPTIONS, 'orientation');
+            const priority = validateEnum(args.priority, PRIORITY_OPTIONS, 'priority') ?? 'normal';
             let quiet = Boolean(args.quiet);
             const report = validateEnum(args.report, REPORT_OPTIONS, 'report');
             let retry = parseIntFlag(args.retry, 'retry');
@@ -600,6 +602,7 @@ export const cloudCommand = defineCommand({
                 metadata: mergedMetadata,
                 name,
                 orientation,
+                priority,
                 raw: [],
                 report,
                 retry,

package/dist/config/flags/execution.flags.d.ts

@@ -33,6 +33,11 @@ export declare const executionFlags: {
         readonly alias: ["maestroVersion"];
         readonly description: "Maestro version to run your flow against. Use \"latest\" for the most recent version. See https://docs.devicecloud.dev/configuration/maestro-versions for supported versions.";
     };
+    readonly priority: {
+        readonly type: "string";
+        readonly default: "normal";
+        readonly description: "Run priority within your organization (options: low, normal, high). Reorders only your own queued runs across your concurrency pool, for every flow in this upload; it never moves them ahead of other customers. Runs queued longer than 6 hours are promoted first, so low runs are never starved. Retries keep the same priority.";
+    };
     readonly retry: {
         readonly type: "string";
         readonly description: "Automatically retry the run up to the number of times specified (same as pressing retry in the UI) - this is free of charge";

package/dist/config/flags/execution.flags.js

@@ -33,6 +33,11 @@ export const executionFlags = {
         alias: ['maestroVersion'],
         description: 'Maestro version to run your flow against. Use "latest" for the most recent version. See https://docs.devicecloud.dev/configuration/maestro-versions for supported versions.',
     },
+    priority: {
+        type: 'string',
+        default: 'normal',
+        description: 'Run priority within your organization (options: low, normal, high). Reorders only your own queued runs across your concurrency pool, for every flow in this upload; it never moves them ahead of other customers. Runs queued longer than 6 hours are promoted first, so low runs are never starved. Retries keep the same priority.',
+    },
     retry: {
         type: 'string',
         description: 'Automatically retry the run up to the number of times specified (same as pressing retry in the UI) - this is free of charge',

package/dist/constants.d.ts

@@ -115,6 +115,11 @@ export declare const flags: {
         readonly alias: ["maestroVersion"];
         readonly description: "Maestro version to run your flow against. Use \"latest\" for the most recent version. See https://docs.devicecloud.dev/configuration/maestro-versions for supported versions.";
     };
+    readonly priority: {
+        readonly type: "string";
+        readonly default: "normal";
+        readonly description: "Run priority within your organization (options: low, normal, high). Reorders only your own queued runs across your concurrency pool, for every flow in this upload; it never moves them ahead of other customers. Runs queued longer than 6 hours are promoted first, so low runs are never starved. Retries keep the same priority.";
+    };
     readonly retry: {
         readonly type: "string";
         readonly description: "Automatically retry the run up to the number of times specified (same as pressing retry in the UI) - this is free of charge";

package/dist/gateways/api-gateway.d.ts

@@ -1,7 +1,7 @@
 import { TAppMetadata } from '../types.js';
 import type { AuthContext } from '../types/domain/auth.types.js';
 import type { LiveCommandStatus, LiveExecResult, LiveSession, LiveSessionSummary } from '../types/domain/live.types.js';
-import { components } from '../types/generated/schema.types.js';
+import { components, paths } from '../types/generated/schema.types.js';
 /**
  * Error thrown for non-OK API responses, carrying the HTTP status so callers
  * can branch on auth failures etc. without string matching.
@@ -10,6 +10,17 @@ export declare class ApiError extends Error {
     status: number;
     constructor(message: string, status: number);
 }
+type ResultsResponse = paths['/results/{uploadId}']['get']['responses']['200']['content']['application/json'];
+/**
+ * The last results body a poll loop received and the ETag it came with, so
+ * the next poll can revalidate with `If-None-Match` and get an empty 304 back
+ * when nothing changed. Create one per poll loop; `getResultsForUpload` fills
+ * and clears it.
+ */
+export interface ResultsPollCache {
+    body?: ResultsResponse;
+    etag?: string;
+}
 export declare const ApiGateway: {
     /**
      * Enhances generic "fetch failed" errors with more specific diagnostic information
@@ -98,7 +109,23 @@ export declare const ApiGateway: {
         token?: string;
     }>;
     finishLargeFile(baseUrl: string, auth: AuthContext, fileId: string, partSha1Array: string[]): Promise<unknown>;
-    getResultsForUpload(baseUrl: string, auth: AuthContext, uploadId: string): Promise<{
+    /**
+     * Fetch the result rows for an upload, for the `dcd cloud` poll loop.
+     *
+     * Asks for `?view=summary`, which leaves out `result_files` and the rest of
+     * the columns the CLI never reads. An API that predates the view ignores
+     * the parameter and returns the full rows, a superset, so this works
+     * against either.
+     *
+     * With a `cache`, a repeat poll revalidates with `If-None-Match` and a 304
+     * hands back the cached body.
+     * @param baseUrl API base URL
+     * @param auth AuthContext carrying request headers
+     * @param uploadId Upload ID to fetch results for
+     * @param cache Optional per-poll-loop cache, filled and cleared here
+     * @returns The results response body
+     */
+    getResultsForUpload(baseUrl: string, auth: AuthContext, uploadId: string, cache?: ResultsPollCache): Promise<{
         statusCode?: number;
         results?: components["schemas"]["TResultResponse"][];
     }>;
@@ -209,3 +236,4 @@ export declare const ApiGateway: {
     stopLiveSession(baseUrl: string, auth: AuthContext, sessionName: string): Promise<void>;
     getLiveSession(baseUrl: string, auth: AuthContext, sessionName: string): Promise<LiveSession>;
 };
+export {};

package/dist/gateways/api-gateway.js

@@ -347,20 +347,73 @@ export const ApiGateway = {
             throw error;
         }
     },
-    async getResultsForUpload(baseUrl, auth, uploadId) {
+    /**
+     * Fetch the result rows for an upload, for the `dcd cloud` poll loop.
+     *
+     * Asks for `?view=summary`, which leaves out `result_files` and the rest of
+     * the columns the CLI never reads. An API that predates the view ignores
+     * the parameter and returns the full rows, a superset, so this works
+     * against either.
+     *
+     * With a `cache`, a repeat poll revalidates with `If-None-Match` and a 304
+     * hands back the cached body.
+     * @param baseUrl API base URL
+     * @param auth AuthContext carrying request headers
+     * @param uploadId Upload ID to fetch results for
+     * @param cache Optional per-poll-loop cache, filled and cleared here
+     * @returns The results response body
+     */
+    async getResultsForUpload(baseUrl, auth, uploadId, cache) {
         // TODO: merge with getUploadStatus
+        const url = `${baseUrl}/results/${uploadId}?view=summary`;
         try {
-            const res = await fetch(`${baseUrl}/results/${uploadId}`, {
-                headers: { ...auth.headers },
-            });
+            const headers = { ...auth.headers };
+            if (cache?.body && cache.etag) {
+                headers['if-none-match'] = cache.etag;
+                // Per the Fetch spec, undici appends `Cache-Control: no-cache` to any
+                // request that carries a conditional header and no Cache-Control of
+                // its own, and Express's `fresh` never answers 304 to a no-cache
+                // request. So every poll would get a full 200. max-age=0 still asks
+                // for revalidation, and keeps undici from adding no-cache.
+                headers['cache-control'] = 'max-age=0';
+            }
+            const res = await fetch(url, { headers });
+            // Before the `!res.ok` check, since a 304 is not `ok`.
+            if (res.status === 304) {
+                if (cache?.body) {
+                    return cache.body;
+                }
+                // We sent no If-None-Match, so there is nothing to reuse. Start over
+                // with an unconditional request on the next poll.
+                if (cache) {
+                    delete cache.body;
+                    delete cache.etag;
+                }
+                throw new Error('Failed to get results: API returned 304 Not Modified to an unconditional request');
+            }
             if (!res.ok) {
                 await this.handleApiError(res, 'Failed to get results');
             }
-            return await parseJsonResponse(res, 'Failed to get results');
+            const body = await parseJsonResponse(res, 'Failed to get results');
+            if (cache) {
+                // Only pin a real result set. The API reports some errors as a 200
+                // with a `{ statusCode, message }` envelope, and an empty set is
+                // rejected by the poll loop; caching either would replay it on 304.
+                const etag = res.headers.get('etag');
+                if (etag && Array.isArray(body.results) && body.results.length > 0) {
+                    cache.body = body;
+                    cache.etag = etag;
+                }
+                else {
+                    delete cache.body;
+                    delete cache.etag;
+                }
+            }
+            return body;
         }
         catch (error) {
             if (error instanceof TypeError && error.message === 'fetch failed') {
-                throw this.enhanceFetchError(error, `${baseUrl}/results/${uploadId}`);
+                throw this.enhanceFetchError(error, url);
             }
             throw error;
         }

package/dist/mcp/tools/run-cloud-test.js

@@ -70,6 +70,10 @@ export function registerRunCloudTest(server) {
                 .enum(['default', 'm4', 'm1', 'gpu1', 'cpu1'])
                 .optional()
                 .describe('Runner type (default "default"). gpu1 is deprecated and will be removed on 9 November 2026; prefer cpu1.'),
+            priority: z
+                .enum(['low', 'normal', 'high'])
+                .optional()
+                .describe('Run priority within the organization (default "normal"). Reorders only the queued runs of this organization, for every flow in this upload; it never moves them ahead of other customers. Runs queued over 6 hours are promoted first, so low runs are never starved.'),
             configFile: z.string().optional().describe('Path to a workspace config.yaml'),
             ignoreShaCheck: z
                 .boolean()
@@ -208,6 +212,7 @@ export function registerRunCloudTest(server) {
             iOSDevice: args.iosDevice,
             iOSVersion: args.iosVersion,
             name: args.name,
+            priority: args.priority,
             runnerType: args.runnerType ?? 'default',
             maestroVersion: resolvedMaestroVersion,
             retry: args.retry,

package/dist/services/results-polling.service.d.ts

@@ -118,6 +118,7 @@ export declare class ResultsPollingService {
      * @param apiUrl API base URL
      * @param auth AuthContext carrying request headers
      * @param uploadId Upload ID to fetch results for
+     * @param cache The poll loop's results cache, for ETag revalidation
      * @param debug Whether debug logging is enabled
      * @param logger Optional logger function
      * @returns Promise resolving to test results

package/dist/services/results-polling.service.js

@@ -133,6 +133,9 @@ export class ResultsPollingService {
         let { auth } = options;
         this.initializePollingDisplay(json, logger);
         let sequentialPollFailures = 0;
+        // The last result set and its ETag, so a poll that finds nothing changed
+        // gets an empty 304 instead of the whole set again.
+        const resultsCache = {};
         const pollIntervalMs = auth.mode === 'bearer'
             ? this.BEARER_POLL_INTERVAL_MS
             : this.APIKEY_POLL_INTERVAL_MS;
@@ -229,7 +232,7 @@ export class ResultsPollingService {
                     nextPollAt = null;
                     renderStatus();
                     auth = await this.refreshPollingAuth(auth, uploadId, subscription, debug, logger);
-                    const updatedResults = await this.fetchAndLogResults(apiUrl, auth, uploadId, debug, logger);
+                    const updatedResults = await this.fetchAndLogResults(apiUrl, auth, uploadId, resultsCache, debug, logger);
                     const { summary } = this.calculateStatusSummary(updatedResults);
                     if (!json) {
                         statusBody = this.buildStatusBody(updatedResults, quiet, summary);
@@ -395,21 +398,28 @@ export class ResultsPollingService {
      * @param apiUrl API base URL
      * @param auth AuthContext carrying request headers
      * @param uploadId Upload ID to fetch results for
+     * @param cache The poll loop's results cache, for ETag revalidation
      * @param debug Whether debug logging is enabled
      * @param logger Optional logger function
      * @returns Promise resolving to test results
      */
-    async fetchAndLogResults(apiUrl, auth, uploadId, debug, logger) {
+    async fetchAndLogResults(apiUrl, auth, uploadId, cache, debug, logger) {
         if (debug && logger) {
             logger(`[DEBUG] Polling for results: ${uploadId}`);
         }
-        const { results: updatedResults } = await ApiGateway.getResultsForUpload(apiUrl, auth, uploadId);
+        // A 304 hands back the cached body itself; a 200 is always a new object.
+        const cachedBody = cache.body;
+        const response = await ApiGateway.getResultsForUpload(apiUrl, auth, uploadId, cache);
+        const notModified = cachedBody !== undefined && response === cachedBody;
+        const { results: updatedResults } = response;
         // An empty array would otherwise read as "all complete, all passed".
         if (!updatedResults || updatedResults.length === 0) {
             throw new Error('no results');
         }
         if (debug && logger) {
-            logger(`[DEBUG] Poll received ${updatedResults.length} results`);
+            logger(notModified
+                ? `[DEBUG] Poll not modified (304), reusing ${updatedResults.length} cached results`
+                : `[DEBUG] Poll received ${updatedResults.length} results`);
             for (const result of updatedResults) {
                 logger(`[DEBUG] Result status: ${result.test_file_name} - ${result.status}`);
             }

package/dist/services/test-submission.service.d.ts

@@ -50,6 +50,13 @@ export interface TestSubmissionConfig {
     metadata?: string[];
     name?: string;
     orientation?: string;
+    /**
+     * Where this upload sits among the org's own queued runs. Like
+     * `cancelPrevious`, sent as its own field rather than inside `config`: it is
+     * a scheduling directive for the whole upload, not run configuration. Only
+     * reorders the org's own queue; it never moves the org ahead of others.
+     */
+    priority?: 'low' | 'normal' | 'high';
     raw?: unknown;
     /**
      * Which emulator software renderer to boot with (Android only). Omitted

package/dist/services/test-submission.service.js

@@ -20,7 +20,7 @@ export class TestSubmissionService {
      * @returns The flow zip buffer, its SHA-256, and the string-encoded fields
      */
     async buildTestPayload(config) {
-        const { apiUrl, appBinaryId, appPlatform, encrypt, flowFile, executionPlan, commonRoot, cliVersion, env = [], metadata = [], cancelPrevious = false, googlePlay = false, androidApiLevel, androidDevice, androidNoSnapshot, iOSVersion, iOSDevice, name, runnerType, maestroVersion, deviceLocale, orientation, retry, continueOnFailure = true, renderEngine, report, showCrosshairs, maestroChromeOnboarding, raw, disableAnimations, deviceMatrix, debug = false, logger, } = config;
+        const { apiUrl, appBinaryId, appPlatform, encrypt, flowFile, executionPlan, commonRoot, cliVersion, env = [], metadata = [], cancelPrevious = false, googlePlay = false, androidApiLevel, androidDevice, androidNoSnapshot, iOSVersion, iOSDevice, name, runnerType, maestroVersion, deviceLocale, orientation, priority, retry, continueOnFailure = true, renderEngine, report, showCrosshairs, maestroChromeOnboarding, raw, disableAnimations, deviceMatrix, debug = false, logger, } = config;
         const { allExcludeTags, allIncludeTags, flowMetadata, flowOverrides, flowsToRun: testFileNames, includedFiles = [], referencedFiles, sequence, workspaceConfig, } = executionPlan;
         const { flows: sequentialFlows = [] } = sequence ?? {};
         const envObject = this.parseKeyValuePairs(env);
@@ -168,6 +168,11 @@ export class TestSubmissionService {
         if (cancelPrevious) {
             fields.cancelPrevious = 'true';
         }
+        // Same reasoning: 'normal' is the default and is never sent, so the
+        // default path's wire shape is unchanged and an older API never sees it.
+        if (priority && priority !== 'normal') {
+            fields.priority = priority;
+        }
         this.setOptionalFields(fields, {
             androidApiLevel,
             androidDevice,

package/package.json

@@ -30,7 +30,7 @@
     "chai": "^6.2.2",
     "eslint": "^10.5.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-unicorn": "^76.0.0",
+    "eslint-plugin-unicorn": "^77.0.0",
     "husky": "^9.1.7",
     "mocha": "^12.0.0",
     "prettier": "^3.8.4",
@@ -68,7 +68,7 @@
     "test:unit": "node scripts/test-runner.mjs --unit",
     "typecheck": "tsc --noEmit -p tsconfig.test.json"
   },
-  "version": "5.7.1",
+  "version": "5.8.0-beta.2",
   "bugs": {
     "url": "https://discord.gg/gm3mJwcNw8"
   },