io.appium.settings 8.0.9 → 8.1.0

package/build/lib/utils/streaming-transport.js

@@ -0,0 +1,416 @@
+import net from 'node:net';
+import { retryInterval } from 'asyncbox';
+import { createParserState, parseFrames, StreamTrack } from './streaming-protocol.js';
+const DEFAULT_QUEUE_CAPACITY = 60;
+const CONNECT_TIMEOUT_MS = 5000;
+const CONNECT_RETRY_INTERVAL_MS = 200;
+// adb forward's host-side TCP listener accepts a connection immediately, independent of
+// whether the on-device local socket is bound yet; if it isn't, adb tears the connection
+// down right away with no data. Wait this long past 'connect' before trusting the socket.
+const CONNECT_VERIFY_GRACE_MS = 150;
+/**
+ * A bounded async-iterable queue that drops the oldest buffered item once its
+ * capacity is exceeded, so a slow consumer never causes unbounded memory growth.
+ * An optional `isProtected` predicate can shield items (e.g. video CONFIG frames)
+ * from eviction as long as any non-protected item remains to drop instead. An
+ * optional `dependencyChain` additionally makes eviction dependency-aware: dropping
+ * any chain member cascades to every following chain member up to (not including)
+ * the next sync point, and further chain-member pushes are discarded until a fresh
+ * sync point arrives - since anything in between is undecodable, buffering it only
+ * to have the consumer choke on it later isn't useful.
+ */
+export class BoundedFrameQueue {
+    capacity;
+    isProtected;
+    dependencyChain;
+    items = [];
+    waiters = [];
+    errorWaiters = [];
+    ended = false;
+    endError;
+    awaitingSyncPoint = false;
+    constructor(capacity = DEFAULT_QUEUE_CAPACITY, isProtected, dependencyChain) {
+        this.capacity = capacity;
+        this.isProtected = isProtected;
+        this.dependencyChain = dependencyChain;
+    }
+    /**
+     * Enqueues an item. If a consumer is already awaiting the next item, it is
+     * delivered directly; otherwise it is buffered, dropping the oldest droppable
+     * (non-protected) buffered item first if `capacity` would be exceeded. If a
+     * `dependencyChain` was given and a prior eviction broke it without a later sync
+     * point already buffered, chain-member items are silently discarded here until a
+     * fresh sync point item is pushed.
+     *
+     * @param item - The item to enqueue
+     */
+    push(item) {
+        if (this.ended) {
+            return;
+        }
+        const chain = this.dependencyChain;
+        if (this.awaitingSyncPoint && chain?.isChainMember(item)) {
+            if (!chain.isSyncPoint(item)) {
+                return;
+            }
+            this.awaitingSyncPoint = false;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            this.errorWaiters.shift();
+            waiter({ value: item, done: false });
+            return;
+        }
+        this.items.push(item);
+        while (this.items.length > this.capacity) {
+            this.evictOnce();
+        }
+    }
+    /**
+     * Marks the dependency chain (if configured) as broken by something outside this
+     * queue's own eviction - e.g. a producer detecting a sequence gap in items it never
+     * even offered here. The next chain-member item pushed is discarded unless it is
+     * itself a sync point, exactly as if a local eviction had cascaded off the end of
+     * the buffer. A no-op if no `dependencyChain` was configured.
+     */
+    notifyGap() {
+        if (this.dependencyChain) {
+            this.awaitingSyncPoint = true;
+        }
+    }
+    /**
+     * Evicts one item to bring the queue back under capacity: the oldest non-protected
+     * item, or (if every buffered item is protected, which should not happen in
+     * practice) the true oldest one regardless. If the evicted item was a
+     * `dependencyChain` member, cascades to drop every following chain member up to
+     * the next sync point, setting {@link awaitingSyncPoint} if none is found.
+     */
+    evictOnce() {
+        const isProtected = this.isProtected;
+        const index = isProtected ? this.items.findIndex((item) => !isProtected(item)) : 0;
+        if (index === -1) {
+            this.items.shift();
+            return;
+        }
+        const [evicted] = this.items.splice(index, 1);
+        const chain = this.dependencyChain;
+        if (chain?.isChainMember(evicted) && !this.dropDependentsFrom(index, chain)) {
+            this.awaitingSyncPoint = true;
+        }
+    }
+    /**
+     * Starting at `index`, removes chain-member items up to (not including) the next
+     * sync point, skipping over non-chain-member items (e.g. an interleaved audio
+     * track) in place without disturbing them.
+     *
+     * @returns True if a sync point was found (and kept), false if the scan reached
+     * the end of the buffer first
+     */
+    dropDependentsFrom(index, chain) {
+        while (index < this.items.length) {
+            const item = this.items[index];
+            if (!chain.isChainMember(item)) {
+                index++;
+                continue;
+            }
+            if (chain.isSyncPoint(item)) {
+                return true;
+            }
+            this.items.splice(index, 1);
+        }
+        return false;
+    }
+    /**
+     * Ends the queue. Any already-buffered items are still delivered first; once
+     * drained, the async iterator completes, rejecting with `error` if one is given.
+     * A no-op if the queue has already ended.
+     *
+     * @param error - Optional error to surface to the consumer once buffered items are drained
+     */
+    end(error) {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        this.endError = error;
+        for (;;) {
+            const waiter = this.waiters.shift();
+            const errorWaiter = this.errorWaiters.shift();
+            if (!waiter || !errorWaiter) {
+                return;
+            }
+            if (error) {
+                errorWaiter(error);
+            }
+            else {
+                waiter({ value: undefined, done: true });
+            }
+        }
+    }
+    next() {
+        if (this.items.length > 0) {
+            return Promise.resolve({ value: this.items.shift(), done: false });
+        }
+        if (this.ended) {
+            return this.endError ? Promise.reject(this.endError) : Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve, reject) => {
+            this.waiters.push(resolve);
+            this.errorWaiters.push(reject);
+        });
+    }
+    /**
+     * Async-iterates the queue, yielding items as they are pushed until {@link end} is called.
+     */
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            const result = await this.next();
+            if (result.done) {
+                return;
+            }
+            yield result.value;
+        }
+    }
+}
+/**
+ * Validates local-port selection options for a live stream session.
+ *
+ * @param opts - Options containing an optional localPort and/or localPortRange
+ * @throws {TypeError} If both localPort and localPortRange are provided, or either is malformed
+ */
+export function validateLocalPortOpts(opts) {
+    const { localPort, localPortRange } = opts;
+    if (localPort !== undefined && localPortRange !== undefined) {
+        throw new TypeError('Only one of localPort or localPortRange may be provided');
+    }
+    if (localPort !== undefined && (!Number.isInteger(localPort) || localPort < 1 || localPort > 65535)) {
+        throw new TypeError(`localPort must be an integer between 1 and 65535, got ${localPort}`);
+    }
+    if (localPortRange !== undefined) {
+        const [min, max] = localPortRange;
+        if (!Number.isInteger(min) || !Number.isInteger(max) || min < 1 || max > 65535 || min > max) {
+            throw new TypeError(`localPortRange must be a [min, max] tuple with 1 <= min <= max <= 65535, got [${min}, ${max}]`);
+        }
+    }
+}
+/**
+ * Tries to bind a local TCP server to `port` (0 lets the OS pick an ephemeral one),
+ * immediately closes it, and returns the bound port - or `null` if `port` is already
+ * in use (EADDRINUSE/EACCES), so the caller can try another candidate.
+ */
+async function tryBindPort(port) {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE' || err.code === 'EACCES') {
+                resolve(null);
+            }
+            else {
+                reject(err);
+            }
+        });
+        server.listen(port, '127.0.0.1', () => {
+            const address = server.address();
+            const boundPort = address && typeof address === 'object' ? address.port : null;
+            server.close(() => {
+                if (boundPort) {
+                    resolve(boundPort);
+                }
+                else {
+                    reject(new Error('Unable to determine a free local port'));
+                }
+            });
+        });
+    });
+}
+/**
+ * Resolves the local TCP port to use for the `adb forward` bridge: the exact
+ * `localPort` if given, the first free port in `localPortRange` if given, or an
+ * OS-assigned ephemeral port otherwise.
+ *
+ * @param opts - Port selection options; see {@link validateLocalPortOpts}
+ * @returns The bound, free local TCP port
+ * @throws {Error} If the requested port is busy, or no free port exists in the requested range
+ */
+export async function resolveLocalPort(opts) {
+    const { localPort, localPortRange } = opts;
+    if (localPort !== undefined) {
+        const bound = await tryBindPort(localPort);
+        if (bound === null) {
+            throw new Error(`Local port ${localPort} is already in use`);
+        }
+        return bound;
+    }
+    if (localPortRange) {
+        const [min, max] = localPortRange;
+        for (let port = min; port <= max; port++) {
+            const bound = await tryBindPort(port);
+            if (bound !== null) {
+                return bound;
+            }
+        }
+        throw new Error(`No free local port found in range ${min}-${max}`);
+    }
+    // No preference given - let the OS assign an ephemeral port.
+    const bound = await tryBindPort(0);
+    if (bound === null) {
+        throw new Error('Unable to determine a free local port');
+    }
+    return bound;
+}
+async function connectOnce(port) {
+    return new Promise((resolve, reject) => {
+        const socket = net.connect(port, '127.0.0.1');
+        let settled = false;
+        let verifyTimer;
+        const cleanup = () => {
+            socket.removeListener('error', onError);
+            socket.removeListener('close', onClose);
+            clearTimeout(verifyTimer);
+        };
+        const onError = (err) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            socket.destroy();
+            reject(err);
+        };
+        const onClose = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            reject(new Error('Connection was closed before the on-device stream became ready'));
+        };
+        socket.once('error', onError);
+        socket.once('close', onClose);
+        socket.once('connect', () => {
+            verifyTimer = setTimeout(() => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                resolve(socket);
+            }, CONNECT_VERIFY_GRACE_MS);
+        });
+    });
+}
+async function connectWithRetry(port, timeoutMs, intervalMs) {
+    const times = Math.max(1, Math.ceil(timeoutMs / intervalMs));
+    let socket;
+    try {
+        socket = await retryInterval(times, intervalMs, connectOnce, port);
+    }
+    catch (e) {
+        throw new Error(`Could not connect to the local streaming socket on port ${port} after ${times} attempts. ` +
+            `Last error: ${e instanceof Error ? e.message : e}`, { cause: e });
+    }
+    if (!socket) {
+        throw new Error(`Could not connect to the local streaming socket on port ${port}`);
+    }
+    return socket;
+}
+/**
+ * Bridges the on-device local abstract socket to the host over `adb forward`,
+ * parses the streaming wire protocol, and exposes the result as a bounded
+ * async-iterable frame queue.
+ */
+export class StreamTransport {
+    adb;
+    localPort;
+    socket;
+    // Config frames (e.g. video SPS/PPS) carry decoder state a consumer needs to make sense
+    // of everything that follows, so protect them from the bounded queue's drop-oldest policy.
+    // Non-config video frames form a decode-dependency chain (a delta frame is undecodable
+    // without every frame back to its last keyframe), so eviction there must cascade up to
+    // the next keyframe rather than leaving orphaned, undecodable frames behind - audio
+    // frames have no such dependency and are left alone by this either way.
+    queue = new BoundedFrameQueue(DEFAULT_QUEUE_CAPACITY, (frame) => frame.isConfig, {
+        isChainMember: (frame) => frame.track === StreamTrack.Video && !frame.isConfig,
+        isSyncPoint: (frame) => frame.isKeyFrame,
+    });
+    parserState = createParserState();
+    closed = false;
+    // Tracks the video track's shared sequence counter (CONFIG and data frames both draw
+    // from it) so a gap - meaning the on-device FrameQueue dropped a frame under
+    // backpressure before we ever saw it - can be detected on receipt, not just when our
+    // own queue evicts something locally.
+    lastVideoSequence;
+    constructor(adb, localPort, socket) {
+        this.adb = adb;
+        this.localPort = localPort;
+        this.socket = socket;
+    }
+    /**
+     * Resolves a local port, forwards it to the on-device local abstract socket via
+     * `adb forward`, and connects to it (retrying until the on-device session accepts).
+     * On failure, any port forward that was already set up is best-effort removed.
+     *
+     * @param adb - ADB instance for device communication
+     * @param socketName - Name of the on-device local abstract socket to forward
+     * @param portOpts - Optional local port selection options
+     * @returns A connected StreamTransport instance
+     * @throws {Error} If the local port cannot be resolved, or the connection fails
+     */
+    static async connect(adb, socketName, portOpts = {}) {
+        const localPort = await resolveLocalPort(portOpts);
+        await adb.forwardAbstractPort(localPort, socketName);
+        let socket;
+        try {
+            socket = await connectWithRetry(localPort, CONNECT_TIMEOUT_MS, CONNECT_RETRY_INTERVAL_MS);
+        }
+        catch (e) {
+            await adb.removePortForward(localPort).catch(() => { });
+            throw e;
+        }
+        const transport = new StreamTransport(adb, localPort, socket);
+        transport.wire();
+        return transport;
+    }
+    wire() {
+        this.socket.on('data', (chunk) => {
+            try {
+                for (const frame of parseFrames(this.parserState, chunk)) {
+                    if (frame.track === StreamTrack.Video) {
+                        if (this.lastVideoSequence !== undefined && frame.sequence !== this.lastVideoSequence + 1n) {
+                            this.queue.notifyGap();
+                        }
+                        this.lastVideoSequence = frame.sequence;
+                    }
+                    this.queue.push(frame);
+                }
+            }
+            catch (e) {
+                this.queue.end(e instanceof Error ? e : new Error(String(e)));
+                this.socket.destroy();
+            }
+        });
+        this.socket.on('close', () => this.queue.end());
+        this.socket.on('error', (err) => this.queue.end(err));
+    }
+    /**
+     * Returns an async generator yielding parsed frames as they arrive on the socket,
+     * until the connection closes or errors.
+     */
+    frames() {
+        return this.queue[Symbol.asyncIterator]();
+    }
+    /**
+     * Destroys the client socket and best-effort removes the `adb forward` port
+     * mapping. Safe to call more than once.
+     */
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.socket.destroy();
+        await this.adb.removePortForward(this.localPort).catch(() => { });
+    }
+}
+//# sourceMappingURL=streaming-transport.js.map

