digital-ai-testing-mcp 2.2.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/README.md +28 -16
  2. package/dist/api/browser-events.d.ts +48 -0
  3. package/dist/api/browser-events.d.ts.map +1 -0
  4. package/dist/api/browser-events.js +155 -0
  5. package/dist/api/browser-events.js.map +1 -0
  6. package/dist/api/browser-inspection.d.ts +21 -0
  7. package/dist/api/browser-inspection.d.ts.map +1 -1
  8. package/dist/api/browser-inspection.js +113 -20
  9. package/dist/api/browser-inspection.js.map +1 -1
  10. package/dist/api/playwright-runs.d.ts +42 -0
  11. package/dist/api/playwright-runs.d.ts.map +1 -0
  12. package/dist/api/playwright-runs.js +207 -0
  13. package/dist/api/playwright-runs.js.map +1 -0
  14. package/dist/api/reporting.d.ts.map +1 -1
  15. package/dist/api/reporting.js +4 -2
  16. package/dist/api/reporting.js.map +1 -1
  17. package/dist/api/repository.d.ts +13 -1
  18. package/dist/api/repository.d.ts.map +1 -1
  19. package/dist/api/repository.js +39 -4
  20. package/dist/api/repository.js.map +1 -1
  21. package/dist/api/test-runs.d.ts +5 -0
  22. package/dist/api/test-runs.d.ts.map +1 -1
  23. package/dist/api/test-runs.js.map +1 -1
  24. package/dist/api/webdriver.d.ts +23 -2
  25. package/dist/api/webdriver.d.ts.map +1 -1
  26. package/dist/api/webdriver.js +142 -13
  27. package/dist/api/webdriver.js.map +1 -1
  28. package/dist/index.js +1 -1
  29. package/dist/tools/boilerplate-tools.d.ts +22 -0
  30. package/dist/tools/boilerplate-tools.d.ts.map +1 -1
  31. package/dist/tools/boilerplate-tools.js +323 -44
  32. package/dist/tools/boilerplate-tools.js.map +1 -1
  33. package/dist/tools/device-group-tools.js +2 -2
  34. package/dist/tools/device-group-tools.js.map +1 -1
  35. package/dist/tools/device-tools.js +3 -3
  36. package/dist/tools/device-tools.js.map +1 -1
  37. package/dist/tools/inspection-tools.d.ts +24 -0
  38. package/dist/tools/inspection-tools.d.ts.map +1 -1
  39. package/dist/tools/inspection-tools.js +129 -13
  40. package/dist/tools/inspection-tools.js.map +1 -1
  41. package/dist/tools/meta-tools.d.ts +1 -1
  42. package/dist/tools/meta-tools.d.ts.map +1 -1
  43. package/dist/tools/meta-tools.js +3 -2
  44. package/dist/tools/meta-tools.js.map +1 -1
  45. package/dist/tools/prompt-tools.d.ts.map +1 -1
  46. package/dist/tools/prompt-tools.js +4 -0
  47. package/dist/tools/prompt-tools.js.map +1 -1
  48. package/dist/tools/reporting-tools.d.ts.map +1 -1
  49. package/dist/tools/reporting-tools.js +27 -8
  50. package/dist/tools/reporting-tools.js.map +1 -1
  51. package/dist/tools/repository-tools.d.ts.map +1 -1
  52. package/dist/tools/repository-tools.js +5 -3
  53. package/dist/tools/repository-tools.js.map +1 -1
  54. package/dist/tools/test-run-tools.d.ts.map +1 -1
  55. package/dist/tools/test-run-tools.js +107 -6
  56. package/dist/tools/test-run-tools.js.map +1 -1
  57. package/dist/tools/usage-report-tools.d.ts.map +1 -1
  58. package/dist/tools/usage-report-tools.js +6 -4
  59. package/dist/tools/usage-report-tools.js.map +1 -1
  60. package/dist/tools/web-inspection-tools.d.ts.map +1 -1
  61. package/dist/tools/web-inspection-tools.js +116 -13
  62. package/dist/tools/web-inspection-tools.js.map +1 -1
  63. package/dist/types/digital-ai.d.ts +6 -1
  64. package/dist/types/digital-ai.d.ts.map +1 -1
  65. package/dist/utils/adb-shell.d.ts +25 -0
  66. package/dist/utils/adb-shell.d.ts.map +1 -0
  67. package/dist/utils/adb-shell.js +87 -0
  68. package/dist/utils/adb-shell.js.map +1 -0
  69. package/dist/utils/credential-env.d.ts +36 -0
  70. package/dist/utils/credential-env.d.ts.map +1 -0
  71. package/dist/utils/credential-env.js +57 -0
  72. package/dist/utils/credential-env.js.map +1 -0
  73. package/dist/utils/failure-triage.d.ts +13 -0
  74. package/dist/utils/failure-triage.d.ts.map +1 -0
  75. package/dist/utils/failure-triage.js +53 -0
  76. package/dist/utils/failure-triage.js.map +1 -0
  77. package/dist/utils/locator-recommend.d.ts +27 -0
  78. package/dist/utils/locator-recommend.d.ts.map +1 -0
  79. package/dist/utils/locator-recommend.js +59 -0
  80. package/dist/utils/locator-recommend.js.map +1 -0
  81. package/dist/utils/response-formatter.d.ts +8 -0
  82. package/dist/utils/response-formatter.d.ts.map +1 -1
  83. package/dist/utils/response-formatter.js +26 -0
  84. package/dist/utils/response-formatter.js.map +1 -1
  85. package/dist/utils/usage-report-summary.d.ts +2 -0
  86. package/dist/utils/usage-report-summary.d.ts.map +1 -1
  87. package/dist/utils/usage-report-summary.js +5 -1
  88. package/dist/utils/usage-report-summary.js.map +1 -1
  89. package/package.json +13 -6
  90. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  91. package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +3 -2
  92. package/resources/boilerplate/Android-Native/Python/pip-oss +1 -1
  93. package/resources/boilerplate/Android-Native/Robot Framework/AndroidNative-oss.robot +1 -1
  94. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  95. package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +3 -2
  96. package/resources/boilerplate/iOS-Native/Python/pip-oss.txt +1 -1
  97. package/resources/boilerplate/iOS-Native/Robot Framework/iOSNative-oss.robot +1 -1
