@devicecloud.dev/dcd 5.6.0-beta.3 → 5.6.0-beta.4

package/README.md

@@ -45,13 +45,15 @@ Add it to your MCP client config:
   "mcpServers": {
     "devicecloud": {
       "command": "npx",
-      "args": ["-y", "@devicecloud.dev/dcd", "dcd-mcp"],
+      "args": ["-y", "--package=@devicecloud.dev/dcd", "dcd-mcp"],
       "env": { "DEVICE_CLOUD_API_KEY": "<your-api-key>" }
     }
   }
 }
 ```
 
+`--package` matters: the package's default bin is `dcd`, so `npx @devicecloud.dev/dcd dcd-mcp` would run `dcd dcd-mcp` (an unknown command) instead of the server.
+
 Auth is inherited from the CLI: set `DEVICE_CLOUD_API_KEY` as above, or run `dcd login` once and the server picks up the stored session. Point it at a non-prod environment with `DCD_API_URL`.
 
 **Tools**
@@ -64,7 +66,7 @@ Auth is inherited from the CLI: set `DEVICE_CLOUD_API_KEY` as above, or run `dcd
 | `dcd_download_artifacts` | Download a run's artifacts/report to disk |
 | `dcd_run_cloud_test` | Submit a flow to run on the cloud (**billable**) |
 
-**Read-only mode.** `dcd_run_cloud_test` consumes test minutes, so it is annotated as non-read-only/destructive (clients can prompt before calling it). To hide it entirely — recommended for autonomous or untrusted agents — pass `--read-only` in `args`, or set `DCD_MCP_READONLY=1` in `env`.
+**Read-only mode.** `dcd_run_cloud_test` consumes test minutes, so it is annotated as non-read-only/destructive (clients can prompt before calling it). To hide it entirely — recommended for autonomous or untrusted agents — pass `--read-only` at the end of `args` (`["-y", "--package=@devicecloud.dev/dcd", "dcd-mcp", "--read-only"]`), or set `DCD_MCP_READONLY=1` in `env`.
 
 By default `dcd_run_cloud_test` is async: it returns an `uploadId` immediately, which you poll with `dcd_get_status`. Pass `wait: true` (bounded by `waitTimeoutSeconds`) to block until completion, or `dryRun: true` to preview the flows without submitting.
 

package/dist/commands/artifacts.d.ts

