@devicecloud.dev/dcd 5.5.0 → 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";
@@ -98,6 +98,11 @@ export declare const cloudCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly description: "Pull request URL for this run (stored as gh_pr_url metadata)";
     };
+    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: 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";
         readonly description: "Path to custom config.yaml file. If not provided, defaults to config.yaml in root flows folders.";
@@ -206,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';
@@ -132,6 +132,7 @@ export const cloudCommand = defineCommand({
             const excludeFlows = coerceArray(collectRepeatedFlag(rawArgs, ['--exclude-flows']));
             const excludeTags = coerceArray(collectRepeatedFlag(rawArgs, ['--exclude-tags']));
             let flows = args.flows;
+            const cancelPrevious = Boolean(args['cancel-previous']);
             const googlePlay = Boolean(args['google-play']);
             const ignoreShaCheck = Boolean(args['ignore-sha-check']);
             // Single opt-in for client-side envelope encryption of every sensitive
@@ -139,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']);
@@ -163,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'];
@@ -401,15 +408,22 @@ export const cloudCommand = defineCommand({
                 }
                 throw error;
             }
-            const { allExcludeTags, allIncludeTags, flowMetadata, flowOverrides, flowsToRun: testFileNames, referencedFiles, sequence, } = executionPlan;
+            const { allExcludeTags, allIncludeTags, flowMetadata, flowOverrides, flowsToRun: testFileNames, includedFiles, referencedFiles, sequence, } = executionPlan;
             if (debug) {
                 out(`[DEBUG] All include tags: ${allIncludeTags?.join(', ') || 'none'}`);
                 out(`[DEBUG] All exclude tags: ${allExcludeTags?.join(', ') || 'none'}`);
                 out(`[DEBUG] Test file names: ${testFileNames.join(', ')}`);
             }
-            const commonRoot = computeCommonRoot(testFileNames, referencedFiles);
+            const commonRoot = computeCommonRoot(testFileNames, referencedFiles, includedFiles);
             if (debug) {
                 out(`[DEBUG] Common root directory: ${commonRoot}`);
+                // `includedPaths` files sitting beside the flows tree rather than
+                // inside it raise the common root, so every server-side flow key gains
+                // a leading segment. Harmless but visible in the console, so say it.
+                const rootWithoutIncludes = computeCommonRoot(testFileNames, referencedFiles);
+                if (includedFiles.length > 0 && rootWithoutIncludes !== commonRoot) {
+                    out(`[DEBUG] \`includedPaths\` raised the common root from ${rootWithoutIncludes} to ${commonRoot} — flow paths gain a leading segment`);
+                }
             }
             const testMetadataMap = buildTestMetadataMap(flowMetadata, commonRoot);
             if (debug) {
@@ -549,6 +563,9 @@ 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,
                 continueOnFailure,

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

@@ -2,6 +2,11 @@
  * Test execution and flow management flags
  */
 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: 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";
         readonly description: "Path to custom config.yaml file. If not provided, defaults to config.yaml in root flows folders.";

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

@@ -2,6 +2,11 @@
  * Test execution and flow management flags
  */
 export const executionFlags = {
+    'cancel-previous': {
+        type: 'boolean',
+        default: false,
+        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',
         description: 'Path to custom config.yaml file. If not provided, defaults to config.yaml in root flows folders.',

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";
@@ -84,6 +84,11 @@ export declare const flags: {
         readonly type: "string";
         readonly description: "Pull request URL for this run (stored as gh_pr_url metadata)";
     };
+    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: 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";
         readonly description: "Path to custom config.yaml file. If not provided, defaults to config.yaml in root flows folders.";
@@ -192,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 () => {