@@ -4,6 +4,7 @@ import { getMyAccountInfo } from './users.js';
4
4
  import { getActiveUrl, getActiveAccessKey } from './client.js';
5
5
  import { checkDeleteAllowed } from './access-level.js';
6
6
  import { isEmulatorQuery } from '../utils/device-query.js';
7
+ import { stopBrowserEventCapture } from './browser-events.js';
7
8
  // In-process session registry — cleared on MCP server restart
8
9
  const sessionRegistry = new Map();
9
10
  // All report IDs created this process lifetime, mapped to the project name they
@@ -150,11 +151,23 @@ export async function createInspectionSession(opts) {
150
151
  // so the start is remembered and cleanup_inspection_sessions sweeps whatever it left (sweepTimedOutStarts).
151
152
  if (/timeout of \d+ms exceeded/i.test(detail)) {
152
153
  timedOutStarts.push({ testName, projectName, requestedAt });
153
- throw new Error(`Session creation failed: no answer from the platform within ${Math.round(timeout / 1000)} s. ` +
154
- `Emulators/simulators boot and install the app inside this request and can take 60–130 s or more; ` +
155
- `set INSPECTION_SESSION_TIMEOUT_MS (ms) in the MCP server's environment to wait longer. ` +
154
+ const timeouts = (timedOutQueries.get(query) ?? 0) + 1;
155
+ timedOutQueries.set(query, timeouts);
156
+ // The old text only said "wait longer", so the agent repeated the identical start for another 240 s; the platform
157
+ // then answered at ~516 s with "Failed to boot emulator" (debug-mode intake 2026-10-19). Say the start can still
158
+ // fail and steer away from an identical retry.
159
+ const emulator = isEmulatorQuery(query);
160
+ throw new Error((timeouts > 1 ? `This query has now timed out ${timeouts} times in this session — do not retry it unchanged. ` : '') +
161
+ `Session creation failed: no answer from the platform within ${Math.round(timeout / 1000)} s. ` +
162
+ (emulator
163
+ ? `Emulators/simulators boot and install the app inside this request and can take 60–130 s or more, but one ` +
164
+ `that has not answered by now may also fail to boot (seen live: "Failed to boot emulator" after ~8.5 min). ` +
165
+ `Rather than repeating the same query, try another emulator model or OS version (list_virtual_device_templates) or a real device. `
166
+ : `The platform may still be waiting on the device or fail the start; rather than repeating the same query, widen it or pick another device. `) +
167
+ `To wait longer instead, set INSPECTION_SESSION_TIMEOUT_MS (ms) in the MCP server's environment. ` +
156
168
  `The platform may still finish this start: the session would then hold the device unattended until its idle ` +
157
- `timeout (~4 min) and leave a report "${testName}" — run cleanup_inspection_sessions afterwards to delete it.`);
169
+ `timeout (~4 min) and leave a report "${testName}" (its status and cause show the platform's final outcome — ` +
170
+ `find_latest_test_for_name) — run cleanup_inspection_sessions afterwards to delete it.`);
158
171
  }
159
172
  // A start that fails after a device was allocated still leaves an "Error" report (UAT 2026-10-10: five of them).
160
173
  const leftover = await cleanUpFailedSessionReport(testName, projectName, requestedAt);
@@ -223,6 +236,7 @@ export async function createInspectionSession(opts) {
223
236
  }
224
237
  export async function quitInspectionSession(handle, keepReport = false) {
225
238
  const session = requireSession(handle);
239
+ stopBrowserEventCapture(handle); // browser sessions: close the BiDi socket (no-op otherwise)
226
240
  const client = makeClient();
227
241
  // A HAR / device-log capture left running would never be finalised once the session is gone — stop it first
228
242
  // (best-effort: the session may already be dead).
@@ -240,6 +254,18 @@ export async function quitInspectionSession(handle, keepReport = false) {
240
254
  }
241
255
  session[field] = undefined;
242
256
  }
257
+ // A simulated location outlives the session on the device (iOS keeps it until resetSimulatedLocation) — the next
258
+ // user of a shared phone would inherit it. Reset it before quitting (best-effort).
259
+ let geolocationReset;
260
+ if (session.geolocationSet) {
261
+ try {
262
+ await resetGeolocation(handle);
263
+ geolocationReset = true;
264
+ }
265
+ catch {
266
+ geolocationReset = false;
267
+ }
268
+ }
243
269
  try {
244
270
  await client.delete(`/session/${session.gridSessionId}`, { timeout: 30_000 });
245
271
  }
@@ -281,6 +307,7 @@ export async function quitInspectionSession(handle, keepReport = false) {
281
307
  canDeleteReport: session.canDeleteReport,
282
308
  reportTestId: session.reportTestId,
283
309
  reportUrl: session.reportUrl,
310
+ ...(geolocationReset !== undefined ? { geolocationReset } : {}),
284
311
  };
285
312
  }
