dsh-apk-vm 0.10.2 → 0.11.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.
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);
@@ -941,6 +950,7 @@ export function apply(ctx, config = {}) {
941
950
  '/apk-vm/debug/proxy',
942
951
  '/apk-vm/debug/ca',
943
952
  '/apk-vm/debug/record',
953
+ '/apk-vm/debug/env',
944
954
  ]);
945
955
 
946
956
  function requestQuery(req) {
@@ -1857,9 +1867,13 @@ export function apply(ctx, config = {}) {
1857
1867
  else if (action === 'dns') result = await instance.vm.setDnsServers(body.servers);
1858
1868
  else if (action === 'hosts') result = await instance.vm.setHosts(body.entries);
1859
1869
  else if (action === 'test') result = await instance.vm.testNetwork(body);
1870
+ else if (action === 'validate') result = await instance.vm.networkValidation();
1860
1871
  else if (action === 'pcap') result = instance.vm.setTcpdumpPath(body.path);
1861
1872
  else if (action === 'forward-add') result = await instance.vm.addPortForward(body.localPort, body.remotePort, { shared: body.shared === true });
1862
1873
  else if (action === 'forward-remove') result = await instance.vm.removePortForward(body.localPort);
1874
+ else if (action === 'reverse-add') result = await instance.vm.addReverse(body.localPort, body.hostPort || body.remotePort);
1875
+ else if (action === 'reverse-remove') result = await instance.vm.removeReverse(body.localPort);
1876
+ else if (action === 'reverse-list') result = { ok: true, reverses: instance.vm.listReverseForwards() };
1863
1877
  else throw new Error(`unsupported network action: ${action || '(missing)'}`);
1864
1878
  sendJson(res, 200, result);
1865
1879
  } catch (error) {
@@ -2647,6 +2661,27 @@ export function apply(ctx, config = {}) {
2647
2661
  sendJson(res, 200, await vm.deviceInfo());
2648
2662
  });
2649
2663
 
2664
+ register('/apk-vm/debug/env', async (req, res) => {
2665
+ if (req.method !== 'POST') {
2666
+ sendError(res, 405, 'POST only');
2667
+ return;
2668
+ }
2669
+ const body = await readJsonBody(req);
2670
+ const action = String(body.action || '').toLowerCase();
2671
+ try {
2672
+ if (action === 'capture') {
2673
+ sendJson(res, 200, { ok: true, snapshot: await vm.captureEnv() });
2674
+ } else if (action === 'restore') {
2675
+ if (!body.envSnapshot || typeof body.envSnapshot !== 'object') throw new Error('restore requires envSnapshot');
2676
+ sendJson(res, 200, await vm.restoreEnv(body.envSnapshot));
2677
+ } else {
2678
+ throw new Error('action must be capture or restore');
2679
+ }
2680
+ } catch (error) {
2681
+ sendError(res, 400, error.message);
2682
+ }
2683
+ });
2684
+
2650
2685
  register('/apk-vm/debug/shell', async (req, res) => {
2651
2686
  if (req.method !== 'POST') {
2652
2687
  sendError(res, 405, 'POST only');
@@ -2953,9 +2988,13 @@ export function apply(ctx, config = {}) {
2953
2988
  else if (action === 'dns') result = await vm.setDnsServers(body.servers);
2954
2989
  else if (action === 'hosts') result = await vm.setHosts(body.entries);
2955
2990
  else if (action === 'test') result = await vm.testNetwork(body);
2991
+ else if (action === 'validate') result = await vm.networkValidation();
2956
2992
  else if (action === 'pcap') result = vm.setTcpdumpPath(body.path);
2957
2993
  else if (action === 'forward-add') result = await vm.addPortForward(body.localPort, body.remotePort, { shared: body.shared === true });
2958
2994
  else if (action === 'forward-remove') result = await vm.removePortForward(body.localPort);
2995
+ else if (action === 'reverse-add') result = await vm.addReverse(body.localPort, body.hostPort || body.remotePort);
2996
+ else if (action === 'reverse-remove') result = await vm.removeReverse(body.localPort);
2997
+ else if (action === 'reverse-list') result = { ok: true, reverses: vm.listReverseForwards() };
2959
2998
  else throw new Error(`unsupported network action: ${action || '(missing)'}`);
2960
2999
  sendJson(res, 200, result);
2961
3000
  } catch (error) {
@@ -3039,7 +3078,16 @@ export function apply(ctx, config = {}) {
3039
3078
  return;
3040
3079
  }
3041
3080
  if (!(await ensureDebugReady(res))) return;
3042
- const png = await vm.screenshot();
3081
+ let png = await vm.screenshot();
3082
+ try {
3083
+ const url = new URL(req.url || '/', 'http://127.0.0.1');
3084
+ if (url.searchParams.get('overlay') === '1') {
3085
+ const dump = await vm.uiDump();
3086
+ png = annotateScreenshot(png, parseUiHierarchy(dump.xml).nodes).buffer;
3087
+ }
3088
+ } catch {
3089
+ /* keep the plain screenshot on overlay failure */
3090
+ }
3043
3091
  res.writeHead(200, {
3044
3092
  'Content-Type': 'image/png',
3045
3093
  'Content-Length': png.length,
@@ -3098,6 +3146,8 @@ export function apply(ctx, config = {}) {
3098
3146
  void stopScrcpy();
3099
3147
  void cleanupUploads();
3100
3148
  for (const id of [...extraRouteDisposers.keys()]) disposeExtraRouteSet(id);
3149
+ for (const bridge of cdpBridges.values()) void bridge.close().catch(() => {});
3150
+ cdpBridges.clear();
3101
3151
  void instanceManager?.dispose?.();
3102
3152
  for (const dispose of disposers.reverse()) {
3103
3153
  try {
@@ -3157,6 +3207,56 @@ export function apply(ctx, config = {}) {
3157
3207
  * can call `apk_vm` for root shell / logcat / props / packages / APK install
3158
3208
  * / push-pull / reboot, without duplicating plugin logic. */
3159
3209
 
3210
+ function cdpFor(api) {
3211
+ const key = `${api.kind}:${api.id}`;
3212
+ let bridge = cdpBridges.get(key);
3213
+ if (!bridge) {
3214
+ bridge = new CdpBridge({
3215
+ adb: (args, options) => api.adb(args, options),
3216
+ serial: () => api.serial(),
3217
+ timeoutMs: 15_000,
3218
+ });
3219
+ cdpBridges.set(key, bridge);
3220
+ }
3221
+ return bridge;
3222
+ }
3223
+
3224
+ function webviewDescriptor(value) {
3225
+ if (value == null || value === '') return null;
3226
+ if (typeof value === 'number') return value >= 1 ? value - 1 : value;
3227
+ const text = String(value).trim();
3228
+ if (/^\d+$/.test(text)) return Math.max(0, Number(text) - 1);
3229
+ if (/^(https?|file|about):/i.test(text)) return { urlContains: text };
3230
+ return text;
3231
+ }
3232
+
3233
+ async function withCdpSession(api, options, fn) {
3234
+ const bridge = cdpFor(api);
3235
+ const session = await bridge.open(webviewDescriptor(options && options.target));
3236
+ try {
3237
+ return await fn(session, bridge);
3238
+ } finally {
3239
+ session.close();
3240
+ }
3241
+ }
3242
+
3243
+ function webviewApi(api) {
3244
+ return {
3245
+ webviewTargets: () => cdpFor(api).targets(),
3246
+ webviewQuery: (selector, options) => cdpFor(api).query(selector, {
3247
+ target: webviewDescriptor(options && options.target),
3248
+ }),
3249
+ webviewEval: (script, options) => withCdpSession(api, options, (session) => session.evaluate(script)),
3250
+ webviewClick: (selector, options) => withCdpSession(api, options, (session) => session.click(selector)),
3251
+ webviewWaitFor: (selector, options) => withCdpSession(api, options, (session) => session.waitFor(selector, {
3252
+ timeoutMs: options && options.timeoutMs,
3253
+ })),
3254
+ webviewInsertText: (text, options) => withCdpSession(api, options, (session) => session.insertText(text, {
3255
+ selector: options && options.selector,
3256
+ })),
3257
+ };
3258
+ }
3259
+
3160
3260
  function defaultToolApi() {
3161
3261
  return {
3162
3262
  kind: 'default',
@@ -3185,10 +3285,16 @@ export function apply(ctx, config = {}) {
3185
3285
  if (!session || session.state !== 'running') throw new Error('H.264 control stream is not running');
3186
3286
  return session.setClipboard(text, { paste: paste === true });
3187
3287
  },
3288
+ typeText: async (text) => {
3289
+ const session = scrcpyState && scrcpyState.session;
3290
+ if (!session || session.state !== 'running') throw new Error('H.264 control stream is not running');
3291
+ const count = await session.sendText(String(text));
3292
+ return { ok: true, chars: String(text).length, messages: count };
3293
+ },
3188
3294
  install: (apkPath) => installApkFromPath(apkPath),
3189
3295
  pushFile: (local, remote) => vm.pushFile(local, remote),
3190
3296
  pullFile: (remote, local) => vm.pullFile(remote, local),
3191
- reboot: (mode) => vm.reboot(mode),
3297
+ reboot: (mode, options) => vm.reboot(mode, options),
3192
3298
  forceStop: (pkg) => vm.forceStop(pkg),
3193
3299
  clearData: (pkg) => vm.clearData(pkg),
3194
3300
  uninstall: (pkg) => vm.uninstall(pkg),
@@ -3199,6 +3305,7 @@ export function apply(ctx, config = {}) {
3199
3305
  setProxy: (options) => vm.setProxy(options),
3200
3306
  installCaCertificate: (certPath) => vm.installCaCertificate(certPath),
3201
3307
  networkInfo: () => vm.networkInfo(),
3308
+ networkValidation: () => vm.networkValidation(),
3202
3309
  setNetworkMode: (mode) => vm.setNetworkMode(mode),
3203
3310
  setTcpdumpPath: (filePath) => vm.setTcpdumpPath(filePath),
3204
3311
  setDnsServers: (servers) => vm.setDnsServers(servers),
@@ -3206,15 +3313,42 @@ export function apply(ctx, config = {}) {
3206
3313
  testNetwork: (options) => vm.testNetwork(options),
3207
3314
  addPortForward: (local, remote, options) => vm.addPortForward(local, remote, options),
3208
3315
  removePortForward: (local) => vm.removePortForward(local),
3316
+ addReverse: (local, host) => vm.addReverse(local, host),
3317
+ removeReverse: (local) => vm.removeReverse(local),
3318
+ listReverse: () => vm.listReverseForwards(),
3319
+ captureEnv: () => vm.captureEnv(),
3320
+ restoreEnv: (snapshot) => vm.restoreEnv(snapshot),
3321
+ adb: (args, options) => vm.adb(args, options),
3209
3322
  screenRecord: (options) => vm.screenRecord(options),
3210
3323
  perfSnapshot: () => vm.perfSnapshot(),
3211
3324
  screenshotBuffer: () => vm.screenshot(),
3325
+ ...webviewApi({
3326
+ kind: 'default',
3327
+ id: 'default',
3328
+ adb: (args, options) => vm.adb(args, options),
3329
+ serial: () => vm.serial,
3330
+ }),
3212
3331
  screenshot: async () => {
3213
3332
  const buffer = await vm.screenshot();
3214
3333
  const target = path.join(os.tmpdir(), `apk-vm-shot-${Date.now()}.png`);
3215
3334
  await fsp.writeFile(target, buffer);
3216
3335
  return { path: target, bytes: buffer.length };
3217
3336
  },
3337
+ screenshotAnnotated: async () => {
3338
+ const [buffer, dump] = await Promise.all([vm.screenshot(), vm.uiDump()]);
3339
+ const nodes = parseUiHierarchy(dump.xml).nodes;
3340
+ const annotated = annotateScreenshot(buffer, nodes);
3341
+ const target = path.join(os.tmpdir(), `apk-vm-shot-overlay-${Date.now()}.png`);
3342
+ await fsp.writeFile(target, annotated.buffer);
3343
+ return {
3344
+ path: target,
3345
+ bytes: annotated.buffer.length,
3346
+ width: annotated.width,
3347
+ height: annotated.height,
3348
+ nodes: nodes.length,
3349
+ boxes: annotated.boxes,
3350
+ };
3351
+ },
3218
3352
  };
3219
3353
  }
3220
3354
 
@@ -3238,10 +3372,11 @@ export function apply(ctx, config = {}) {
3238
3372
  },
3239
3373
  getClipboard: () => instance.getClipboard(),
3240
3374
  setClipboard: (text, paste) => instance.setClipboard(text, paste),
3375
+ typeText: (text) => instance.sendText(text),
3241
3376
  install: async (apkPath) => instance.installApk(resolveApkPath(apkPath, rootsFor())),
3242
3377
  pushFile: (local, remote) => instance.pushFile(local, remote),
3243
3378
  pullFile: (remote, local) => instance.pullFile(remote, local),
3244
- reboot: (mode) => instance.reboot(mode),
3379
+ reboot: (mode, options) => instance.reboot(mode, options),
3245
3380
  forceStop: (pkg) => instance.forceStop(pkg),
3246
3381
  clearData: (pkg) => instance.clearData(pkg),
3247
3382
  uninstall: (pkg) => instance.uninstall(pkg),
@@ -3252,6 +3387,7 @@ export function apply(ctx, config = {}) {
3252
3387
  setProxy: (options) => instance.vm.setProxy(options),
3253
3388
  installCaCertificate: (certPath) => instance.vm.installCaCertificate(certPath),
3254
3389
  networkInfo: () => instance.vm.networkInfo(),
3390
+ networkValidation: () => instance.vm.networkValidation(),
3255
3391
  setNetworkMode: (mode) => instance.vm.setNetworkMode(mode),
3256
3392
  setTcpdumpPath: (filePath) => instance.vm.setTcpdumpPath(filePath),
3257
3393
  setDnsServers: (servers) => instance.vm.setDnsServers(servers),
@@ -3259,15 +3395,42 @@ export function apply(ctx, config = {}) {
3259
3395
  testNetwork: (options) => instance.vm.testNetwork(options),
3260
3396
  addPortForward: (local, remote, options) => instance.vm.addPortForward(local, remote, options),
3261
3397
  removePortForward: (local) => instance.vm.removePortForward(local),
3398
+ addReverse: (local, host) => instance.vm.addReverse(local, host),
3399
+ removeReverse: (local) => instance.vm.removeReverse(local),
3400
+ listReverse: () => instance.vm.listReverseForwards(),
3401
+ captureEnv: () => instance.vm.captureEnv(),
3402
+ restoreEnv: (snapshot) => instance.vm.restoreEnv(snapshot),
3403
+ adb: (args, options) => instance.vm.adb(args, options),
3262
3404
  screenRecord: (options) => instance.screenRecord(options),
3263
3405
  perfSnapshot: () => instance.perfSnapshot(),
3264
3406
  screenshotBuffer: () => instance.screenshot(),
3407
+ ...webviewApi({
3408
+ kind: 'extra',
3409
+ id: instance.id,
3410
+ adb: (args, options) => instance.vm.adb(args, options),
3411
+ serial: () => instance.vm.serial,
3412
+ }),
3265
3413
  screenshot: async () => {
3266
3414
  const buffer = await instance.screenshot();
3267
3415
  const target = path.join(os.tmpdir(), `apk-vm-shot-${instance.id}-${Date.now()}.png`);
3268
3416
  await fsp.writeFile(target, buffer);
3269
3417
  return { path: target, bytes: buffer.length };
3270
3418
  },
3419
+ screenshotAnnotated: async () => {
3420
+ const [buffer, dump] = await Promise.all([instance.screenshot(), instance.uiDump()]);
3421
+ const nodes = parseUiHierarchy(dump.xml).nodes;
3422
+ const annotated = annotateScreenshot(buffer, nodes);
3423
+ const target = path.join(os.tmpdir(), `apk-vm-shot-overlay-${instance.id}-${Date.now()}.png`);
3424
+ await fsp.writeFile(target, annotated.buffer);
3425
+ return {
3426
+ path: target,
3427
+ bytes: annotated.buffer.length,
3428
+ width: annotated.width,
3429
+ height: annotated.height,
3430
+ nodes: nodes.length,
3431
+ boxes: annotated.boxes,
3432
+ };
3433
+ },
3271
3434
  };
3272
3435
  }
3273
3436
 
@@ -3563,7 +3726,10 @@ export function apply(ctx, config = {}) {
3563
3726
  'Actions: info, shell, logcat, getprop, setprop, packages, install, push, pull, reboot, root, ' +
3564
3727
  'force_stop, clear_data, uninstall, rotate, ui_dump, inspect_ui, proxy, install_ca, network, record, perf, screenshot, tap, swipe, long_press, key, text, ' +
3565
3728
  '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. ' +
3729
+ '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, ' +
3730
+ 'webview, tap_css, tap_selector, type_text, wait_for, env_snapshot, env_restore, adb. ' +
3731
+ 'WebView actions use Chrome DevTools Protocol (CDP): webview list|eval|click|wait_for|insert_text over the app WebView. ' +
3732
+ '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
3733
  '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
3734
  '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
3735
  'Multi-instance: pass `instance` to target an isolated VM; omit it to use the calling Agent\'s ' +
@@ -3578,7 +3744,7 @@ export function apply(ctx, config = {}) {
3578
3744
  properties: {
3579
3745
  action: {
3580
3746
  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',
3747
+ 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
3748
  },
3583
3749
  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
3750
  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 +3771,17 @@ export function apply(ctx, config = {}) {
3605
3771
  y1: { type: 'integer', description: 'swipe: start device y coordinate.' },
3606
3772
  x2: { type: 'integer', description: 'swipe: end device x coordinate.' },
3607
3773
  y2: { type: 'integer', description: 'swipe: end device y coordinate.' },
3774
+ selector: { type: 'string', description: 'webview/tap_selector/type_text: CSS selector, or testid:VALUE for [data-testid="VALUE"]; open shadow roots are supported.' },
3775
+ script: { type: 'string', description: 'webview eval: JavaScript expression evaluated in the page (return a JSON-serializable value).' },
3776
+ targetId: { type: 'string', description: 'webview: optional DevTools target id from action=webview webviewAction=list.' },
3777
+ webviewAction: { type: 'string', description: 'webview: list|eval|click|wait_for|insert_text|info.' },
3778
+ webviewTarget: { type: 'string', description: 'webview: target id, URL substring, title substring, or 1-based index.' },
3779
+ dpr: { type: 'number', description: 'tap_css: optional devicePixelRatio override; defaults to info.coordinateMap.dpr.' },
3780
+ offsetX: { type: 'number', description: 'tap_css: optional device-pixel x offset of the page viewport; defaults to info.coordinateMap.offsetX.' },
3781
+ offsetY: { type: 'number', description: 'tap_css: optional device-pixel y offset of the page viewport; defaults to info.coordinateMap.offsetY.' },
3782
+ statusBar: { type: 'number', description: 'tap_css: optional status-bar height in device pixels; alias for offsetY.' },
3783
+ cssX: { type: 'number', description: 'tap_css: CSS x coordinate (viewport CSS pixels).' },
3784
+ cssY: { type: 'number', description: 'tap_css: CSS y coordinate (viewport CSS pixels).' },
3608
3785
  durationMs: { type: 'integer', description: 'swipe/long_press duration in ms (1-60000; long_press default 800).' },
3609
3786
  key: { type: 'string', description: 'key: Android keycode name or number, e.g. HOME, BACK, ENTER, 3.' },
3610
3787
  text: { type: 'string', description: 'text: text to type into the focused field (max 4096 chars).' },
@@ -3620,10 +3797,17 @@ export function apply(ctx, config = {}) {
3620
3797
  storageAction: { type: 'string', description: 'clean_storage: temp|snapshots|orphan-avds.' },
3621
3798
  avdName: { type: 'string', description: 'clean_storage snapshots: target AVD (defaults to the active AVD).' },
3622
3799
  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.' },
3800
+ networkAction: { type: 'string', description: 'network: info|mode|dns|hosts|test|validate|pcap|forward-add|forward-remove|reverse-add|reverse-remove|reverse-list.' },
3624
3801
  networkMode: { type: 'string', description: 'network mode: isolated|shared.' },
3625
3802
  localPort: { type: 'integer', description: 'port forward: host loopback port.' },
3626
3803
  remotePort: { type: 'integer', description: 'port forward: guest service port.' },
3804
+ envSnapshot: { type: 'object', additionalProperties: true, description: 'env_restore: snapshot returned by action=env_snapshot.' },
3805
+ adbArgs: { type: 'array', items: { type: 'string' }, description: 'adb: raw adb argument list, e.g. ["devices"] or ["-s","emulator-5554","shell","pidof","app"].' },
3806
+ adbCommand: { type: 'string', description: 'adb: convenience raw command string split on whitespace; prefer adbArgs for paths with spaces.' },
3807
+ restoreEnv: { type: 'boolean', description: 'reboot: capture and restore network/proxy/forwards after boot (default true).' },
3808
+ overlay: { type: 'boolean', description: 'screenshot: draw UIAutomator node boxes on the PNG and return boxes/labels.' },
3809
+ http: { type: 'string', description: 'wait_for: URL polled until any 2xx response.' },
3810
+ pollMs: { type: 'integer', description: 'wait_for: polling interval in ms (default 250).' },
3627
3811
  shared: { type: 'boolean', description: 'port forward: expose to other VMs through the emulator host alias (requires shared mode).' },
3628
3812
  servers: { type: 'array', items: { type: 'string' }, description: 'network DNS: up to 4 IPv4/IPv6 DNS servers.' },
3629
3813
  entries: { type: 'array', items: { type: 'string' }, description: 'network hosts: lines such as "1.2.3.4 api.example.com".' },
@@ -3673,6 +3857,10 @@ export function apply(ctx, config = {}) {
3673
3857
  },
3674
3858
  timeoutMs: 180000,
3675
3859
  async execute(args, exec) {
3860
+ return losslessJson(await this.executeInner(args, exec));
3861
+ },
3862
+
3863
+ async executeInner(args, exec) {
3676
3864
  const action = String((args && args.action) || '').toLowerCase();
3677
3865
 
3678
3866
  if (action === 'list_instances') {
@@ -3726,6 +3914,40 @@ export function apply(ctx, config = {}) {
3726
3914
  return { ok: true, summary: `destroyed instance ${id}`, result };
3727
3915
  }
3728
3916
 
3917
+ if (action === 'env_snapshot') {
3918
+ const snapshot = await api.captureEnv();
3919
+ return {
3920
+ ok: true,
3921
+ summary: `env: mode=${snapshot.networkMode} forwards=${snapshot.forwards.length} reverses=${snapshot.reverses.length} dns=${snapshot.dnsServers.length} hosts=${snapshot.hostsEntries.length}`,
3922
+ result: snapshot,
3923
+ };
3924
+ }
3925
+ if (action === 'env_restore') {
3926
+ if (!args.envSnapshot || typeof args.envSnapshot !== 'object') throw new Error('env_restore requires envSnapshot');
3927
+ const result = await api.restoreEnv(args.envSnapshot);
3928
+ return { ok: result.ok === true, summary: `restored ${result.applied.length} env item(s)${result.errors.length ? `; ${result.errors.length} failed` : ''}`, result };
3929
+ }
3930
+ if (action === 'adb') {
3931
+ const adbArgs = Array.isArray(args.adbArgs)
3932
+ ? args.adbArgs.map(String)
3933
+ : String(args.adbCommand || '').trim().split(/\s+/).filter(Boolean);
3934
+ if (!adbArgs.length) throw new Error('adb requires adbArgs or adbCommand');
3935
+ const raw = await api.adb(adbArgs, { timeoutMs: Math.min(120000, Number(args.timeoutMs) || 30000), maxBytes: 2 * 1024 * 1024 });
3936
+ const asText = (value) => {
3937
+ if (value == null) return '';
3938
+ if (Buffer.isBuffer(value)) return value.toString('utf8');
3939
+ if (value instanceof Uint8Array) return Buffer.from(value).toString('utf8');
3940
+ return String(value);
3941
+ };
3942
+ const stdout = asText(raw.stdout).slice(0, 200000);
3943
+ const stderr = asText(raw.stderr).slice(0, 20000);
3944
+ return {
3945
+ ok: raw.code === 0 && !raw.timedOut,
3946
+ summary: `adb ${adbArgs[0] || ''} exit ${raw.code}${raw.timedOut ? ' (timeout)' : ''}`,
3947
+ result: { code: raw.code, timedOut: raw.timedOut === true, stdout, stderr },
3948
+ };
3949
+ }
3950
+
3729
3951
  if (action === 'apk_info') {
3730
3952
  if (!args.path) throw new Error('action=apk_info requires path (local .apk file)');
3731
3953
  const apkPath = resolveApkPath(args.path, rootsFor());
@@ -4019,6 +4241,24 @@ export function apply(ctx, config = {}) {
4019
4241
  const result = await api.removePortForward(args.localPort);
4020
4242
  return { ok: true, summary: `removed forward tcp:${result.localPort}`, result };
4021
4243
  }
4244
+ if (networkAction === 'reverse-add') {
4245
+ if (!args.localPort || !args.remotePort) throw new Error('reverse-add requires localPort (guest) and remotePort (host)');
4246
+ const result = await api.addReverse(args.localPort, args.remotePort);
4247
+ return { ok: true, summary: `reverse guest 127.0.0.1:${result.localPort} -> host 127.0.0.1:${result.hostPort}`, result };
4248
+ }
4249
+ if (networkAction === 'reverse-remove') {
4250
+ if (!args.localPort) throw new Error('reverse-remove requires localPort');
4251
+ const result = await api.removeReverse(args.localPort);
4252
+ return { ok: true, summary: `removed reverse tcp:${result.localPort}`, result };
4253
+ }
4254
+ if (networkAction === 'reverse-list') {
4255
+ const result = await api.listReverse();
4256
+ return { ok: true, summary: `${result.length} reverse forward(s)`, result: { reverses: result, count: result.length } };
4257
+ }
4258
+ if (networkAction === 'validate') {
4259
+ const result = await api.networkValidation();
4260
+ return { ok: result.validated === true, summary: result.validated ? 'network is VALIDATED' : 'network is not VALIDATED', result };
4261
+ }
4022
4262
  throw new Error(`unsupported networkAction: ${networkAction}`);
4023
4263
  }
4024
4264
  if (action === 'start') {
@@ -4086,9 +4326,129 @@ export function apply(ctx, config = {}) {
4086
4326
  }
4087
4327
  case 'text': {
4088
4328
  if (typeof args.text !== 'string' || !args.text) throw new Error('action=text requires a non-empty text string');
4329
+ if (/[^\x00-\x7f]/.test(args.text) && typeof api.typeText === 'function') {
4330
+ const result = await api.typeText(args.text);
4331
+ return { ok: true, summary: `typed ${args.text.length} Unicode chars on ${api.id}`, result };
4332
+ }
4089
4333
  const result = await api.input({ type: 'text', text: args.text });
4090
4334
  return { ok: result.ok, summary: `typed ${args.text.length} chars on ${api.id}`, result };
4091
4335
  }
4336
+ case 'webview': {
4337
+ const action = String(args.webviewAction || 'list').toLowerCase();
4338
+ const target = args.webviewTarget || args.targetId;
4339
+ if (action === 'list' || action === 'info') {
4340
+ if (typeof api.webviewTargets !== 'function') throw new Error('webview: CDP bridge is unavailable');
4341
+ const targets = await api.webviewTargets();
4342
+ return { ok: true, summary: `${targets.length} WebView target(s) on ${api.id}`, result: { targets, count: targets.length } };
4343
+ }
4344
+ if (action === 'eval') {
4345
+ if (!args.script) throw new Error('webview eval requires script');
4346
+ const value = await api.webviewEval(args.script, { target });
4347
+ return { ok: true, summary: `evaluated JS in WebView on ${api.id}`, result: { value } };
4348
+ }
4349
+ if (action === 'click') {
4350
+ if (!args.selector) throw new Error('webview click requires selector');
4351
+ await api.webviewClick(args.selector, { target });
4352
+ return { ok: true, summary: `clicked WebView selector ${args.selector}`, result: { selector: args.selector } };
4353
+ }
4354
+ if (action === 'wait_for' || action === 'waitfor') {
4355
+ if (!args.selector) throw new Error('webview wait_for requires selector');
4356
+ const timeoutMs = Math.max(1, Math.min(120000, Number(args.timeoutMs) || 10000));
4357
+ await api.webviewWaitFor(args.selector, { target, timeoutMs });
4358
+ return { ok: true, summary: `WebView selector ${args.selector} appeared within ${timeoutMs}ms`, result: { selector: args.selector } };
4359
+ }
4360
+ if (action === 'insert_text' || action === 'inserttext' || action === 'type') {
4361
+ if (typeof args.text !== 'string' || !args.text) throw new Error('webview insert_text requires text');
4362
+ await api.webviewInsertText(args.text, { target, selector: args.selector });
4363
+ return { ok: true, summary: `inserted ${args.text.length} chars into WebView on ${api.id}`, result: { chars: args.text.length } };
4364
+ }
4365
+ throw new Error(`webview: unknown webviewAction ${action}; use list|eval|click|wait_for|insert_text`);
4366
+ }
4367
+ case 'type_text': {
4368
+ if (typeof args.text !== 'string' || !args.text) throw new Error('action=type_text requires a non-empty text string');
4369
+ if (args.selector) {
4370
+ if (typeof api.webviewInsertText !== 'function') throw new Error('type_text with selector requires a CDP/WebView bridge');
4371
+ await api.webviewInsertText(args.text, { target: args.webviewTarget || args.targetId, selector: args.selector });
4372
+ return { ok: true, summary: `inserted ${args.text.length} Unicode chars into ${args.selector} on ${api.id}` };
4373
+ }
4374
+ if (typeof api.typeText === 'function') {
4375
+ const result = await api.typeText(args.text);
4376
+ return {
4377
+ ok: true,
4378
+ summary: `typed ${args.text.length} Unicode chars on ${api.id}`,
4379
+ result,
4380
+ };
4381
+ }
4382
+ throw new Error('type_text: H.264 control stream is unavailable; open the VM panel once to start streaming, or pass a WebView selector');
4383
+ }
4384
+ case 'tap_css': {
4385
+ const x = Number(args.cssX !== undefined ? args.cssX : args.x);
4386
+ const y = Number(args.cssY !== undefined ? args.cssY : args.y);
4387
+ if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error('action=tap_css requires numeric cssX/cssY (viewport CSS pixels)');
4388
+ const info = await api.deviceInfo();
4389
+ const map = info.coordinateMap || {};
4390
+ const dpr = Number(args.dpr !== undefined ? args.dpr : map.dpr);
4391
+ const offsetX = Number(args.offsetX !== undefined ? args.offsetX : map.offsetX || 0);
4392
+ const offsetY = Number(
4393
+ args.offsetY !== undefined
4394
+ ? args.offsetY
4395
+ : args.statusBar !== undefined
4396
+ ? args.statusBar
4397
+ : map.offsetY || 0,
4398
+ );
4399
+ if (!Number.isFinite(dpr) || dpr <= 0) throw new Error('tap_css: devicePixelRatio is unknown; pass dpr explicitly');
4400
+ const dx = Math.round(x * dpr + offsetX);
4401
+ const dy = Math.round(y * dpr + offsetY);
4402
+ const result = await api.input({ type: 'tap', x: dx, y: dy });
4403
+ return {
4404
+ ok: result.ok,
4405
+ summary: `tap CSS ${x},${y} -> device ${dx},${dy} (dpr=${dpr}, offset=${offsetX},${offsetY}) on ${api.id}`,
4406
+ result: { css: { x, y }, device: { x: dx, y: dy }, dpr, offset: { x: offsetX, y: offsetY }, input: result },
4407
+ };
4408
+ }
4409
+ case 'tap_selector': {
4410
+ if (!args.selector) throw new Error('action=tap_selector requires selector');
4411
+ if (typeof api.webviewClick !== 'function') throw new Error('tap_selector: no CDP/WebView bridge is available');
4412
+ const result = await api.webviewClick(args.selector, { target: args.webviewTarget || args.targetId });
4413
+ return { ok: true, summary: `clicked selector ${args.selector}`, result };
4414
+ }
4415
+ case 'wait_for': {
4416
+ const timeoutMs = Math.max(0, Math.min(120000, Number(args.timeoutMs) || 10000));
4417
+ const pollMs = Math.max(25, Math.min(2000, Number(args.pollMs) || 250));
4418
+ const started = Date.now();
4419
+ const deadline = started + timeoutMs;
4420
+ const mode = args.selector ? 'selector' : args.http ? 'http' : args.text ? 'text' : 'seconds';
4421
+ let last = null;
4422
+ while (Date.now() <= deadline) {
4423
+ if (mode === 'seconds') {
4424
+ const waitMs = Math.min(timeoutMs, Math.max(0, Number(args.seconds || 0) * 1000));
4425
+ await new Promise((resolve) => setTimeout(resolve, waitMs));
4426
+ return { ok: true, summary: `waited ${waitMs}ms on ${api.id}`, result: { waitedMs: waitMs } };
4427
+ }
4428
+ try {
4429
+ if (mode === 'selector') {
4430
+ if (typeof api.webviewQuery === 'function') {
4431
+ last = await api.webviewQuery(args.selector, { target: args.webviewTarget || args.targetId });
4432
+ if (last && last.found) return { ok: true, summary: `selector appeared after ${Date.now() - started}ms`, result: last };
4433
+ }
4434
+ } else if (mode === 'http') {
4435
+ const response = await fetch(String(args.http), { redirect: 'manual' });
4436
+ last = { status: response.status, ok: response.ok, url: response.url };
4437
+ if (response.ok) return { ok: true, summary: `HTTP ${response.status} after ${Date.now() - started}ms`, result: last };
4438
+ } else if (mode === 'text') {
4439
+ const dump = await api.uiDump();
4440
+ const needle = String(args.text);
4441
+ last = { nodes: dump.nodes, matched: String(dump.xml || '').includes(needle) };
4442
+ if (last.matched) return { ok: true, summary: `UI text appeared after ${Date.now() - started}ms`, result: last };
4443
+ }
4444
+ } catch (error) {
4445
+ last = { error: error.message };
4446
+ }
4447
+ if (Date.now() + pollMs > deadline) break;
4448
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
4449
+ }
4450
+ throw new Error(`wait_for timed out after ${timeoutMs}ms (${mode}): ${JSON.stringify(last)}`);
4451
+ }
4092
4452
  case 'install': {
4093
4453
  const installed = await api.install(args.path);
4094
4454
  return { ok: true, summary: `${api.id}: installed ${installed.packageName} (${installed.label})`, result: installed };
@@ -4104,8 +4464,12 @@ export function apply(ctx, config = {}) {
4104
4464
  return { ok: true, summary: `pulled ${args.remotePath} -> ${result.localPath}`, result };
4105
4465
  }
4106
4466
  case 'reboot': {
4107
- const result = await api.reboot(args.mode || '');
4108
- return { ok: true, summary: `rebooting ${api.id} (${result.mode})`, result };
4467
+ const result = await api.reboot(args.mode || '', { restoreEnv: args.restoreEnv !== false });
4468
+ return {
4469
+ ok: true,
4470
+ summary: `rebooting ${api.id} (${result.mode})${result.restoreScheduled ? '; env restore scheduled' : ''}`,
4471
+ result,
4472
+ };
4109
4473
  }
4110
4474
  case 'root': {
4111
4475
  const ok = await api.ensureRoot();
@@ -4125,6 +4489,10 @@ export function apply(ctx, config = {}) {
4125
4489
  return { ok: result.ok, summary: `uninstalled ${args.packageName}`, result };
4126
4490
  }
4127
4491
  case 'screenshot': {
4492
+ if (args.overlay === true) {
4493
+ const result = await api.screenshotAnnotated();
4494
+ return { ok: true, summary: `annotated screenshot (${result.nodes} nodes) saved to ${result.path}`, result };
4495
+ }
4128
4496
  const result = await api.screenshot();
4129
4497
  return { ok: true, summary: `${api.id}: screenshot saved to ${result.path} (${result.bytes} bytes)`, result };
4130
4498
  }