@@ -27,7 +27,7 @@ export declare const artifactsCommand: import("citty").CommandDef<{
     };
     readonly 'html-path': {
         readonly type: "string";
-        readonly description: "Custom file path for downloaded HTML report (default: ./report.html)";
+        readonly description: "Custom file path for the downloaded HTML report, a ZIP of report.html and its assets (default: ./report.zip)";
     };
     readonly 'junit-path': {
         readonly type: "string";

package/dist/commands/artifacts.js

@@ -41,7 +41,7 @@ export const artifactsCommand = defineCommand({
         },
         'html-path': {
             type: 'string',
-            description: 'Custom file path for downloaded HTML report (default: ./report.html)',
+            description: 'Custom file path for the downloaded HTML report, a ZIP of report.html and its assets (default: ./report.zip)',
         },
         'junit-path': {
             type: 'string',

package/dist/commands/cloud.d.ts

@@ -35,7 +35,7 @@ export declare const cloudCommand: import("citty").CommandDef<{
     };
     readonly 'html-path': {
         readonly type: "string";
-        readonly description: "Custom file path for downloaded HTML report (requires --report html, default: ./report.html)";
+        readonly description: "Custom file path for the downloaded HTML report, a ZIP of report.html and its assets (requires --report html or html-detailed, default: ./report.zip)";
     };
     readonly async: {
         readonly type: "boolean";
@@ -101,7 +101,7 @@ export declare const cloudCommand: import("citty").CommandDef<{
     readonly 'cancel-previous': {
         readonly type: "boolean";
         readonly default: false;
-        readonly description: "Cancel the still-queued tests of the previous run from the same CI context (repo + branch/PR + check name, read from your CI metadata). Tests already running are left to finish; cancelled tests are refunded at 75%. Does nothing outside CI.";
+        readonly description: "Cancel the still-queued tests of the previous run from the same CI context: the same repo and branch or PR (and check name, if one is set), read from the run metadata. Needs repo plus branch/PR metadata (--repo-name with --branch or --pr-number, or --metadata gh_repo=… with gh_branch=… or gh_pr_number=…); without it nothing is superseded. Tests already running are left to finish; cancelled tests are refunded at 75%.";
     };
     readonly config: {
         readonly type: "string";
@@ -211,12 +211,12 @@ export declare const cloudCommand: import("citty").CommandDef<{
     readonly 'android-no-snapshot': {
         readonly type: "boolean";
         readonly default: false;
-        readonly description: "[Android only] Force cold boot instead of using snapshot boot. This is automatically enabled for API 35+ but can be used to force cold boot on older API levels.";
+        readonly description: "[Android only] Force cold boot instead of using snapshot boot. This is automatically enabled for API 34+ but can be used to force cold boot on older API levels.";
     };
     readonly 'disable-animations': {
         readonly type: "boolean";
-        readonly default: false;
-        readonly description: "Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion. Reduces CPU load and may improve test reliability.";
+        readonly description: "Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion. Reduces CPU load and may improve test reliability. Overrides platform.ios/android.disableAnimations in config.yaml.";
+        readonly negativeDescription: "Keep device animations on, even where config.yaml sets platform.ios/android.disableAnimations";
     };
     readonly 'app-binary-id': {
         readonly type: "string";

package/dist/commands/cloud.js

@@ -14,7 +14,7 @@ import { deviceFromResultRow, ResultsPollingService, RunFailedError, } from '../
 import { telemetry } from '../services/telemetry.service.js';
 import { TestSubmissionService } from '../services/test-submission.service.js';
 import { VersionService } from '../services/version.service.js';
-import { EAndroidApiLevels, EAndroidDevices, EiOSDevices, EiOSVersions, isIosMatrixConfig, } from '../types/domain/device.types.js';
+import { isIosMatrixConfig } from '../types/domain/device.types.js';
 import { resolveAuth } from '../utils/auth.js';
 import { assertMatrixSupported, matrixIsIos, parseDeviceMatrix, } from '../utils/device-matrix.js';
 import { isEncryptionEnabled } from '../utils/envelope.js';
@@ -140,10 +140,14 @@ export const cloudCommand = defineCommand({
             // (#1152). Flag wins; otherwise DCD_ENCRYPT / DCD_ENCRYPT_BINARIES.
             const encrypt = isEncryptionEnabled(args['encrypt'] ? true : undefined);
             const includeTags = coerceArray(collectRepeatedFlag(rawArgs, ['--include-tags']));
-            const iOSDevice = validateEnum(args['ios-device'], Object.values(EiOSDevices), 'ios-device');
-            const iOSVersion = validateEnum(args['ios-version'], Object.values(EiOSVersions), 'ios-version');
-            const androidApiLevel = validateEnum(args['android-api-level'], Object.values(EAndroidApiLevels), 'android-api-level');
-            const androidDevice = validateEnum(args['android-device'], Object.values(EAndroidDevices), 'android-device');
+            // Devices and OS versions are checked against the API's live
+            // compatibility data further down (DeviceValidationService), not the
+            // CLI's enums, which only feed --help: a device the API adds must not
+            // need a CLI release, and one it drops must fail with the API's list.
+            const iOSDevice = args['ios-device'] || undefined;
+            const iOSVersion = args['ios-version'] || undefined;
+            const androidApiLevel = args['android-api-level'] || undefined;
+            const androidDevice = args['android-device'] || undefined;
             const androidNoSnapshot = Boolean(args['android-no-snapshot']);
             // Repeatable device-matrix flags: one validated cell each, no cross-product.
             const iosMatrixFlags = collectRepeatedFlag(rawArgs, ['--ios-device-matrix']);
@@ -164,7 +168,9 @@ export const cloudCommand = defineCommand({
             const renderEngine = validateEnum(args['render-engine'], RENDER_ENGINE_OPTIONS, 'render-engine');
             const showCrosshairs = Boolean(args['show-crosshairs']);
             const maestroChromeOnboarding = Boolean(args['maestro-chrome-onboarding']);
-            const disableAnimations = Boolean(args['disable-animations']);
+            // Left undefined when not passed, so config.yaml's per-platform value
+            // applies; --no-disable-animations is an explicit false that beats it.
+            const disableAnimations = args['disable-animations'];
             const ghBranch = args.branch;
             const ghCommitSha = args['commit-sha'];
             const ghRepoName = args['repo-name'];
@@ -557,6 +563,8 @@ export const cloudCommand = defineCommand({
                 androidNoSnapshot,
                 apiUrl,
                 appBinaryId: finalBinaryId,
+                // With --app-binary-id the binary's platform is unknown here.
+                appPlatform: appBinaryId ? undefined : platformFromAppFile(finalAppFile),
                 cancelPrevious,
                 cliVersion,
                 commonRoot,

package/dist/commands/switch-org.js

@@ -6,7 +6,7 @@
  * Without an argument: fetch orgs and prompt the user to pick one.
  */
 import { defineCommand } from 'citty';
-import { resolveAuth } from '../utils/auth.js';
+import { apiKeyOverride, resolveAuth } from '../utils/auth.js';
 import { CliError, logger } from '../utils/cli.js';
 import { readConfig, resolveApiUrl, writeConfig } from '../utils/config-store.js';
 import { fetchOrgs, pickOrg } from '../utils/orgs.js';
@@ -54,6 +54,10 @@ export const switchOrgCommand = defineCommand({
             current_org_name: chosen.name,
         });
         logger.log(ui.success(`Switched to ${colors.highlight(chosen.name)}`));
+        // The switch only changes the stored session; an exported key still wins.
+        if (apiKeyOverride() === 'DEVICE_CLOUD_API_KEY') {
+            logger.log(ui.warn(`${colors.highlight('DEVICE_CLOUD_API_KEY')} is set, so other dcd commands still authenticate with that API key and its org, not ${chosen.name}. Unset it to use the session.`));
+        }
     },
 });
 /**

package/dist/commands/upload.js

@@ -7,6 +7,7 @@ import { uploadBinary, verifyAppZip } from '../methods.js';
 import { resolveAuth } from '../utils/auth.js';
 import { CliError, logger } from '../utils/cli.js';
 import { resolveApiUrl } from '../utils/config-store.js';
+import { isEncryptionEnabled } from '../utils/envelope.js';
 import { downloadExpoUrl, extractTarGz, findAppBundle, isUrl } from '../utils/expo.js';
 import { colors, formatId } from '../utils/styling.js';
 import { ui } from '../utils/ui.js';
@@ -41,7 +42,10 @@ export const uploadCommand = defineCommand({
             const apiUrl = resolveApiUrl(args['api-url']);
             const appUrl = args['app-url'];
             const ignoreShaCheck = Boolean(args['ignore-sha-check']);
-            const encryptBinary = Boolean(args['encrypt']);
+            // Same rule as `dcd cloud`: the flag turns encryption on, and without it
+            // DCD_ENCRYPT decides. Passing `false` here used to mean "explicitly
+            // off", which silently beat DCD_ENCRYPT=1 for every `dcd upload`.
+            const encryptBinary = isEncryptionEnabled(args['encrypt'] ? true : undefined);
             const debug = Boolean(args.debug);
             const positional = args.appFile;
             const auth = await resolveAuth({ apiKeyFlag });

package/dist/commands/whoami.d.ts

@@ -1,2 +1,8 @@
-export declare const whoamiCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+export declare const whoamiCommand: import("citty").CommandDef<{
+    readonly 'api-key': {
+        readonly description: "An API key as you would pass it to other commands; whoami says that it takes precedence over the stored session";
+        readonly type: "string";
+        readonly alias: ["apiKey"];
+    };
+}>;
 export default whoamiCommand;

package/dist/commands/whoami.js

@@ -1,7 +1,13 @@
 /**
  * `dcd whoami` — prints the logged-in user + active org from stored config.
+ *
+ * It reads only the stored `dcd login` session, while every other command
+ * prefers an API key from --api-key or DEVICE_CLOUD_API_KEY — so when one is
+ * present it says so, rather than implying the session is what they use.
  */
 import { defineCommand } from 'citty';
+import { apiFlags } from '../config/flags/api.flags.js';
+import { apiKeyOverride } from '../utils/auth.js';
 import { logger } from '../utils/cli.js';
 import { readConfig } from '../utils/config-store.js';
 import { colors, formatId } from '../utils/styling.js';
@@ -11,10 +17,22 @@ export const whoamiCommand = defineCommand({
         name: 'whoami',
         description: 'Show the logged-in user and active organization',
     },
-    run() {
+    args: {
+        'api-key': {
+            ...apiFlags['api-key'],
+            description: 'An API key as you would pass it to other commands; whoami says that it takes precedence over the stored session',
+        },
+    },
+    run({ args }) {
         const config = readConfig();
+        const keySource = apiKeyOverride(args['api-key']);
+        const keyName = colors.highlight(keySource ?? '');
         if (!config?.session) {
-            logger.log(ui.info(`Not logged in. Run ${colors.highlight('dcd login')} or set ${colors.highlight('DEVICE_CLOUD_API_KEY')}.`));
+            logger.log(ui.info(keySource === 'DEVICE_CLOUD_API_KEY'
+                ? `Not logged in. ${keyName} is set, so dcd commands authenticate with that API key.`
+                : keySource === '--api-key'
+                    ? `Not logged in. Commands given ${keyName} authenticate with that API key.`
+                    : `Not logged in. Run ${colors.highlight('dcd login')} or set ${colors.highlight('DEVICE_CLOUD_API_KEY')}.`));
             return;
         }
         // Fallback for sessions stored before we persisted org name alongside id.
@@ -26,6 +44,12 @@ export const whoamiCommand = defineCommand({
         fields.push(['env', config.env]);
         logger.log(ui.section('devicecloud.dev'));
         logger.log(ui.branch(ui.fields(fields)));
+        if (keySource === 'DEVICE_CLOUD_API_KEY') {
+            logger.log(ui.warn(`${keyName} is set, so other dcd commands authenticate with that API key and its org, not this session. Unset it to use the session.`));
+        }
+        else if (keySource === '--api-key') {
+            logger.log(ui.warn(`Commands given ${keyName} authenticate with that API key and its org, not this session.`));
+        }
     },
 });
 export default whoamiCommand;

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

@@ -56,11 +56,11 @@ export declare const deviceFlags: {
     readonly 'android-no-snapshot': {
         readonly type: "boolean";
         readonly default: false;
-        readonly description: "[Android only] Force cold boot instead of using snapshot boot. This is automatically enabled for API 35+ but can be used to force cold boot on older API levels.";
+        readonly description: "[Android only] Force cold boot instead of using snapshot boot. This is automatically enabled for API 34+ but can be used to force cold boot on older API levels.";
     };
     readonly 'disable-animations': {
         readonly type: "boolean";
-        readonly default: false;
-        readonly description: "Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion. Reduces CPU load and may improve test reliability.";
+        readonly description: "Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion. Reduces CPU load and may improve test reliability. Overrides platform.ios/android.disableAnimations in config.yaml.";
+        readonly negativeDescription: "Keep device animations on, even where config.yaml sets platform.ios/android.disableAnimations";
     };
 };

package/dist/config/flags/device.flags.js

@@ -61,11 +61,13 @@ export const deviceFlags = {
     'android-no-snapshot': {
         type: 'boolean',
         default: false,
-        description: '[Android only] Force cold boot instead of using snapshot boot. This is automatically enabled for API 35+ but can be used to force cold boot on older API levels.',
+        description: '[Android only] Force cold boot instead of using snapshot boot. This is automatically enabled for API 34+ but can be used to force cold boot on older API levels.',
     },
+    // No default: an unset flag must be distinguishable from --no-disable-animations
+    // so the platform's disableAnimations in config.yaml applies only when unset.
     'disable-animations': {
         type: 'boolean',
-        default: false,
-        description: 'Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion. Reduces CPU load and may improve test reliability.',
+        description: 'Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion. Reduces CPU load and may improve test reliability. Overrides platform.ios/android.disableAnimations in config.yaml.',
+        negativeDescription: 'Keep device animations on, even where config.yaml sets platform.ios/android.disableAnimations',
     },
 };

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

@@ -5,7 +5,7 @@ export declare const executionFlags: {
     readonly 'cancel-previous': {
         readonly type: "boolean";
         readonly default: false;
-        readonly description: "Cancel the still-queued tests of the previous run from the same CI context (repo + branch/PR + check name, read from your CI metadata). Tests already running are left to finish; cancelled tests are refunded at 75%. Does nothing outside CI.";
+        readonly description: "Cancel the still-queued tests of the previous run from the same CI context: the same repo and branch or PR (and check name, if one is set), read from the run metadata. Needs repo plus branch/PR metadata (--repo-name with --branch or --pr-number, or --metadata gh_repo=… with gh_branch=… or gh_pr_number=…); without it nothing is superseded. Tests already running are left to finish; cancelled tests are refunded at 75%.";
     };
     readonly config: {
         readonly type: "string";

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

@@ -5,7 +5,7 @@ export const executionFlags = {
     'cancel-previous': {
         type: 'boolean',
         default: false,
-        description: 'Cancel the still-queued tests of the previous run from the same CI context (repo + branch/PR + check name, read from your CI metadata). Tests already running are left to finish; cancelled tests are refunded at 75%. Does nothing outside CI.',
+        description: 'Cancel the still-queued tests of the previous run from the same CI context: the same repo and branch or PR (and check name, if one is set), read from the run metadata. Needs repo plus branch/PR metadata (--repo-name with --branch or --pr-number, or --metadata gh_repo=… with gh_branch=… or gh_pr_number=…); without it nothing is superseded. Tests already running are left to finish; cancelled tests are refunded at 75%.',
     },
     config: {
         type: 'string',

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

@@ -16,7 +16,7 @@ export declare const outputFlags: {
     };
     readonly 'html-path': {
         readonly type: "string";
-        readonly description: "Custom file path for downloaded HTML report (requires --report html, default: ./report.html)";
+        readonly description: "Custom file path for the downloaded HTML report, a ZIP of report.html and its assets (requires --report html or html-detailed, default: ./report.zip)";
     };
     readonly async: {
         readonly type: "boolean";

package/dist/config/flags/output.flags.js

@@ -16,7 +16,7 @@ export const outputFlags = {
     },
     'html-path': {
         type: 'string',
-        description: 'Custom file path for downloaded HTML report (requires --report html, default: ./report.html)',
+        description: 'Custom file path for the downloaded HTML report, a ZIP of report.html and its assets (requires --report html or html-detailed, default: ./report.zip)',
     },
     async: {
         type: 'boolean',

package/dist/constants.d.ts

@@ -21,7 +21,7 @@ export declare const flags: {
     };
     readonly 'html-path': {
         readonly type: "string";
-        readonly description: "Custom file path for downloaded HTML report (requires --report html, default: ./report.html)";
+        readonly description: "Custom file path for the downloaded HTML report, a ZIP of report.html and its assets (requires --report html or html-detailed, default: ./report.zip)";
     };
     readonly async: {
         readonly type: "boolean";
@@ -87,7 +87,7 @@ export declare const flags: {
     readonly 'cancel-previous': {
         readonly type: "boolean";
         readonly default: false;
-        readonly description: "Cancel the still-queued tests of the previous run from the same CI context (repo + branch/PR + check name, read from your CI metadata). Tests already running are left to finish; cancelled tests are refunded at 75%. Does nothing outside CI.";
+        readonly description: "Cancel the still-queued tests of the previous run from the same CI context: the same repo and branch or PR (and check name, if one is set), read from the run metadata. Needs repo plus branch/PR metadata (--repo-name with --branch or --pr-number, or --metadata gh_repo=… with gh_branch=… or gh_pr_number=…); without it nothing is superseded. Tests already running are left to finish; cancelled tests are refunded at 75%.";
     };
     readonly config: {
         readonly type: "string";
@@ -197,12 +197,12 @@ export declare const flags: {
     readonly 'android-no-snapshot': {
         readonly type: "boolean";
         readonly default: false;
-        readonly description: "[Android only] Force cold boot instead of using snapshot boot. This is automatically enabled for API 35+ but can be used to force cold boot on older API levels.";
+        readonly description: "[Android only] Force cold boot instead of using snapshot boot. This is automatically enabled for API 34+ but can be used to force cold boot on older API levels.";
     };
     readonly 'disable-animations': {
         readonly type: "boolean";
-        readonly default: false;
-        readonly description: "Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion. Reduces CPU load and may improve test reliability.";
+        readonly description: "Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion. Reduces CPU load and may improve test reliability. Overrides platform.ios/android.disableAnimations in config.yaml.";
+        readonly negativeDescription: "Keep device animations on, even where config.yaml sets platform.ios/android.disableAnimations";
     };
     readonly 'app-binary-id': {
         readonly type: "string";

package/dist/gateways/api-gateway.js

@@ -566,7 +566,8 @@ export const ApiGateway = {
             },
             html: {
                 endpoint: `/results/${uploadId}/html-report`,
-                defaultFilename: `report-${uploadId}.html`,
+                // A ZIP of report.html plus its assets, not a bare HTML file.
+                defaultFilename: `report-${uploadId}.zip`,
                 notFoundMessage: `Upload ID '${uploadId}' not found or no HTML report available for this upload`,
                 errorPrefix: 'Failed to download HTML report',
             },

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

@@ -8,6 +8,13 @@ export interface RealtimeResultsSubscription {
     isConnected(): boolean;
     /** Tear down the channel and close the socket. Best-effort, never throws. */
     unsubscribe(): Promise<void>;
+    /**
+     * Hand the socket a refreshed JWT. RLS authorises the channel with the token
+     * it joined with, and the server drops the channel once that expires — so a
+     * poll that outlives the token passes the new one on. Best-effort, never
+     * throws.
+     */
+    updateAccessToken(accessToken: string): void;
 }
 export interface RealtimeSubscribeOptions {
     /** Supabase JWT (AuthContext.accessToken) — authorises the socket for RLS. */

package/dist/gateways/realtime-gateway.js

@@ -86,6 +86,13 @@ export class RealtimeResultsGateway {
                         /* best effort — process is exiting anyway */
                     }
                 },
+                updateAccessToken(nextToken) {
+                    // setAuth updates the join payload and pushes the token to joined
+                    // channels. A failure only costs realtime; the backstop poll stays.
+                    activeClient.realtime.setAuth(nextToken).catch((error) => {
+                        dbg(`failed to update the socket's token: ${error instanceof Error ? error.message : String(error)}`);
+                    });
+                },
             };
         }
         catch (error) {
@@ -97,7 +104,11 @@ export class RealtimeResultsGateway {
             catch {
                 /* ignore */
             }
-            return { isConnected: () => false, async unsubscribe() { } };
+            return {
+                isConnected: () => false,
+                async unsubscribe() { },
+                updateAccessToken() { },
+            };
         }
     }
 }

package/dist/mcp/context.d.ts

@@ -1,6 +1,7 @@
 /**
- * Per-process MCP context: a single resolved AuthContext + API URL, plus the
- * stderr logger every tool must use.
+ * Per-process MCP context: the resolved AuthContext + API URL (re-resolved
+ * when a `dcd login` session nears expiry), plus the stderr logger every tool
+ * must use.
  *
  * stdio transport reserves **stdout** for the JSON-RPC frame stream — anything
  * a tool prints there corrupts the protocol. Tools therefore call the services
@@ -15,17 +16,27 @@ export interface McpContext {
     auth: AuthContext;
 }
 /**
- * Resolve auth + API URL once per process, lazily on first tool invocation.
+ * Resolve auth + API URL lazily on first tool invocation, and again whenever a
+ * `dcd login` session is near expiry.
  *
  * Lazy so `initialize` / `tools/list` succeed before the user has supplied a
  * credential (clients enumerate tools on connect), and so an auth failure
  * surfaces as a tool error rather than crashing the server at boot.
  *
+ * Re-resolved near expiry because a session's access token lasts about an
+ * hour while an MCP server can run for days: resolving once left every tool
+ * call failing after the first hour. resolveAuth refreshes the stored session
+ * (or picks up one another `dcd` process already refreshed). A failed
+ * refresh leaves the cache alone, so the next call retries — including after
+ * the user runs `dcd login` again. API keys never expire and are resolved once.
+ *
  * Precedence matches the CLI: `DEVICE_CLOUD_API_KEY` env > stored `dcd login`
  * session. The API URL honors `DCD_API_URL` (handy for pointing the server at
  * dev/staging), then the logged-in env, then the prod default.
  */
 export declare function getContext(): Promise<McpContext>;
+/** Forget the resolved context. For tests. */
+export declare function clearContextCache(): void;
 /**
  * Read-only mode hides the only state-changing / billable tool
  * (`dcd_run_cloud_test`). Recommended for autonomous or untrusted agents.

package/dist/mcp/context.js

@@ -1,4 +1,4 @@
-import { resolveAuth } from '../utils/auth.js';
+import { isAuthExpiring, resolveAuth } from '../utils/auth.js';
 import { resolveApiUrl } from '../utils/config-store.js';
 /** Write a line to stderr. Safe under stdio transport; stdout is reserved. */
 export function logStderr(message) {
@@ -6,24 +6,36 @@ export function logStderr(message) {
 }
 let cached = null;
 /**
- * Resolve auth + API URL once per process, lazily on first tool invocation.
+ * Resolve auth + API URL lazily on first tool invocation, and again whenever a
+ * `dcd login` session is near expiry.
  *
  * Lazy so `initialize` / `tools/list` succeed before the user has supplied a
  * credential (clients enumerate tools on connect), and so an auth failure
  * surfaces as a tool error rather than crashing the server at boot.
  *
+ * Re-resolved near expiry because a session's access token lasts about an
+ * hour while an MCP server can run for days: resolving once left every tool
+ * call failing after the first hour. resolveAuth refreshes the stored session
+ * (or picks up one another `dcd` process already refreshed). A failed
+ * refresh leaves the cache alone, so the next call retries — including after
+ * the user runs `dcd login` again. API keys never expire and are resolved once.
+ *
  * Precedence matches the CLI: `DEVICE_CLOUD_API_KEY` env > stored `dcd login`
  * session. The API URL honors `DCD_API_URL` (handy for pointing the server at
  * dev/staging), then the logged-in env, then the prod default.
  */
 export async function getContext() {
-    if (cached)
+    if (cached && !isAuthExpiring(cached.auth))
         return cached;
     const auth = await resolveAuth({ apiKeyFlag: undefined });
     const apiUrl = resolveApiUrl(process.env.DCD_API_URL);
     cached = { apiUrl, auth };
     return cached;
 }
+/** Forget the resolved context. For tests. */
+export function clearContextCache() {
+    cached = null;
+}
 /**
  * Read-only mode hides the only state-changing / billable tool
  * (`dcd_run_cloud_test`). Recommended for autonomous or untrusted agents.

package/dist/mcp/tools/download-artifacts.js

@@ -34,7 +34,7 @@ export function registerDownloadArtifacts(server) {
             reportPath: z
                 .string()
                 .optional()
-                .describe('Local path for the report file (defaults depend on report type)'),
+                .describe('Local path for the report file (default ./report.xml for junit, ./report.html for allure, ./report.zip for html, which is a ZIP of report.html and its assets)'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => runTool('dcd_download_artifacts', async () => {
@@ -57,11 +57,14 @@ export function registerDownloadArtifacts(server) {
         });
         let reportPath;
         if (args.report) {
-            reportPath = args.reportPath
-                ? path.resolve(args.reportPath)
-                : path.resolve(args.report === 'junit'
-                    ? 'report.xml'
-                    : 'report.html');
+            // The HTML report is a ZIP of report.html plus assets; Allure's is
+            // a single HTML file.
+            const defaultReportPath = {
+                allure: 'report.html',
+                html: 'report.zip',
+                junit: 'report.xml',
+            }[args.report];
+            reportPath = path.resolve(args.reportPath || defaultReportPath);
             await service.downloadReports({
                 apiUrl,
                 auth,

package/dist/mcp/tools/list-devices.js

@@ -11,7 +11,7 @@ export function registerListDevices(server) {
         title: 'List available devices',
         description: 'List the iOS and Android devices, OS versions, and Maestro versions available on devicecloud.dev. ' +
             'Use this to discover valid device/version values before submitting a test run. ' +
-            'Returns: { ios, android, androidPlay, maestro }, where each platform maps OS version → supported device list.',
+            'Returns: { ios, android, androidPlay, maestro }, where each platform maps a device slug to the OS versions it runs.',
         inputSchema: {},
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async () => runTool('dcd_list_devices', async () => {

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

@@ -4,9 +4,11 @@ import { ApiError, ApiGateway } from '../../gateways/api-gateway.js';
 import { plan } from '../../services/execution-plan.service.js';
 import { computeCommonRoot, buildTestMetadataMap } from '../../services/flow-paths.js';
 import { DeviceValidationService } from '../../services/device-validation.service.js';
+import { platformFromAppFile } from '../../services/notices.service.js';
 import { TestSubmissionService } from '../../services/test-submission.service.js';
 import { VersionService } from '../../services/version.service.js';
 import { uploadBinary, uploadFlowZip, verifyAppZip } from '../../methods.js';
+import { refreshAuth } from '../../utils/auth.js';
 import { getCliVersion } from '../../utils/cli.js';
 import { fetchCompatibilityData } from '../../utils/compatibility.js';
 import { isEncryptionEnabled } from '../../utils/envelope.js';
@@ -100,8 +102,15 @@ export function registerRunCloudTest(server) {
         const cliVersion = getCliVersion();
         const compatibilityData = await fetchCompatibilityData(apiUrl, auth);
         const deviceValidation = new DeviceValidationService();
-        deviceValidation.validateiOSDevice(args.iosVersion, args.iosDevice, compatibilityData, { logger: logStderr });
-        deviceValidation.validateAndroidDevice(args.androidApiLevel, args.androidDevice, Boolean(args.googlePlay), compatibilityData, { logger: logStderr });
+        // Hints in validation errors name this tool's parameters, not CLI flags.
+        const argNames = {
+            androidApiLevel: 'androidApiLevel',
+            androidDevice: 'androidDevice',
+            iOSDevice: 'iosDevice',
+            iOSVersion: 'iosVersion',
+        };
+        deviceValidation.validateiOSDevice(args.iosVersion, args.iosDevice, compatibilityData, { argNames, logger: logStderr });
+        deviceValidation.validateAndroidDevice(args.androidApiLevel, args.androidDevice, Boolean(args.googlePlay), compatibilityData, { argNames, logger: logStderr });
         const resolvedMaestroVersion = new VersionService().resolveMaestroVersion(args.maestroVersion, compatibilityData, { logger: logStderr });
         // Directory inputs must end in a separator so the planner treats them
         // as a workspace rather than a single file.
@@ -162,6 +171,8 @@ export function registerRunCloudTest(server) {
         const { buffer, fields } = await testSubmissionService.buildTestPayload({
             apiUrl,
             appBinaryId,
+            // Picks the workspace config's per-platform disableAnimations.
+            appPlatform: args.appBinaryId ? undefined : platformFromAppFile(args.appFile),
             cliVersion,
             commonRoot,
             continueOnFailure,
@@ -221,8 +232,13 @@ export function registerRunCloudTest(server) {
         // Bounded poll. The run continues in the cloud regardless of timeout —
         // the caller can resume with dcd_get_status using the returned uploadId.
         const deadline = Date.now() + (args.waitTimeoutSeconds ?? 600) * 1000;
+        let pollAuth = auth;
         for (;;) {
-            const status = await ApiGateway.getUploadStatus(apiUrl, auth, { uploadId });
+            // A wait of up to an hour can outlast a `dcd login` access token.
+            pollAuth = await refreshAuth(pollAuth);
+            const status = await ApiGateway.getUploadStatus(apiUrl, pollAuth, {
+                uploadId,
+            });
             if (TERMINAL_STATUSES.has(status.status)) {
                 return jsonResult({ uploadId, consoleUrl, status: status.status, tests: status.tests });
             }

package/dist/services/device-validation.service.d.ts

@@ -1,10 +1,25 @@
-import { CompatibilityData } from '../utils/compatibility.js';
+import type { CompatibilityData } from '../utils/compatibility.js';
+/** The device / OS inputs a caller exposes, named for "pass it explicitly" hints. */
+export interface DeviceArgNames {
+    androidApiLevel: string;
+    androidDevice: string;
+    iOSDevice: string;
+    iOSVersion: string;
+}
 export interface DeviceValidationOptions {
+    /** How the caller names its inputs in error hints. Defaults to the CLI flags. */
+    argNames?: DeviceArgNames;
     debug?: boolean;
     logger?: (message: string) => void;
 }
 /**
- * Service for validating device configurations against compatibility data
+ * Validates requested devices against the compatibility matrix the API serves
+ * from `GET /results/compatibility/data`, which is the only authority on what
+ * can run. Nothing here consults the CLI's device and OS enums
+ * (src/types/domain/device.types.ts) — those only feed `--help` — so a device
+ * or OS version the API adds is accepted without a CLI release, and one it
+ * withdraws is refused, before anything is uploaded, with the list the API
+ * offers today.
  */
 export declare class DeviceValidationService {
     /**