package/build/lib/utils/streaming-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-transport.js","sourceRoot":"","sources":["../../../lib/utils/streaming-transport.ts"],"names":[],"mappings":"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"}

package/lib/client.ts

@@ -6,6 +6,7 @@ import {setAnimationState} from './commands/animation.js';
 import {setBluetoothState, unpairAllBluetoothDevices} from './commands/bluetooth.js';
 import {getClipboard} from './commands/clipboard.js';
 import {setGeoLocation, getGeoLocation, refreshGeoLocationCache} from './commands/geolocation.js';
+import {makeJpegStreamSession} from './commands/jpeg-stream.js';
 import {setDeviceLocale, listSupportedLocales} from './commands/locale.js';
 import {makeMediaProjectionRecorder, adjustMediaProjectionServicePermissions} from './commands/media-projection.js';
 import {scanMedia} from './commands/media.js';
@@ -13,6 +14,7 @@ import {setDataState, setWifiState} from './commands/network.js';
 import {getNotifications, adjustNotificationsPermissions} from './commands/notifications.js';
 import {getSmsList} from './commands/sms.js';
 import {performEditorAction, typeUnicode} from './commands/typing.js';
+import {makeVideoStreamSession} from './commands/video-stream.js';
 import {SETTINGS_HELPER_ID, SETTINGS_HELPER_MAIN_ACTIVITY} from './constants.js';
 import {log, LOG_PREFIX} from './logger.js';
 