286
313
  export async function captureScreenshot(handle) {
@@ -370,7 +397,10 @@ const rectToBounds = (r) => {
370
397
  const o = r;
371
398
  if (!o || o.x == null || o.width == null)
372
399
  return null;
373
- return `[${o.x},${o.y}][${o.x + o.width},${(o.y ?? 0) + (o.height ?? 0)}]`;
400
+ // Web elements report fractional CSS pixels (e.g. 165.23809814453125) — round for readability.
401
+ const n = (v) => Math.round(v);
402
+ const y = o.y ?? 0;
403
+ return `[${n(o.x)},${n(y)}][${n(o.x + o.width)},${n(y + (o.height ?? 0))}]`;
374
404
  };
375
405
  const asBool = (v) => (v === true || v === 'true' ? true : v === false || v === 'false' ? false : null);
376
406
  const asStr = (v) => (v == null ? null : String(v));
@@ -385,7 +415,9 @@ export async function findElements(handle, using, value, opts = {}) {
385
415
  const client = makeClient();
386
416
  const sid = session.gridSessionId;
387
417
  const inline = await ensureInlineAttributes(client, session);
388
- const inWebview = isWebviewContext(session);
418
+ // Browser sessions (desktop or a phone's browser) hold web elements too — read them the web way. They used to fall
419
+ // through to the Android native branch (class/resource-id/text attributes), which gave null text on Android Chrome.
420
+ const inWebview = isWebviewContext(session) || session.platform === 'web';
389
421
  let res;
390
422
  try {
391
423
  res = await client.post(`/session/${sid}/elements`, { using, value },
@@ -798,10 +830,31 @@ export async function swipeScreen(handle, startX, startY, endX, endY, durationMs
798
830
  }, { timeout: 30_000 });
799
831
  return gestureWithFallback(session, w3c, jwp);
800
832
  }
801
- export async function launchApp(handle, packageName, activity) {
833
+ export async function launchApp(handle, packageName, activity, launchArguments) {
802
834
  const session = requireSession(handle);
803
835
  const client = makeClient();
804
836
  const sid = session.gridSessionId;
837
+ // iOS launch arguments (e.g. -AppleLanguages (de), feature flags) — XCUITest `mobile: launchApp {arguments}`. A RUNNING
838
+ // app ignores them (verified live 2026-11-12, iOS 26.6: Settings stayed French), so the app is terminated first;
839
+ // after the terminate the same call opened Settings in German. Appium Server only — the Grid has no equivalent.
840
+ if (launchArguments && launchArguments.length > 0) {
841
+ if (session.platform !== 'ios')
842
+ throw new Error('launchArguments is iOS only. On Android, pass extras through the activity intent or a deep link.');
843
+ if (session.sessionFormat !== 'w3c')
844
+ throw new Error('launchArguments needs an Appium Server session; Appium Grid has no launch-arguments command.');
845
+ try {
846
+ await client.post(`/session/${sid}/execute/sync`, { script: 'mobile: terminateApp', args: [{ bundleId: packageName }] }, { timeout: 30_000 });
847
+ }
848
+ catch { /* not running — fine */ }
849
+ try {
850
+ await client.post(`/session/${sid}/execute/sync`, { script: 'mobile: launchApp', args: [{ bundleId: packageName, arguments: launchArguments }] }, { timeout: 30_000 });
851
+ }
852
+ catch (e) {
853
+ // Same shape as the other launch paths: the driver's own message, not a bare "status code 500".
854
+ throw new Error(`Could not launch ${packageName} with arguments: mobile: launchApp → ${describeWdError(e)}`);
855
+ }
856
+ return `Relaunched ${packageName} with arguments ${JSON.stringify(launchArguments)} via mobile: launchApp (terminated first — a running app ignores launch arguments)`;
857
+ }
805
858
  const errors = [];
806
859
  const tryAll = async (mechanisms) => {
807
860
  for (const [desc, fn] of mechanisms) {
@@ -1186,6 +1239,46 @@ export async function doubleTap(handle, opts) {
1186
1239
  }, { timeout: 30_000 });
1187
1240
  await gestureWithFallback(session, w3c, jwp);
1188
1241
  }
1242
+ /** Single tap at a screen point — W3C pointer actions, JWP touch/perform on the Grid (same fallback as doubleTap). */
1243
+ export async function tapAt(handle, x, y) {
1244
+ const session = requireSession(handle);
1245
+ const client = makeClient();
1246
+ const sid = session.gridSessionId;
1247
+ const jwp = () => client.post(`/session/${sid}/touch/perform`, { actions: [{ action: 'tap', options: { x, y } }] }, { timeout: 30_000 });
1248
+ const w3c = () => client.post(`/session/${sid}/actions`, {
1249
+ actions: [{
1250
+ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' },
1251
+ actions: [
1252
+ { type: 'pointerMove', duration: 0, x, y },
1253
+ { type: 'pointerDown', button: 0 },
1254
+ { type: 'pause', duration: 80 },
1255
+ { type: 'pointerUp', button: 0 },
1256
+ ],
1257
+ }],
1258
+ }, { timeout: 30_000 });
1259
+ await gestureWithFallback(session, w3c, jwp);
1260
+ }
1261
+ /**
1262
+ * Android app runtime permissions (Appium Server, UiAutomator2 — verified live 2026-11-12 on a Pixel 7 / Android 14):
1263
+ * mobile: getPermissions {type, appPackage} lists requested / granted / denied; mobile: changePermissions grants or
1264
+ * revokes. Only permissions the app declares can change (granting an undeclared CAMERA was a silent no-op), and
1265
+ * REVOKING kills the app process — Android does that to any app whose permission is revoked.
1266
+ */
1267
+ export async function appPermissions(handle, action, appPackage, permissions = []) {
1268
+ const session = requireSession(handle);
1269
+ if (session.platform !== 'android' || session.sessionFormat !== 'w3c') {
1270
+ throw new Error('Permissions are an Android Appium Server feature (mobile: getPermissions / changePermissions). On iOS the system dialog is a normal alert — use device_control accept_alert / dismiss_alert.');
1271
+ }
1272
+ const client = makeClient();
1273
+ if (action !== 'list') {
1274
+ await execScript(client, session, 'mobile: changePermissions', [{ permissions, appPackage, action }], 30_000);
1275
+ }
1276
+ const get = async (type) => {
1277
+ const r = await execScript(client, session, 'mobile: getPermissions', [{ type, appPackage }], 30_000);
1278
+ return Array.isArray(r.data.value) ? r.data.value : [];
1279
+ };
1280
+ return { requested: await get('requested'), granted: await get('granted'), denied: await get('denied') };
1281
+ }
1189
1282
  export async function dragAndDrop(handle, startX, startY, endX, endY, holdMs = 600, moveMs = 1200) {
1190
1283
  const session = requireSession(handle);
1191
1284
  const client = makeClient();
@@ -1358,10 +1451,13 @@ const IOS_BUTTONS = {
1358
1451
  VOLUME_DOWN: { w3c: 'volumedown', grid: 'Volume Down' },
1359
1452
  POWER: { w3c: null, grid: 'Lock' },
1360
1453
  };
1361
- export async function pressKey(handle, key, keycode) {
1454
+ export async function pressKey(handle, key, keycode, longPress = false) {
1362
1455
  const session = requireSession(handle);
1363
1456
  const client = makeClient();
1364
1457
  const sid = session.gridSessionId;
1458
+ if (longPress && (session.platform === 'ios' || session.sessionFormat !== 'w3c')) {
1459
+ throw new Error('longPress is available on Android Appium Server sessions only (mobile: pressKey isLongPress).');
1460
+ }
1365
1461
  if (session.platform === 'ios') {
1366
1462
  const button = key ? IOS_BUTTONS[key] : undefined;
1367
1463
  if (!button) {
@@ -1399,7 +1495,12 @@ export async function pressKey(handle, key, keycode) {
1399
1495
  throw new Error('Provide a named key or an Android keycode.');
1400
1496
  // Confirmed live: the Grid routes the legacy press_keycode endpoint.
1401
1497
  const jwp = () => client.post(`/session/${sid}/appium/device/press_keycode`, { keycode: code }, { timeout: 15_000 });
1402
- const w3c = () => execScript(client, session, 'mobile: pressKey', [{ keycode: code }]);
1498
+ // isLongPress verified live 2026-11-12: a long HOME opened Google Assistant on a Galaxy S21 (Android 12).
1499
+ const w3c = () => execScript(client, session, 'mobile: pressKey', [longPress ? { keycode: code, isLongPress: true } : { keycode: code }]);
1500
+ if (longPress) {
1501
+ await w3c();
1502
+ return `${key ?? `keycode ${code}`} (long press)`;
1503
+ }
1403
1504
  const [primary, fallback] = session.sessionFormat === 'w3c' ? [w3c, jwp] : [jwp, w3c];
1404
1505
  try {
1405
1506
  await primary();
@@ -1577,9 +1678,11 @@ export async function appControl(handle, action, packageName, url, opts = {}) {
1577
1678
  throw new Error('deep_link requires url.');
1578
1679
  if (isW3c) {
1579
1680
  const args = { url };
1580
- // Android needs the handler package; iOS routes through the system.
1581
- if (packageName && !isIos)
1582
- args['package'] = packageName;
1681
+ // Android: the handler package. iOS: the bundle id of the app that should open it — com.apple.mobilesafari
1682
+ // opens a web URL straight in Safari with no "Open in …?" prompt (verified live 2026-11-12, iOS 26.6), so no
1683
+ // address-bar typing is needed.
1684
+ if (packageName)
1685
+ args[isIos ? 'bundleId' : 'package'] = packageName;
1583
1686
  await execScript(client, session, 'mobile: deepLink', [args]);
1584
1687
  return `Opened deep link ${url}.`;
1585
1688
  }
@@ -1651,6 +1754,7 @@ export async function setGeolocation(handle, latitude, longitude) {
1651
1754
  // setSimulatedLocation; UiAutomator2 uses setGeolocation — both confirmed live.
1652
1755
  const script = session.platform === 'ios' ? 'mobile: setSimulatedLocation' : 'mobile: setGeolocation';
1653
1756
  await execScript(client, session, script, [{ latitude, longitude }]);
1757
+ session.geolocationSet = true;
1654
1758
  return;
1655
1759
  }
1656
1760
  // Confirmed live on the Grid (both platforms): seetest:client.setLocation, string args.
@@ -1658,6 +1762,7 @@ export async function setGeolocation(handle, latitude, longitude) {
1658
1762
  String(latitude),
1659
1763
  String(longitude),
1660
1764
  ]);
1765
+ session.geolocationSet = true;
1661
1766
  }
1662
1767
  export async function resetGeolocation(handle) {
1663
1768
  const session = requireSession(handle);
@@ -1665,10 +1770,12 @@ export async function resetGeolocation(handle) {
1665
1770
  if (session.sessionFormat === 'jwp') {
1666
1771
  // seetest:client.clearLocation() — inline 0-arg form (execScript adds the parentheses on the Grid).
1667
1772
  await execScript(client, session, 'seetest:client.clearLocation', []);
1773
+ session.geolocationSet = false;
1668
1774
  return;
1669
1775
  }
1670
1776
  const script = session.platform === 'ios' ? 'mobile: resetSimulatedLocation' : 'mobile: resetGeolocation';
1671
1777
  await execScript(client, session, script, [{}]);
1778
+ session.geolocationSet = false;
1672
1779
  }
1673
1780
  /** Alert text and, on iOS Appium Server, its button labels (`mobile: alert getButtons` → ["Yes","No"] live 2026-10-18). */
1674
1781
  export async function getAlertInfo(handle) {
@@ -1816,7 +1923,7 @@ export async function sessionCapture(handle, kind, action, name) {
1816
1923
  try {
1817
1924
  const { listFiles } = await import('./repository.js');
1818
1925
  for (let i = 0; i < 5 && !repositoryFile; i++) {
1819
- const hit = (await listFiles()).find((f) => f.uniqueName === file);
1926
+ const hit = (await listFiles({ uniqueName: file })).find((f) => f.uniqueName === file); // a miss re-fetches (cache)
1820
1927
  if (hit)
1821
1928
  repositoryFile = { id: hit.id, size: Number(hit.size ?? 0) };
1822
1929
  else
@@ -1974,6 +2081,26 @@ export async function accessibilityAudit(handle) {
1974
2081
  const r = await execScript(makeClient(), session, 'mobile: performAccessibilityAudit', [{}], 60_000);
1975
2082
  return Array.isArray(r.data.value) ? r.data.value : [];
1976
2083
  }
2084
+ /**
2085
+ * Run an adb shell command on an Android Appium Server session (`mobile: shell`, verified live 2026-11-12). The Grid's
2086
+ * execute layer accepts only seetest:client.* (and seetest:client.run is "not implemented" on Appium Server), and iOS
2087
+ * has no shell. Callers must classify the command first (src/utils/adb-shell.ts) — this function does not guard.
2088
+ */
2089
+ export async function adbShell(handle, command, args = [], timeoutMs = 60_000) {
2090
+ const session = requireSession(handle);
2091
+ if (session.platform !== 'android')
2092
+ throw new Error('shell is Android only — iOS devices have no adb shell.');
2093
+ if (session.sessionFormat !== 'w3c') {
2094
+ throw new Error('shell needs an Appium Server project: the Appium Grid only runs seetest:client commands. Use get_remote_debug_command for a full adb connection instead.');
2095
+ }
2096
+ try {
2097
+ const r = await execScript(makeClient(), session, 'mobile: shell', [{ command, args, timeout: timeoutMs }], timeoutMs + 5_000);
2098
+ return typeof r.data.value === 'string' ? r.data.value : JSON.stringify(r.data.value ?? '');
2099
+ }
2100
+ catch (e) {
2101
+ throw new Error(`adb shell "${[command, ...args].join(' ')}" failed: ${describeWdError(e)}`);
2102
+ }
2103
+ }
1977
2104
  export function isWebviewContext(session) {
1978
2105
  return !!session.currentContext && session.currentContext !== 'NATIVE_APP';
1979
2106
  }
@@ -2140,6 +2267,8 @@ export function getPendingReportIds() {
2140
2267
  }
2141
2268
  /** Session starts the client gave up on (POST /session timeout) — the platform may have completed them later. */
2142
2269
  const timedOutStarts = [];
2270
+ /** Client-side timeouts per device query in this process — a repeat gets an explicit "don't retry unchanged". */
2271
+ const timedOutQueries = new Map();
2143
2272
  /**
2144
2273
  * Register the reports that timed-out starts created after the client stopped waiting, so cleanup_inspection_sessions
2145
2274
  * can delete them. Any status counts (the session may still be running or have idled out). A start whose report