dsh-apk-vm 0.10.2 → 0.11.1

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.
package/index.js CHANGED
@@ -29,6 +29,7 @@ import { ScrcpySession, annexbToAvcc, CONTROL_MESSAGE_TYPE } from './lib/scrcpy.
29
29
  import { detectEnvironment, createAvd, installSystemImage, installSdkPackages, bootstrapSdk, DEFAULT_SYSTEM_IMAGE } from './lib/setup.js';
30
30
  import { acceptWebSocket } from './lib/ws.js';
31
31
  import { parseUiHierarchy, decorateUiNodes, buildInspectorPayload, snapshotIdForXml } from './lib/ui-inspector.js';
32
+ import { annotateScreenshot } from './lib/png-annotate.js';
32
33
  import { FlowRecorder } from './lib/flows.js';
33
34
  import { normalizeCodebook, resolveControl, suggestFeatures } from './lib/control-codebook.js';
34
35
  import { attachNodeImageFeatures } from './lib/image-features.js';
@@ -38,6 +39,8 @@ import { buildApksFromAab, aabInfo, detectBundletool } from './lib/aab.js';
38
39
  import { readHarFile, summarizeHar, filterHar, toCurl } from './lib/har.js';
39
40
  import { runAssertions, compareScreenshot, createTestReport, reportMarkdown } from './lib/ui-tests.js';
40
41
  import { SshAdbTunnel } from './lib/remote.js';
42
+ import { CdpBridge } from './lib/cdp.js';
43
+ import { losslessJson } from './lib/json-safe.js';
41
44
 