@@ -62,6 +64,9 @@ export class SettingsApp {
   makeMediaProjectionRecorder = makeMediaProjectionRecorder;
   adjustMediaProjectionServicePermissions = adjustMediaProjectionServicePermissions;
 
+  makeJpegStreamSession = makeJpegStreamSession;
+  makeVideoStreamSession = makeVideoStreamSession;
+
   constructor(opts: SettingsAppOpts) {
     this.adb = opts.adb;
     this.log = log;

package/lib/commands/clipboard.ts

@@ -33,6 +33,7 @@ export async function getClipboard(this: SettingsApp): Promise<string> {
       `Cannot retrieve the current clipboard content from the device. ` +
         `Make sure the Appium Settings application is up to date. ` +
         `Original error: ${err.message}`,
+      {cause: err},
     );
   }
 

package/lib/commands/jpeg-stream.ts

@@ -0,0 +1,171 @@
+import {randomUUID} from 'node:crypto';
+
+import type {ADB} from 'appium-adb';
+import {waitForCondition} from 'asyncbox';
+
+import type {SettingsApp} from '../client.js';
+import {
+  JPEG_STREAM_ACTION_START,
+  JPEG_STREAM_ACTION_STOP,
+  JPEG_STREAM_SERVICE_NAME,
+  SETTINGS_HELPER_ID,
+  STREAMING_ACTIVITY_NAME,
+} from '../constants.js';
+import {StreamTransport, validateLocalPortOpts} from '../utils/index.js';
+import type {JpegFrame, StartJpegStreamOpts} from './types.js';
+
+const STREAM_STARTUP_TIMEOUT_MS = 3 * 1000;
+const STREAM_STOP_TIMEOUT_MS = 3 * 1000;
+
+/**
+ * Creates a new instance of the live JPEG frame streaming session.
+ * The stream only works since Android API 29+
+ *
+ * @returns The streaming session instance
+ */
+export function makeJpegStreamSession(this: SettingsApp): JpegStreamSession {
+  return new JpegStreamSession(this.adb);
+}
+
+function validateJpegStreamOpts(opts: StartJpegStreamOpts): void {
+  const {fps, quality, scale} = opts;
+  if (fps !== undefined && (!Number.isInteger(fps) || fps <= 0)) {
+    throw new TypeError(`fps must be a positive integer, got ${fps}`);
+  }
+  if (quality !== undefined && (!Number.isInteger(quality) || quality < 1 || quality > 100)) {
+    throw new TypeError(`quality must be an integer between 1 and 100, got ${quality}`);
+  }
+  if (scale !== undefined && (!Number.isInteger(scale) || scale < 1 || scale > 100)) {
+    throw new TypeError(`scale must be an integer between 1 and 100, got ${scale}`);
+  }
+  validateLocalPortOpts(opts);
+}
+
+/**
+ * Live JPEG frame streaming session for the device screen.
+ * This class provides methods to start, stop, and consume a continuous
+ * sequence of JPEG-encoded frames over a local socket (API 29+).
+ */
+export class JpegStreamSession {
+  private transport: StreamTransport | null = null;
+
+  /**
+   * Creates a new JpegStreamSession instance.
+   *
+   * @param adb - ADB instance for device communication
+   */
+  constructor(private readonly adb: ADB) {}
+
+  /**
+   * Checks if the JPEG stream is currently running.
+   */
+  async isRunning(): Promise<boolean> {
+    const stdout = await this.adb.shell(['dumpsys', 'activity', 'services', JPEG_STREAM_SERVICE_NAME]);
+    return stdout.includes(JPEG_STREAM_SERVICE_NAME);
+  }
+
+  /**
+   * Starts the live JPEG frame stream.
+   * If a stream is already running, this method returns false without starting a new one.
+   *
+   * @param opts Streaming options including fps, quality, scale, and the local port to use
+   * @returns True if the stream was started successfully, false if already running
+   * @throws {Error} If the stream fails to start within the timeout period
+   */
+  async start(opts: StartJpegStreamOpts = {}): Promise<boolean> {
+    validateJpegStreamOpts(opts);
+    if (await this.isRunning()) {
+      return false;
+    }
+
+    const {fps, quality, scale, localPort, localPortRange} = opts;
+    // Socket names are validated on-device against ^[a-zA-Z0-9._-]{1,200}$, so this
+    // must not contain a "/" - unlike JPEG_STREAM_SERVICE_NAME.
+    const socketName = `${SETTINGS_HELPER_ID}.jpegstream.${randomUUID()}`;
+    const args = [
+      'am',
+      'start',
+      '-n',
+      STREAMING_ACTIVITY_NAME,
+      '-a',
+      JPEG_STREAM_ACTION_START,
+      '--es',
+      'socket_name',
+      socketName,
+    ];
+    if (fps) {
+      args.push('--es', 'fps', `${fps}`);
+    }
+    if (quality) {
+      args.push('--es', 'quality', `${quality}`);
+    }
+    if (scale) {
+      args.push('--es', 'scale', `${scale}`);
+    }
+
+    await this.adb.shell(args);
+    try {
+      await waitForCondition(async () => await this.isRunning(), {
+        waitMs: STREAM_STARTUP_TIMEOUT_MS,
+        intervalMs: 300,
+      });
+    } catch {
+      throw new Error(
+        `The JPEG stream is not running after ${STREAM_STARTUP_TIMEOUT_MS}ms. ` +
+          `Please check the logcat output for more details.`,
+      );
+    }
+
+    this.transport = await StreamTransport.connect(this.adb, socketName, {localPort, localPortRange});
+    return true;
+  }
+
+  /**
+   * Yields JPEG frames as they arrive from the device.
+   * `start()` must be called before iterating.
+   */
+  async *frames(): AsyncGenerator<JpegFrame> {
+    if (!this.transport) {
+      throw new Error('The JPEG stream has not been started. Call start() first.');
+    }
+    for await (const frame of this.transport.frames()) {
+      yield {
+        data: frame.data,
+        sequence: Number(frame.sequence),
+        timestampMicros: Number(frame.timestampMicros),
+      };
+    }
+  }
+
+  /**
+   * Stops the currently running JPEG stream.
+   *
+   * @returns True if the stream was stopped successfully, false if it was not running
+   * @throws {Error} If the stream fails to stop within the timeout period
+   */
+  async stop(): Promise<boolean> {
+    try {
+      if (!(await this.isRunning())) {
+        // The on-device service may have already stopped itself (e.g. the client
+        // disconnected), leaving a local transport/adb-forward that still needs closing.
+        return false;
+      }
+
+      await this.adb.shell(['am', 'start', '-n', STREAMING_ACTIVITY_NAME, '-a', JPEG_STREAM_ACTION_STOP]);
+      try {
+        await waitForCondition(async () => !(await this.isRunning()), {
+          waitMs: STREAM_STOP_TIMEOUT_MS,
+          intervalMs: 300,
+        });
+      } catch {
+        throw new Error(`The attempt to stop the current JPEG stream timed out after ${STREAM_STOP_TIMEOUT_MS}ms`);
+      }
+      return true;
+    } finally {
+      if (this.transport) {
+        await this.transport.close();
+        this.transport = null;
+      }
+    }
+  }
+}

package/lib/commands/media-projection.ts

@@ -48,16 +48,12 @@ const RECORDINGS_ROOT = `/storage/emulated/0/Android/data/${SETTINGS_HELPER_ID}/
  * using Android's MediaProjection API (API 29+).
  */
 export class MediaProjectionRecorder {
-  private readonly adb: ADB;
-
   /**
    * Creates a new MediaProjectionRecorder instance.
    *
    * @param adb - ADB instance for device communication
    */
-  constructor(adb: ADB) {
-    this.adb = adb;
-  }
+  constructor(private readonly adb: ADB) {}
 
   /**
    * Checks if the recording is currently running.

package/lib/commands/media.ts

@@ -13,7 +13,7 @@ import {LOG_PREFIX} from '../logger.js';
 export async function scanMedia(this: SettingsApp, destination: string): Promise<void> {
   this.log.debug(LOG_PREFIX, `Scanning '${destination}' for media files`);
   await this.checkBroadcast(
-    ['-n', MEDIA_SCAN_RECEIVER, '-a', MEDIA_SCAN_ACTION, '--es', 'path', destination],
+    ['-n', MEDIA_SCAN_RECEIVER, '-a', MEDIA_SCAN_ACTION, '--es', 'path', `'${destination.replace(/'/g, `'"'"'`)}'`],
     'scan media',
   );
 }

package/lib/commands/network.ts

@@ -51,7 +51,7 @@ export async function setDataState(this: SettingsApp, on: boolean, isEmulator =
     try {
       await this.adb.shell(['cmd', 'phone', 'data', on ? 'enable' : 'disable']);
     } catch (e: any) {
-      throw new Error(`Cannot change the data state. Original error: ${e.stderr || e.message}`);
+      throw new Error(`Cannot change the data state. Original error: ${e.stderr || e.message}`, {cause: e});
     }
   }
 }