42
45
  const PLUGIN_VERSION = (() => {
43
46
  try {
@@ -65,6 +68,11 @@ function isReady(vm) {
65
68
  return vm && vm.state === 'ready';
66
69
  }
67
70
 
71
+ /**
72
+ * Tool results must survive a lossless JSON round-trip. The shared helper
73
+ * converts values that JSON cannot represent without failing the whole action.
74
+ */
75
+
68
76
  function sendJson(res, status, body) {
69
77
  const text = JSON.stringify(body);
70
78
  res.writeHead(status, {
@@ -297,6 +305,7 @@ export function apply(ctx, config = {}) {
297
305
  let registerInstanceRoutes = null;
298
306
  let disposeInstanceRoutes = null;
299
307
  const flowRecorder = new FlowRecorder();
308
+ const cdpBridges = new Map();
300
309
  if (instanceManager) {
301
310
  instanceManager.onCreated = (id) => {
302
311
  registerInstanceRoutes?.(id);
@@ -655,6 +664,17 @@ export function apply(ctx, config = {}) {
655
664
  return st.startPromise;
656
665
  }
657
666
 
667
+ // Clipboard/text tools must work even when no panel client is connected.
668
+ // Start the scrcpy control stream lazily, then let the normal idle timer stop it.
669
+ async function ensureControlSession() {
670
+ const st = await ensureScrcpy();
671
+ const session = st && st.session;
672
+ if (!session || session.state !== 'running') {
673
+ throw new Error('H.264 control stream is not running');
674
+ }
675
+ return session;
676
+ }
677
+
658
678
  function handleScrcpyClient(client) {
659
679
  const st = getScrcpyState();
660
680
  st.clients.add(client);
@@ -941,6 +961,7 @@ export function apply(ctx, config = {}) {
941
961
  '/apk-vm/debug/proxy',
942
962
  '/apk-vm/debug/ca',
943
963
  '/apk-vm/debug/record',
964
+ '/apk-vm/debug/env',
944
965
  ]);
945
966
 
946
967
  function requestQuery(req) {
@@ -1857,9 +1878,13 @@ export function apply(ctx, config = {}) {
1857
1878
  else if (action === 'dns') result = await instance.vm.setDnsServers(body.servers);
1858
1879
  else if (action === 'hosts') result = await instance.vm.setHosts(body.entries);
1859
1880
  else if (action === 'test') result = await instance.vm.testNetwork(body);
1881
+ else if (action === 'validate') result = await instance.vm.networkValidation();
1860
1882
  else if (action === 'pcap') result = instance.vm.setTcpdumpPath(body.path);
1861
1883
  else if (action === 'forward-add') result = await instance.vm.addPortForward(body.localPort, body.remotePort, { shared: body.shared === true });
1862
1884
  else if (action === 'forward-remove') result = await instance.vm.removePortForward(body.localPort);
1885
+ else if (action === 'reverse-add') result = await instance.vm.addReverse(body.localPort, body.hostPort || body.remotePort);
1886
+ else if (action === 'reverse-remove') result = await instance.vm.removeReverse(body.localPort);
1887
+ else if (action === 'reverse-list') result = { ok: true, reverses: instance.vm.listReverseForwards() };
1863
1888
  else throw new Error(`unsupported network action: ${action || '(missing)'}`);
1864
1889
  sendJson(res, 200, result);
1865
1890
  } catch (error) {
@@ -2565,10 +2590,12 @@ export function apply(ctx, config = {}) {
2565
2590
  });
2566
2591
 
2567
2592
  register('/apk-vm/clipboard', async (req, res) => {
2568
- const session = scrcpyState && scrcpyState.session;
2569
2593
  if (req.method === 'GET') {
2570
- if (!session || session.state !== 'running') {
2571
- sendError(res, 409, 'H.264 control stream is not running');
2594
+ let session;
2595
+ try {
2596
+ session = await ensureControlSession();
2597
+ } catch (error) {
2598
+ sendError(res, 409, error && error.message ? error.message : String(error));
2572
2599
  return;
2573
2600
  }
2574
2601
  try {
@@ -2576,6 +2603,8 @@ export function apply(ctx, config = {}) {
2576
2603
  sendJson(res, 200, { ok: true, text });
2577
2604
  } catch (error) {
2578
2605
  sendError(res, 504, error && error.message ? error.message : String(error));
2606
+ } finally {
2607
+ scheduleScrcpyIdleStop();
2579
2608
  }
2580
2609
  return;
2581
2610
  }
@@ -2583,17 +2612,28 @@ export function apply(ctx, config = {}) {
2583
2612
  sendError(res, 405, 'GET or POST only');
2584
2613
  return;
2585
2614
  }
2586
- if (!session || session.state !== 'running') {
2587
- sendError(res, 409, 'H.264 control stream is not running');
2615
+ let body;
2616
+ try {
2617
+ body = await readJsonBody(req);
2618
+ } catch (error) {
2619
+ sendError(res, 400, error && error.message ? error.message : String(error));
2588
2620
  return;
2589
2621
  }
2590
- const body = await readJsonBody(req);
2591
2622
  if (typeof body.text !== 'string') {
2592
2623
  sendError(res, 400, 'text must be a string');
2593
2624
  return;
2594
2625
  }
2595
- const result = await session.setClipboard(body.text, { paste: body.paste === true });
2596
- sendJson(res, 200, { ok: true, ...result });
2626
+ try {
2627
+ const session = await ensureControlSession();
2628
+ try {
2629
+ const result = await session.setClipboard(body.text, { paste: body.paste === true });
2630
+ sendJson(res, 200, { ok: true, ...result });
2631
+ } finally {
2632
+ scheduleScrcpyIdleStop();
2633
+ }
2634
+ } catch (error) {
2635
+ sendError(res, 409, error && error.message ? error.message : String(error));
2636
+ }
2597
2637
  });
2598
2638
 
2599
2639
  register('/apk-vm/stream', async (req, res) => {
@@ -2647,6 +2687,27 @@ export function apply(ctx, config = {}) {
2647
2687
  sendJson(res, 200, await vm.deviceInfo());
2648
2688
  });
2649
2689
 
2690
+ register('/apk-vm/debug/env', async (req, res) => {
2691
+ if (req.method !== 'POST') {
2692
+ sendError(res, 405, 'POST only');
2693
+ return;
2694
+ }
2695
+ const body = await readJsonBody(req);
2696
+ const action = String(body.action || '').toLowerCase();
2697
+ try {
2698
+ if (action === 'capture') {
2699
+ sendJson(res, 200, { ok: true, snapshot: await vm.captureEnv() });
2700
+ } else if (action === 'restore') {
2701
+ if (!body.envSnapshot || typeof body.envSnapshot !== 'object') throw new Error('restore requires envSnapshot');
2702
+ sendJson(res, 200, await vm.restoreEnv(body.envSnapshot));
2703
+ } else {
2704
+ throw new Error('action must be capture or restore');
2705
+ }
2706
+ } catch (error) {
2707
+ sendError(res, 400, error.message);
2708
+ }
2709
+ });
2710
+
2650
2711
  register('/apk-vm/debug/shell', async (req, res) => {
2651
2712
  if (req.method !== 'POST') {
2652
2713
  sendError(res, 405, 'POST only');
@@ -2953,9 +3014,13 @@ export function apply(ctx, config = {}) {
2953
3014
  else if (action === 'dns') result = await vm.setDnsServers(body.servers);
2954
3015
  else if (action === 'hosts') result = await vm.setHosts(body.entries);
2955
3016
  else if (action === 'test') result = await vm.testNetwork(body);
3017
+ else if (action === 'validate') result = await vm.networkValidation();
2956
3018
  else if (action === 'pcap') result = vm.setTcpdumpPath(body.path);
2957
3019
  else if (action === 'forward-add') result = await vm.addPortForward(body.localPort, body.remotePort, { shared: body.shared === true });
2958
3020
  else if (action === 'forward-remove') result = await vm.removePortForward(body.localPort);
3021
+ else if (action === 'reverse-add') result = await vm.addReverse(body.localPort, body.hostPort || body.remotePort);
3022
+ else if (action === 'reverse-remove') result = await vm.removeReverse(body.localPort);
3023
+ else if (action === 'reverse-list') result = { ok: true, reverses: vm.listReverseForwards() };
2959
3024
  else throw new Error(`unsupported network action: ${action || '(missing)'}`);
2960
3025
  sendJson(res, 200, result);
2961
3026
  } catch (error) {
@@ -3039,7 +3104,16 @@ export function apply(ctx, config = {}) {
3039
3104
  return;
3040
3105
  }
3041
3106
  if (!(await ensureDebugReady(res))) return;
3042
- const png = await vm.screenshot();
3107
+ let png = await vm.screenshot();
3108
+ try {
3109
+ const url = new URL(req.url || '/', 'http://127.0.0.1');
3110
+ if (url.searchParams.get('overlay') === '1') {
3111
+ const dump = await vm.uiDump();
3112
+ png = annotateScreenshot(png, parseUiHierarchy(dump.xml).nodes).buffer;
3113
+ }
3114
+ } catch {
3115
+ /* keep the plain screenshot on overlay failure */
3116
+ }
3043
3117
  res.writeHead(200, {
3044
3118
  'Content-Type': 'image/png',
3045
3119
  'Content-Length': png.length,
@@ -3098,6 +3172,8 @@ export function apply(ctx, config = {}) {
3098
3172
  void stopScrcpy();
3099
3173
  void cleanupUploads();
3100
3174
  for (const id of [...extraRouteDisposers.keys()]) disposeExtraRouteSet(id);
3175
+ for (const bridge of cdpBridges.values()) void bridge.close().catch(() => {});
3176
+ cdpBridges.clear();
3101
3177
  void instanceManager?.dispose?.();
3102
3178
  for (const dispose of disposers.reverse()) {
3103
3179
  try {
@@ -3157,6 +3233,56 @@ export function apply(ctx, config = {}) {
3157
3233
  * can call `apk_vm` for root shell / logcat / props / packages / APK install
3158
3234
  * / push-pull / reboot, without duplicating plugin logic. */
3159
3235
 
3236
+ function cdpFor(api) {
3237
+ const key = `${api.kind}:${api.id}`;
3238
+ let bridge = cdpBridges.get(key);
3239
+ if (!bridge) {
3240
+ bridge = new CdpBridge({
3241
+ adb: (args, options) => api.adb(args, options),
3242
+ serial: () => api.serial(),
3243
+ timeoutMs: 15_000,
3244
+ });
3245
+ cdpBridges.set(key, bridge);
3246
+ }
3247
+ return bridge;
3248
+ }
3249
+
3250
+ function webviewDescriptor(value) {
3251
+ if (value == null || value === '') return null;
3252
+ if (typeof value === 'number') return value >= 1 ? value - 1 : value;
3253
+ const text = String(value).trim();
3254
+ if (/^\d+$/.test(text)) return Math.max(0, Number(text) - 1);
3255
+ if (/^(https?|file|about):/i.test(text)) return { urlContains: text };
3256
+ return text;
3257
+ }
3258
+
3259
+ async function withCdpSession(api, options, fn) {
3260
+ const bridge = cdpFor(api);
3261
+ const session = await bridge.open(webviewDescriptor(options && options.target));
3262
+ try {
3263
+ return await fn(session, bridge);
3264
+ } finally {
3265
+ session.close();
3266
+ }
3267
+ }
3268
+
3269
+ function webviewApi(api) {
3270
+ return {
3271
+ webviewTargets: () => cdpFor(api).targets(),
3272
+ webviewQuery: (selector, options) => cdpFor(api).query(selector, {
3273
+ target: webviewDescriptor(options && options.target),
3274
+ }),
3275
+ webviewEval: (script, options) => withCdpSession(api, options, (session) => session.evaluate(script)),
3276
+ webviewClick: (selector, options) => withCdpSession(api, options, (session) => session.click(selector)),
3277
+ webviewWaitFor: (selector, options) => withCdpSession(api, options, (session) => session.waitFor(selector, {
3278
+ timeoutMs: options && options.timeoutMs,
3279
+ })),
3280
+ webviewInsertText: (text, options) => withCdpSession(api, options, (session) => session.insertText(text, {
3281
+ selector: options && options.selector,
3282
+ })),
3283
+ };
3284
+ }
3285
+
3160
3286
  function defaultToolApi() {
3161
3287
  return {
3162
3288
  kind: 'default',
@@ -3176,19 +3302,34 @@ export function apply(ctx, config = {}) {
3176
3302
  return vm.input(payload);
3177
3303
  },
3178
3304
  getClipboard: async () => {
3179
- const session = scrcpyState && scrcpyState.session;
3180
- if (!session || session.state !== 'running') throw new Error('H.264 control stream is not running');
3181
- return session.requestClipboard(2000);
3305
+ const session = await ensureControlSession();
3306
+ try {
3307
+ return await session.requestClipboard(2000);
3308
+ } finally {
3309
+ scheduleScrcpyIdleStop();
3310
+ }
3182
3311
  },
3183
3312
  setClipboard: async (text, paste) => {
3184
- const session = scrcpyState && scrcpyState.session;
3185
- if (!session || session.state !== 'running') throw new Error('H.264 control stream is not running');
3186
- return session.setClipboard(text, { paste: paste === true });
3313
+ const session = await ensureControlSession();
3314
+ try {
3315
+ return await session.setClipboard(text, { paste: paste === true });
3316
+ } finally {
3317
+ scheduleScrcpyIdleStop();
3318
+ }
3319
+ },
3320
+ typeText: async (text) => {
3321
+ const session = await ensureControlSession();
3322
+ try {
3323
+ const count = await session.sendText(String(text));
3324
+ return { ok: true, chars: String(text).length, messages: count };
3325
+ } finally {
3326
+ scheduleScrcpyIdleStop();
3327
+ }
3187
3328
  },
3188
3329
  install: (apkPath) => installApkFromPath(apkPath),
3189
3330
  pushFile: (local, remote) => vm.pushFile(local, remote),
3190
3331
  pullFile: (remote, local) => vm.pullFile(remote, local),
3191
- reboot: (mode) => vm.reboot(mode),
3332
+ reboot: (mode, options) => vm.reboot(mode, options),
3192
3333
  forceStop: (pkg) => vm.forceStop(pkg),
3193
3334
  clearData: (pkg) => vm.clearData(pkg),
3194
3335
  uninstall: (pkg) => vm.uninstall(pkg),
@@ -3199,6 +3340,7 @@ export function apply(ctx, config = {}) {
3199
3340
  setProxy: (options) => vm.setProxy(options),
3200
3341
  installCaCertificate: (certPath) => vm.installCaCertificate(certPath),
3201
3342
  networkInfo: () => vm.networkInfo(),
3343
+ networkValidation: () => vm.networkValidation(),
3202
3344
  setNetworkMode: (mode) => vm.setNetworkMode(mode),
3203
3345
  setTcpdumpPath: (filePath) => vm.setTcpdumpPath(filePath),
3204
3346
  setDnsServers: (servers) => vm.setDnsServers(servers),
@@ -3206,15 +3348,42 @@ export function apply(ctx, config = {}) {
3206
3348
  testNetwork: (options) => vm.testNetwork(options),
3207
3349
  addPortForward: (local, remote, options) => vm.addPortForward(local, remote, options),
3208
3350
  removePortForward: (local) => vm.removePortForward(local),
3351
+ addReverse: (local, host) => vm.addReverse(local, host),
3352
+ removeReverse: (local) => vm.removeReverse(local),
3353
+ listReverse: () => vm.listReverseForwards(),
3354
+ captureEnv: () => vm.captureEnv(),
3355
+ restoreEnv: (snapshot) => vm.restoreEnv(snapshot),
3356
+ adb: (args, options) => vm.adb(args, options),
3209
3357
  screenRecord: (options) => vm.screenRecord(options),
3210
3358
  perfSnapshot: () => vm.perfSnapshot(),
3211
3359
  screenshotBuffer: () => vm.screenshot(),
3360
+ ...webviewApi({
3361
+ kind: 'default',
3362
+ id: 'default',
3363
+ adb: (args, options) => vm.adb(args, options),
3364
+ serial: () => vm.serial,
3365
+ }),
3212
3366
  screenshot: async () => {
3213
3367
  const buffer = await vm.screenshot();
3214
3368
  const target = path.join(os.tmpdir(), `apk-vm-shot-${Date.now()}.png`);
3215
3369
  await fsp.writeFile(target, buffer);
3216
3370
  return { path: target, bytes: buffer.length };
3217
3371
  },
3372
+ screenshotAnnotated: async () => {
3373
+ const [buffer, dump] = await Promise.all([vm.screenshot(), vm.uiDump()]);
3374
+ const nodes = parseUiHierarchy(dump.xml).nodes;
3375
+ const annotated = annotateScreenshot(buffer, nodes);
3376
+ const target = path.join(os.tmpdir(), `apk-vm-shot-overlay-${Date.now()}.png`);
3377
+ await fsp.writeFile(target, annotated.buffer);
3378
+ return {
3379
+ path: target,
3380
+ bytes: annotated.buffer.length,
3381
+ width: annotated.width,
3382
+ height: annotated.height,
3383
+ nodes: nodes.length,
3384
+ boxes: annotated.boxes,
3385
+ };
3386
+ },
3218
3387
  };
3219
3388
  }
3220
3389
 
@@ -3238,10 +3407,11 @@ export function apply(ctx, config = {}) {
3238
3407
  },
3239
3408
  getClipboard: () => instance.getClipboard(),
3240
3409
  setClipboard: (text, paste) => instance.setClipboard(text, paste),
3410
+ typeText: (text) => instance.sendText(text),
3241
3411
  install: async (apkPath) => instance.installApk(resolveApkPath(apkPath, rootsFor())),
3242
3412
  pushFile: (local, remote) => instance.pushFile(local, remote),
3243
3413
  pullFile: (remote, local) => instance.pullFile(remote, local),
3244
- reboot: (mode) => instance.reboot(mode),
3414
+ reboot: (mode, options) => instance.reboot(mode, options),
3245
3415
  forceStop: (pkg) => instance.forceStop(pkg),
3246
3416
  clearData: (pkg) => instance.clearData(pkg),
3247
3417
  uninstall: (pkg) => instance.uninstall(pkg),
@@ -3252,6 +3422,7 @@ export function apply(ctx, config = {}) {
3252
3422
  setProxy: (options) => instance.vm.setProxy(options),
3253
3423
  installCaCertificate: (certPath) => instance.vm.installCaCertificate(certPath),
3254
3424
  networkInfo: () => instance.vm.networkInfo(),
3425
+ networkValidation: () => instance.vm.networkValidation(),
3255
3426
  setNetworkMode: (mode) => instance.vm.setNetworkMode(mode),
3256
3427
  setTcpdumpPath: (filePath) => instance.vm.setTcpdumpPath(filePath),
3257
3428
  setDnsServers: (servers) => instance.vm.setDnsServers(servers),
@@ -3259,15 +3430,42 @@ export function apply(ctx, config = {}) {
3259
3430
  testNetwork: (options) => instance.vm.testNetwork(options),
3260
3431
  addPortForward: (local, remote, options) => instance.vm.addPortForward(local, remote, options),
3261
3432
  removePortForward: (local) => instance.vm.removePortForward(local),
3433
+ addReverse: (local, host) => instance.vm.addReverse(local, host),
3434
+ removeReverse: (local) => instance.vm.removeReverse(local),
3435
+ listReverse: () => instance.vm.listReverseForwards(),
3436
+ captureEnv: () => instance.vm.captureEnv(),
3437
+ restoreEnv: (snapshot) => instance.vm.restoreEnv(snapshot),
3438
+ adb: (args, options) => instance.vm.adb(args, options),
3262
3439
  screenRecord: (options) => instance.screenRecord(options),
3263
3440
  perfSnapshot: () => instance.perfSnapshot(),
3264
3441
  screenshotBuffer: () => instance.screenshot(),
3442
+ ...webviewApi({
3443
+ kind: 'extra',
3444
+ id: instance.id,
3445
+ adb: (args, options) => instance.vm.adb(args, options),
3446
+ serial: () => instance.vm.serial,
3447
+ }),
3265
3448
  screenshot: async () => {
3266
3449
  const buffer = await instance.screenshot();
3267
3450
  const target = path.join(os.tmpdir(), `apk-vm-shot-${instance.id}-${Date.now()}.png`);
3268
3451
  await fsp.writeFile(target, buffer);
3269
3452
  return { path: target, bytes: buffer.length };
3270
3453
  },
3454
+ screenshotAnnotated: async () => {
3455
+ const [buffer, dump] = await Promise.all([instance.screenshot(), instance.uiDump()]);
3456
+ const nodes = parseUiHierarchy(dump.xml).nodes;
3457
+ const annotated = annotateScreenshot(buffer, nodes);
3458
+ const target = path.join(os.tmpdir(), `apk-vm-shot-overlay-${instance.id}-${Date.now()}.png`);
3459
+ await fsp.writeFile(target, annotated.buffer);
3460
+ return {
3461
+ path: target,
3462
+ bytes: annotated.buffer.length,
3463
+ width: annotated.width,
3464
+ height: annotated.height,
3465
+ nodes: nodes.length,
3466
+ boxes: annotated.boxes,
3467
+ };
3468
+ },
3271
3469
  };
3272
3470
  }
3273
3471
 
@@ -3563,7 +3761,10 @@ export function apply(ctx, config = {}) {
3563
3761
  'Actions: info, shell, logcat, getprop, setprop, packages, install, push, pull, reboot, root, ' +
3564
3762
  'force_stop, clear_data, uninstall, rotate, ui_dump, inspect_ui, proxy, install_ca, network, record, perf, screenshot, tap, swipe, long_press, key, text, ' +
3565
3763
  'apk_info, find_ui, assert_text, tap_text, clipboard_get, clipboard_set, devices, attach_device, detach_device, start, stop, list_instances, create_instance, destroy_instance, owner_status, claim_vm, release_vm, flow_start, flow_stop, flow_list, flow_replay, storage, clean_storage, ' +
3566
- 'skill_list, skill_get, skill_save, skill_delete, skill_start, skill_stop, skill_cancel, skill_run, skill_codebook, control_ui, control_features, control_codebook, control_tap, control_input, control_long_press, control_swipe, control_assert, control_wait, control_launch. ' +
3764
+ 'skill_list, skill_get, skill_save, skill_delete, skill_start, skill_stop, skill_cancel, skill_run, skill_codebook, control_ui, control_features, control_codebook, control_tap, control_input, control_long_press, control_swipe, control_assert, control_wait, control_launch, ' +
3765
+ 'webview, tap_css, tap_selector, type_text, wait_for, env_snapshot, env_restore, adb. ' +
3766
+ 'WebView actions use Chrome DevTools Protocol (CDP): webview list|eval|click|wait_for|insert_text over the app WebView. ' +
3767
+ 'tap_selector clicks a DOM selector through CDP so CSS/dpr/status-bar math is not needed; type_text injects UTF-8 (including Chinese) through the scrcpy control stream. ' +
3567
3768
  'App-operation Skills use a persisted Control Codebook (stable codes such as LOGIN_BTN or A01) instead of raw coordinates; record once with skill_start + control_* then replay with skill_run to reach a page quickly. ' +
3568
3769
  'VM ownership: pass ownerScope=conversation or project to use a dedicated VM for this session/project; shared is the default. owner_status / claim_vm / release_vm inspect or change the current lease. A VM owned by another conversation is never taken silently: the tool returns a vm-busy error unless ownerForce=true (explicit takeover). ' +
3569
3770
  'Multi-instance: pass `instance` to target an isolated VM; omit it to use the calling Agent\'s ' +
@@ -3578,7 +3779,7 @@ export function apply(ctx, config = {}) {
3578
3779
  properties: {
3579
3780
  action: {
3580
3781
  type: 'string',
3581
- description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|inspect_ui|proxy|install_ca|network|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance|owner_status|claim_vm|release_vm|flow_start|flow_stop|flow_list|flow_replay|storage|clean_storage|skill_list|skill_get|skill_save|skill_delete|skill_start|skill_stop|skill_cancel|skill_run|skill_codebook|control_ui|control_features|control_codebook|control_tap|control_input|control_long_press|control_swipe|control_assert|control_wait|control_launch',
3782
+ description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|inspect_ui|proxy|install_ca|network|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance|owner_status|claim_vm|release_vm|flow_start|flow_stop|flow_list|flow_replay|storage|clean_storage|skill_list|skill_get|skill_save|skill_delete|skill_start|skill_stop|skill_cancel|skill_run|skill_codebook|control_ui|control_features|control_codebook|control_tap|control_input|control_long_press|control_swipe|control_assert|control_wait|control_launch|webview|tap_css|tap_selector|type_text|wait_for|env_snapshot|env_restore|adb',
3582
3783
  },
3583
3784
  instance: { type: 'string', description: 'Target VM instance id (default or an extra instance from list_instances). Omit for the calling Agent\'s assigned instance.' },
3584
3785
  ownerScope: { type: 'string', enum: ['shared', 'conversation', 'project'], description: 'VM ownership scope: shared (default), conversation (dedicated per DSH session), or project (dedicated per workspace).' },
@@ -3605,6 +3806,17 @@ export function apply(ctx, config = {}) {
3605
3806
  y1: { type: 'integer', description: 'swipe: start device y coordinate.' },
3606
3807
  x2: { type: 'integer', description: 'swipe: end device x coordinate.' },
3607
3808
  y2: { type: 'integer', description: 'swipe: end device y coordinate.' },
3809
+ selector: { type: 'string', description: 'webview/tap_selector/type_text: CSS selector, or testid:VALUE for [data-testid="VALUE"]; open shadow roots are supported.' },
3810
+ script: { type: 'string', description: 'webview eval: JavaScript expression evaluated in the page (return a JSON-serializable value).' },
3811
+ targetId: { type: 'string', description: 'webview: optional DevTools target id from action=webview webviewAction=list.' },
3812
+ webviewAction: { type: 'string', description: 'webview: list|eval|click|wait_for|insert_text|info.' },
3813
+ webviewTarget: { type: 'string', description: 'webview: target id, URL substring, title substring, or 1-based index.' },
3814
+ dpr: { type: 'number', description: 'tap_css: optional devicePixelRatio override; defaults to info.coordinateMap.dpr.' },
3815
+ offsetX: { type: 'number', description: 'tap_css: optional device-pixel x offset of the page viewport; defaults to info.coordinateMap.offsetX.' },
3816
+ offsetY: { type: 'number', description: 'tap_css: optional device-pixel y offset of the page viewport; defaults to info.coordinateMap.offsetY.' },
3817
+ statusBar: { type: 'number', description: 'tap_css: optional status-bar height in device pixels; alias for offsetY.' },
3818
+ cssX: { type: 'number', description: 'tap_css: CSS x coordinate (viewport CSS pixels).' },
3819
+ cssY: { type: 'number', description: 'tap_css: CSS y coordinate (viewport CSS pixels).' },
3608
3820
  durationMs: { type: 'integer', description: 'swipe/long_press duration in ms (1-60000; long_press default 800).' },
3609
3821
  key: { type: 'string', description: 'key: Android keycode name or number, e.g. HOME, BACK, ENTER, 3.' },
3610
3822
  text: { type: 'string', description: 'text: text to type into the focused field (max 4096 chars).' },
@@ -3620,10 +3832,17 @@ export function apply(ctx, config = {}) {
3620
3832
  storageAction: { type: 'string', description: 'clean_storage: temp|snapshots|orphan-avds.' },
3621
3833
  avdName: { type: 'string', description: 'clean_storage snapshots: target AVD (defaults to the active AVD).' },
3622
3834
  confirm: { type: 'boolean', description: 'clean_storage: required true for snapshot or orphan AVD deletion.' },
3623
- networkAction: { type: 'string', description: 'network: info|mode|dns|hosts|test|pcap|forward-add|forward-remove.' },
3835
+ networkAction: { type: 'string', description: 'network: info|mode|dns|hosts|test|validate|pcap|proxy|forward-add|forward-remove|reverse-add|reverse-remove|reverse-list.' },
3624
3836
  networkMode: { type: 'string', description: 'network mode: isolated|shared.' },
3625
3837
  localPort: { type: 'integer', description: 'port forward: host loopback port.' },
3626
3838
  remotePort: { type: 'integer', description: 'port forward: guest service port.' },
3839
+ envSnapshot: { type: 'object', additionalProperties: true, description: 'env_restore: snapshot returned by action=env_snapshot.' },
3840
+ adbArgs: { type: 'array', items: { type: 'string' }, description: 'adb: raw adb argument list, e.g. ["devices"] or ["-s","emulator-5554","shell","pidof","app"].' },
3841
+ adbCommand: { type: 'string', description: 'adb: convenience raw command string split on whitespace; prefer adbArgs for paths with spaces.' },
3842
+ restoreEnv: { type: 'boolean', description: 'reboot: capture and restore network/proxy/forwards after boot (default true).' },
3843
+ overlay: { type: 'boolean', description: 'screenshot: draw UIAutomator node boxes on the PNG and return boxes/labels.' },
3844
+ http: { type: 'string', description: 'wait_for: URL polled until any 2xx response.' },
3845
+ pollMs: { type: 'integer', description: 'wait_for: polling interval in ms (default 250).' },
3627
3846
  shared: { type: 'boolean', description: 'port forward: expose to other VMs through the emulator host alias (requires shared mode).' },
3628
3847
  servers: { type: 'array', items: { type: 'string' }, description: 'network DNS: up to 4 IPv4/IPv6 DNS servers.' },
3629
3848
  entries: { type: 'array', items: { type: 'string' }, description: 'network hosts: lines such as "1.2.3.4 api.example.com".' },
@@ -3673,6 +3892,10 @@ export function apply(ctx, config = {}) {
3673
3892
  },
3674
3893
  timeoutMs: 180000,
3675
3894
  async execute(args, exec) {
3895
+ return losslessJson(await this.executeInner(args, exec));
3896
+ },
3897
+
3898
+ async executeInner(args, exec) {
3676
3899
  const action = String((args && args.action) || '').toLowerCase();
3677
3900
 
3678
3901
  if (action === 'list_instances') {
@@ -3726,6 +3949,40 @@ export function apply(ctx, config = {}) {
3726
3949
  return { ok: true, summary: `destroyed instance ${id}`, result };
3727
3950
  }
3728
3951
 
3952
+ if (action === 'env_snapshot') {
3953
+ const snapshot = await api.captureEnv();
3954
+ return {
3955
+ ok: true,
3956
+ summary: `env: mode=${snapshot.networkMode} forwards=${snapshot.forwards.length} reverses=${snapshot.reverses.length} dns=${snapshot.dnsServers.length} hosts=${snapshot.hostsEntries.length}`,
3957
+ result: snapshot,
3958
+ };
3959
+ }
3960
+ if (action === 'env_restore') {
3961
+ if (!args.envSnapshot || typeof args.envSnapshot !== 'object') throw new Error('env_restore requires envSnapshot');
3962
+ const result = await api.restoreEnv(args.envSnapshot);
3963
+ return { ok: result.ok === true, summary: `restored ${result.applied.length} env item(s)${result.errors.length ? `; ${result.errors.length} failed` : ''}`, result };
3964
+ }
3965
+ if (action === 'adb') {
3966
+ const adbArgs = Array.isArray(args.adbArgs)
3967
+ ? args.adbArgs.map(String)
3968
+ : String(args.adbCommand || '').trim().split(/\s+/).filter(Boolean);
3969
+ if (!adbArgs.length) throw new Error('adb requires adbArgs or adbCommand');
3970
+ const raw = await api.adb(adbArgs, { timeoutMs: Math.min(120000, Number(args.timeoutMs) || 30000), maxBytes: 2 * 1024 * 1024 });
3971
+ const asText = (value) => {
3972
+ if (value == null) return '';
3973
+ if (Buffer.isBuffer(value)) return value.toString('utf8');
3974
+ if (value instanceof Uint8Array) return Buffer.from(value).toString('utf8');
3975
+ return String(value);
3976
+ };
3977
+ const stdout = asText(raw.stdout).slice(0, 200000);
3978
+ const stderr = asText(raw.stderr).slice(0, 20000);
3979
+ return {
3980
+ ok: raw.code === 0 && !raw.timedOut,
3981
+ summary: `adb ${adbArgs[0] || ''} exit ${raw.code}${raw.timedOut ? ' (timeout)' : ''}`,
3982
+ result: { code: raw.code, timedOut: raw.timedOut === true, stdout, stderr },
3983
+ };
3984
+ }
3985
+
3729
3986
  if (action === 'apk_info') {
3730
3987
  if (!args.path) throw new Error('action=apk_info requires path (local .apk file)');
3731
3988
  const apkPath = resolveApkPath(args.path, rootsFor());
@@ -3979,6 +4236,16 @@ export function apply(ctx, config = {}) {
3979
4236
  }
3980
4237
  if (action === 'network') {
3981
4238
  const networkAction = String(args.networkAction || 'info').toLowerCase();
4239
+ // `proxy` already exists as a top-level action; accept it here too because
4240
+ // callers naturally try `action=network, networkAction=proxy`.
4241
+ if (networkAction === 'proxy') {
4242
+ if (args.enabled === false || args.clear === true) {
4243
+ const result = await api.setProxy({ enabled: false });
4244
+ return { ok: true, summary: 'proxy cleared', result };
4245
+ }
4246
+ const result = await api.setProxy({ host: args.host, port: args.port, bypass: args.bypass, enabled: true });
4247
+ return { ok: true, summary: result.proxy ? `proxy=${result.proxy}` : 'proxy set', result };
4248
+ }
3982
4249
  if (networkAction === 'mode') {
3983
4250
  const result = api.setNetworkMode(args.networkMode || args.mode);
3984
4251
  return { ok: true, summary: `network mode: ${result.mode}`, result };
@@ -4019,6 +4286,24 @@ export function apply(ctx, config = {}) {
4019
4286
  const result = await api.removePortForward(args.localPort);
4020
4287
  return { ok: true, summary: `removed forward tcp:${result.localPort}`, result };
4021
4288
  }
4289
+ if (networkAction === 'reverse-add') {
4290
+ if (!args.localPort || !args.remotePort) throw new Error('reverse-add requires localPort (guest) and remotePort (host)');
4291
+ const result = await api.addReverse(args.localPort, args.remotePort);
4292
+ return { ok: true, summary: `reverse guest 127.0.0.1:${result.localPort} -> host 127.0.0.1:${result.hostPort}`, result };
4293
+ }
4294
+ if (networkAction === 'reverse-remove') {
4295
+ if (!args.localPort) throw new Error('reverse-remove requires localPort');
4296
+ const result = await api.removeReverse(args.localPort);
4297
+ return { ok: true, summary: `removed reverse tcp:${result.localPort}`, result };
4298
+ }
4299
+ if (networkAction === 'reverse-list') {
4300
+ const result = await api.listReverse();
4301
+ return { ok: true, summary: `${result.length} reverse forward(s)`, result: { reverses: result, count: result.length } };
4302
+ }
4303
+ if (networkAction === 'validate') {
4304
+ const result = await api.networkValidation();
4305
+ return { ok: result.validated === true, summary: result.validated ? 'network is VALIDATED' : 'network is not VALIDATED', result };
4306
+ }
4022
4307
  throw new Error(`unsupported networkAction: ${networkAction}`);
4023
4308
  }
4024
4309
  if (action === 'start') {
@@ -4086,9 +4371,129 @@ export function apply(ctx, config = {}) {
4086
4371
  }
4087
4372
  case 'text': {
4088
4373
  if (typeof args.text !== 'string' || !args.text) throw new Error('action=text requires a non-empty text string');
4374
+ if (/[^\x00-\x7f]/.test(args.text) && typeof api.typeText === 'function') {
4375
+ const result = await api.typeText(args.text);
4376
+ return { ok: true, summary: `typed ${args.text.length} Unicode chars on ${api.id}`, result };
4377
+ }
4089
4378
  const result = await api.input({ type: 'text', text: args.text });
4090
4379
  return { ok: result.ok, summary: `typed ${args.text.length} chars on ${api.id}`, result };
4091
4380
  }
4381
+ case 'webview': {
4382
+ const action = String(args.webviewAction || 'list').toLowerCase();
4383
+ const target = args.webviewTarget || args.targetId;
4384
+ if (action === 'list' || action === 'info') {
4385
+ if (typeof api.webviewTargets !== 'function') throw new Error('webview: CDP bridge is unavailable');
4386
+ const targets = await api.webviewTargets();
4387
+ return { ok: true, summary: `${targets.length} WebView target(s) on ${api.id}`, result: { targets, count: targets.length } };
4388
+ }
4389
+ if (action === 'eval') {
4390
+ if (!args.script) throw new Error('webview eval requires script');
4391
+ const value = await api.webviewEval(args.script, { target });
4392
+ return { ok: true, summary: `evaluated JS in WebView on ${api.id}`, result: { value } };
4393
+ }
4394
+ if (action === 'click') {
4395
+ if (!args.selector) throw new Error('webview click requires selector');
4396
+ await api.webviewClick(args.selector, { target });
4397
+ return { ok: true, summary: `clicked WebView selector ${args.selector}`, result: { selector: args.selector } };
4398
+ }
4399
+ if (action === 'wait_for' || action === 'waitfor') {
4400
+ if (!args.selector) throw new Error('webview wait_for requires selector');
4401
+ const timeoutMs = Math.max(1, Math.min(120000, Number(args.timeoutMs) || 10000));
4402
+ await api.webviewWaitFor(args.selector, { target, timeoutMs });
4403
+ return { ok: true, summary: `WebView selector ${args.selector} appeared within ${timeoutMs}ms`, result: { selector: args.selector } };
4404
+ }
4405
+ if (action === 'insert_text' || action === 'inserttext' || action === 'type') {
4406
+ if (typeof args.text !== 'string' || !args.text) throw new Error('webview insert_text requires text');
4407
+ await api.webviewInsertText(args.text, { target, selector: args.selector });
4408
+ return { ok: true, summary: `inserted ${args.text.length} chars into WebView on ${api.id}`, result: { chars: args.text.length } };
4409
+ }
4410
+ throw new Error(`webview: unknown webviewAction ${action}; use list|eval|click|wait_for|insert_text`);
4411
+ }
4412
+ case 'type_text': {
4413
+ if (typeof args.text !== 'string' || !args.text) throw new Error('action=type_text requires a non-empty text string');
4414
+ if (args.selector) {
4415
+ if (typeof api.webviewInsertText !== 'function') throw new Error('type_text with selector requires a CDP/WebView bridge');
4416
+ await api.webviewInsertText(args.text, { target: args.webviewTarget || args.targetId, selector: args.selector });
4417
+ return { ok: true, summary: `inserted ${args.text.length} Unicode chars into ${args.selector} on ${api.id}` };
4418
+ }
4419
+ if (typeof api.typeText === 'function') {
4420
+ const result = await api.typeText(args.text);
4421
+ return {
4422
+ ok: true,
4423
+ summary: `typed ${args.text.length} Unicode chars on ${api.id}`,
4424
+ result,
4425
+ };
4426
+ }
4427
+ throw new Error('type_text: H.264 control stream is unavailable; open the VM panel once to start streaming, or pass a WebView selector');
4428
+ }
4429
+ case 'tap_css': {
4430
+ const x = Number(args.cssX !== undefined ? args.cssX : args.x);
4431
+ const y = Number(args.cssY !== undefined ? args.cssY : args.y);
4432
+ if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error('action=tap_css requires numeric cssX/cssY (viewport CSS pixels)');
4433
+ const info = await api.deviceInfo();
4434
+ const map = info.coordinateMap || {};
4435
+ const dpr = Number(args.dpr !== undefined ? args.dpr : map.dpr);
4436
+ const offsetX = Number(args.offsetX !== undefined ? args.offsetX : map.offsetX || 0);
4437
+ const offsetY = Number(
4438
+ args.offsetY !== undefined
4439
+ ? args.offsetY
4440
+ : args.statusBar !== undefined
4441
+ ? args.statusBar
4442
+ : map.offsetY || 0,
4443
+ );
4444
+ if (!Number.isFinite(dpr) || dpr <= 0) throw new Error('tap_css: devicePixelRatio is unknown; pass dpr explicitly');
4445
+ const dx = Math.round(x * dpr + offsetX);
4446
+ const dy = Math.round(y * dpr + offsetY);
4447
+ const result = await api.input({ type: 'tap', x: dx, y: dy });
4448
+ return {
4449
+ ok: result.ok,
4450
+ summary: `tap CSS ${x},${y} -> device ${dx},${dy} (dpr=${dpr}, offset=${offsetX},${offsetY}) on ${api.id}`,
4451
+ result: { css: { x, y }, device: { x: dx, y: dy }, dpr, offset: { x: offsetX, y: offsetY }, input: result },
4452
+ };
4453
+ }
4454
+ case 'tap_selector': {
4455
+ if (!args.selector) throw new Error('action=tap_selector requires selector');
4456
+ if (typeof api.webviewClick !== 'function') throw new Error('tap_selector: no CDP/WebView bridge is available');
4457
+ const result = await api.webviewClick(args.selector, { target: args.webviewTarget || args.targetId });
4458
+ return { ok: true, summary: `clicked selector ${args.selector}`, result };
4459
+ }
4460
+ case 'wait_for': {
4461
+ const timeoutMs = Math.max(0, Math.min(120000, Number(args.timeoutMs) || 10000));
4462
+ const pollMs = Math.max(25, Math.min(2000, Number(args.pollMs) || 250));
4463
+ const started = Date.now();
4464
+ const deadline = started + timeoutMs;
4465
+ const mode = args.selector ? 'selector' : args.http ? 'http' : args.text ? 'text' : 'seconds';
4466
+ let last = null;
4467
+ while (Date.now() <= deadline) {
4468
+ if (mode === 'seconds') {
4469
+ const waitMs = Math.min(timeoutMs, Math.max(0, Number(args.seconds || 0) * 1000));
4470
+ await new Promise((resolve) => setTimeout(resolve, waitMs));
4471
+ return { ok: true, summary: `waited ${waitMs}ms on ${api.id}`, result: { waitedMs: waitMs } };
4472
+ }
4473
+ try {
4474
+ if (mode === 'selector') {
4475
+ if (typeof api.webviewQuery === 'function') {
4476
+ last = await api.webviewQuery(args.selector, { target: args.webviewTarget || args.targetId });
4477
+ if (last && last.found) return { ok: true, summary: `selector appeared after ${Date.now() - started}ms`, result: last };
4478
+ }
4479
+ } else if (mode === 'http') {
4480
+ const response = await fetch(String(args.http), { redirect: 'manual' });
4481
+ last = { status: response.status, ok: response.ok, url: response.url };
4482
+ if (response.ok) return { ok: true, summary: `HTTP ${response.status} after ${Date.now() - started}ms`, result: last };
4483
+ } else if (mode === 'text') {
4484
+ const dump = await api.uiDump();
4485
+ const needle = String(args.text);
4486
+ last = { nodes: dump.nodes, matched: String(dump.xml || '').includes(needle) };
4487
+ if (last.matched) return { ok: true, summary: `UI text appeared after ${Date.now() - started}ms`, result: last };
4488
+ }
4489
+ } catch (error) {
4490
+ last = { error: error.message };
4491
+ }
4492
+ if (Date.now() + pollMs > deadline) break;
4493
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
4494
+ }
4495
+ throw new Error(`wait_for timed out after ${timeoutMs}ms (${mode}): ${JSON.stringify(last)}`);
4496
+ }
4092
4497
  case 'install': {
4093
4498
  const installed = await api.install(args.path);
4094
4499
  return { ok: true, summary: `${api.id}: installed ${installed.packageName} (${installed.label})`, result: installed };
@@ -4104,8 +4509,12 @@ export function apply(ctx, config = {}) {
4104
4509
  return { ok: true, summary: `pulled ${args.remotePath} -> ${result.localPath}`, result };
4105
4510
  }
4106
4511
  case 'reboot': {
4107
- const result = await api.reboot(args.mode || '');
4108
- return { ok: true, summary: `rebooting ${api.id} (${result.mode})`, result };
4512
+ const result = await api.reboot(args.mode || '', { restoreEnv: args.restoreEnv !== false });
4513
+ return {
4514
+ ok: true,
4515
+ summary: `rebooting ${api.id} (${result.mode})${result.restoreScheduled ? '; env restore scheduled' : ''}`,
4516
+ result,
4517
+ };
4109
4518
  }
4110
4519
  case 'root': {
4111
4520
  const ok = await api.ensureRoot();
@@ -4125,6 +4534,10 @@ export function apply(ctx, config = {}) {
4125
4534
  return { ok: result.ok, summary: `uninstalled ${args.packageName}`, result };
4126
4535
  }
4127
4536
  case 'screenshot': {
4537
+ if (args.overlay === true) {
4538
+ const result = await api.screenshotAnnotated();
4539
+ return { ok: true, summary: `annotated screenshot (${result.nodes} nodes) saved to ${result.path}`, result };
4540
+ }
4128
4541
  const result = await api.screenshot();
4129
4542
  return { ok: true, summary: `${api.id}: screenshot saved to ${result.path} (${result.bytes} bytes)`, result };
4130
4543
  }