dsh-apk-vm 0.11.1 → 0.12.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/README.md CHANGED
@@ -45,7 +45,7 @@ same-origin, loopback-only debug HTTP API and an `apk_vm` Agent tool.
45
45
  > 当前 **Windows x64 与 Linux x86_64(headless)为端到端已验证平台**;macOS 仅做探测/CI
46
46
  > 覆盖,详见 `docs/LINUX-E2E.md`。
47
47
 
48
- **Status:** `0.11.1` · Apache-2.0 · no npm runtime dependencies · no build step.
48
+ **Status:** `0.12.0` · Apache-2.0 · no npm runtime dependencies · no build step.
49
49
 
50
50
  This is an open-source DSH plugin published on npm as **`dsh-apk-vm`**. Repository:
51
51
  [github.com/yuxiaole-bili/dsh-apk-vm](https://github.com/yuxiaole-bili/dsh-apk-vm).
@@ -90,7 +90,9 @@ and Agent-facing UI automation for development workflows.
90
90
  **Requirements**
91
91
 
92
92
  - Android SDK with `adb`, emulator, `sdkmanager`/`avdmanager`, a matching system image and an AVD
93
- (the Environment card checks all of this; SDK bootstrap is opt-in).
93
+ (the Environment card checks all of this; on a cold machine the default `autoSetup` provisions
94
+ it — JDK 17, SDK, system image and AVD — on first use, downloading roughly 2.5 GB; set
95
+ `autoSetup: false` to keep setup manual).
94
96
  - Hardware virtualization: AEHD/WHPX on Windows, KVM on Linux, or HVF on macOS.
95
97
  - Node.js ≥ 20 only for the repository's headless checks; the plugin itself has no npm
96
98
  dependencies or build step.
@@ -106,8 +108,10 @@ and Agent-facing UI automation for development workflows.
106
108
  - `/apk-vm/*` HTTP routes and WebSocket upgrades are same-origin and **loopback-only by
107
109
  default**; `allowRemote: true` is an explicit opt-in for use behind a trusted authenticated
108
110
  proxy.
109
- - No telemetry. Network access only occurs for explicit SDK/system-image downloads through the
110
- user's `sdkmanager`, or when the user configures a remote adb device.
111
+ - No telemetry. Network access only occurs for `autoSetup` provisioning (a SHA-256-verified
112
+ Temurin JDK 17 from `api.adoptium.net`, then the user's own `sdkmanager` for SDK packages and
113
+ the system image — roughly 2.5 GB on a cold machine), for manual downloads you trigger, or
114
+ when you configure a remote adb device.
111
115
 
112
116
  **Compatibility**
113
117
 
@@ -132,11 +136,16 @@ Real screenshots from the reference host:
132
136
 
133
137
  ![APK VM in the right sidebar](docs/screenshot-sidebar.png)
134
138
 
139
+ 28-second capture of the loop: home screen → sample APK installed and driven by the API →
140
+ 60 fps animation in the guest (720×1280, 3.2 MiB):
141
+
142
+ ![APK VM demo](docs/demo.gif)
143
+
135
144
  | Asset | Status |
136
145
  | --- | --- |
137
146
  | `docs/screenshot-panel.png` | ✅ main panel: Environment, guest H.264, controls |
138
147
  | `docs/screenshot-sidebar.png` | ✅ right-sidebar layout next to a session |
139
- | `docs/demo.gif` | optional — record a 20–30 s demo on a real host |
148
+ | `docs/demo.gif` | ✅ 28 s loop (720×1280, 3.2 MiB); reproducible from the guest-side screencap loop in [DEMO.md](DEMO.md) |
140
149
 
141
150
  The [Performance](#performance) and [Verification](#verification) sections list exactly what was
142
151
  measured, on which host, and how. Real `apk_vm` output from the reference run:
@@ -162,6 +171,12 @@ key {"text":"HOME"} -> returned to launcher
162
171
  installed, and — when `allowSetupDownloads: true` — install missing SDK components, or
163
172
  **bootstrap a completely empty host** (download Google command-line tools, extract, accept
164
173
  licenses, install platform-tools/emulator/build-tools/platform).
174
+ - **Zero-config first run (即装即用).** `autoSetup: true` (default) provisions a completely cold
175
+ host on first use: it downloads a SHA-256-verified Temurin JDK 17 from Adoptium, bootstraps the
176
+ SDK command-line tools, installs `platform-tools`/`emulator`/`build-tools`/`platforms`, the
177
+ configured system image and the AVD, with live progress plus cancel/retry in the Environment
178
+ card (`autoSetup` on `GET/POST /apk-vm/setup`). The normal `autoStart` flow then boots the VM;
179
+ set `autoSetup: false` to keep setup manual.
165
180
  - **Multi-agent isolation / multi-instance.** Several DSH Agents can drive separate VMs at the
166
181
  same time: each conversation owns a renewable lease on the VM it uses, so a second
167
182
  conversation never silently steals the first one's emulator. The first conversation gets the
@@ -212,6 +227,25 @@ key {"text":"HOME"} -> returned to launcher
212
227
  - **Installed-app management.** The panel's **Installed apps** card lists third-party packages
213
228
  for the active instance and offers force-stop, clear-data and uninstall; it uses the same
214
229
  rooted `debug/packages` + `debug/action` API as the Agent tool.
230
+ - **Remembered APKs and auto-reinstall.** APKs installed through the panel or the tool are
231
+ remembered in `<profile>/.apk-vm/installed-apps.json` (path, package, label, launch activity,
232
+ instance). When a quick-boot snapshot reset, a recreated AVD or a plugin/emulator upgrade leaves
233
+ the guest without one of those packages, the plugin reinstalls it automatically on the next boot
234
+ (`autoReinstall: true`, default) and records the pass in the activity journal. Uploaded APKs are
235
+ archived under `<profile>/.apk-vm/apks` (newest 10) so the reinstall does not depend on the
236
+ original temp file.
237
+ - **Agent activity log (图形化工作日志).** Every `apk_vm` tool call is journaled locally — action,
238
+ bounded argument preview, result, error, duration, instance, and an optional screenshot for
239
+ mutating actions. The sidebar **Agent activity** card renders it as a filterable timeline with
240
+ thumbnails, a full-screen overlay and 3 s auto-refresh, so you can see exactly what an Agent did
241
+ to the VM. See [Agent activity log](#agent-activity-log).
242
+ - **Device resilience and recovery.** Screenshot timeouts return a structured
243
+ `DEVICE_UNRESPONSIVE`-style error with an actionable message instead of a bare 180 s timeout;
244
+ `ui_dump`/`inspect_ui` supplement WebView content with a guest-side `uiautomator dump` text
245
+ fallback; `shell` gains an explicit `root: true` path (`su 0`); `tap`/`text` can verify and
246
+ retry; network mode switches repair the guest default route; watchdog/ANR crashes are detected
247
+ with a recovery hint; reinstall re-grants the install/unknown-sources appop on debug VMs.
248
+ See [Troubleshooting](#troubleshooting) for each case.
215
249
  - **Optional [`dsh-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar) tab.**
216
250
  When that community plugin is installed, this plugin registers a real tab type
217
251
  (`apk-vm:preview`) through its service — no fork, no DOM hacks, and it degrades cleanly when
@@ -282,7 +316,14 @@ to the running WebView: it discovers `webview_devtools_remote` sockets, forwards
282
316
  `tap_selector`, `tap_css`, `type_text`, `wait_for`.
283
317
  - `webviewAction=list` returns sanitized target metadata (`id`, `title`, `url`, `type`), never a
284
318
  DevTools WebSocket URL or token. Select a target with `targetId` or `webviewTarget`.
285
- - `webviewAction=eval` evaluates a JSON-returning expression; `click` and `wait_for` accept
319
+ - `webviewAction=eval` evaluates a single JavaScript expression and returns `result.value` plus a
320
+ compact preview in `summary`. JSON values come back as-is; values that do not survive
321
+ `JSON.stringify` by value (`DOMRect`, `MediaQueryList`, other objects) come back as a JSON-safe
322
+ property snapshot, so `document.querySelector("#x").getBoundingClientRect().width` and
323
+ `matchMedia("(pointer: coarse)").matches` read correctly instead of returning `null`. Statement
324
+ blocks fall back to plain CDP evaluation (no property snapshot; the result is whatever the
325
+ runtime returns, often `null`); wrap a sequence in an expression instead: `(() => { const r = document.querySelector("#x").getBoundingClientRect(); return { width: r.width, height: r.height }; })()`.
326
+ - `click` and `wait_for` accept
286
327
  ordinary CSS and `testid:VALUE` (which maps to `[data-testid="VALUE"]`). **Open** shadow roots
287
328
  are traversed; closed shadow roots and iframes are not.
288
329
  - `tap_selector` uses the same deep query and clicks through CDP. `tap_css` is for canvas or
@@ -297,6 +338,8 @@ Example Agent sequence for a hybrid App:
297
338
 
298
339
  ```text
299
340
  apk_vm { action: "webview", webviewAction: "list" }
341
+ apk_vm { action: "webview", webviewAction: "eval", script: "matchMedia('(pointer: coarse)').matches" }
342
+ apk_vm { action: "webview", webviewAction: "eval", script: "document.querySelector('#file-card').getBoundingClientRect()" }
300
343
  apk_vm { action: "webview", webviewAction: "click", selector: "testid:login" }
301
344
  apk_vm { action: "type_text", text: "中文角色名" }
302
345
  apk_vm { action: "wait_for", selector: "[data-testid=home]" }
@@ -393,6 +436,48 @@ or `project`), session id, workspace, and `since` / `lastSeenAt` timestamps; lea
393
436
  - Closing a DSH conversation (the `session/disposed` event) automatically releases its leases,
394
437
  with the 30-minute TTL as a fallback if that event is unavailable.
395
438
 
439
+ ## Multiple instances, physical devices and snapshots
440
+
441
+ - **Isolated extra instances.** `POST /apk-vm/instances {"name":"agent-a","start":true}` creates a
442
+ dedicated AVD + emulator (+ its own H.264 stream) for another Agent conversation; lease rules
443
+ are in [VM ownership](#vm-ownership-and-dedicated-conversationproject-vms). Extra instances are
444
+ idle-stopped after `instanceIdleMs`; the AVD is kept for quick reuse.
445
+ - **Physical / network devices.** `GET /apk-vm/devices` lists adb devices;
446
+ `POST /apk-vm/device {"serial":"…"}` attaches an online USB/physical/network device and
447
+ detaches back to the managed AVD with `{"serial":""}`. `GET/POST /apk-vm/remote` manages an
448
+ SSH adb tunnel (`allowRemote` / `remote` config; never a shell). The Environment card offers
449
+ the same attach/detach actions.
450
+ - **Named AVD snapshots.** `GET /apk-vm/snapshots` lists snapshots;
451
+ `POST /apk-vm/snapshots {"action":"save|load|delete","name":"…"}` manages them. The quick-boot
452
+ snapshot (`snapshotName`, default `default_boot`) is handled automatically. The panel's
453
+ Snapshot card stores, restores and deletes snapshots and shows their footprint; they live under
454
+ `~/.android/avd/<avd>.avd/snapshots/`.
455
+
456
+ ## Agent activity log
457
+
458
+ Every `apk_vm` tool call and every mutating panel/HTTP action (tap, swipe, typed text, install,
459
+ snapshot save/load, debug shell, ...) is journaled locally, so you can see what an Agent — or a
460
+ person clicking in the panel — actually did to the VM, when, and with what result. The panel adds
461
+ a sidebar **Activity** card that renders the journal as a timeline.
462
+
463
+ - Storage: `<profile>/.apk-vm/activity/activity.jsonl` plus `screenshots/<id>.png`; ring-pruned
464
+ (1000 entries / 250 MB by default). `activityDir` overrides the location.
465
+ - Each entry records `source` (`tool` for the agent tool, `http` for panel/API operations,
466
+ `system`), `tool` (`apk_vm`, `panel` or a client label), `action`, `summary`, `ok` / `error`,
467
+ `durationMs`, `instanceId`, a bounded `argsPreview`, and an optional screenshot for mutating
468
+ actions (`tap`/`swipe`/`key`/`text`/`install`/`type_text`/…).
469
+ - HTTP (same origin, local only):
470
+ `GET /apk-vm/activity?limit=&beforeId=&action=&instanceId=&source=&ok=` (newest first + `stats`),
471
+ `GET /apk-vm/activity/<id>` (one entry), `GET /apk-vm/activity/<id>/shot` (PNG),
472
+ `POST /apk-vm/activity/clear`.
473
+ - The card filters by source (Agent/User) / instance / action / errors only, lazy-loads thumbnails, opens a full-screen
474
+ overlay with metadata, auto-refreshes every 3 s while open and clears with a confirmation.
475
+ - The journal is local-only and is never uploaded, but it can contain screen content and command
476
+ arguments — clear it before recording or sharing the panel. Typed text is journaled as a
477
+ character count, not its content.
478
+
479
+ A worked, dependency-free example is in [examples/agent-workflow.mjs](examples/agent-workflow.mjs): it drives state → install → UI tree → tap → assertion → screenshot and then prints the activity timeline the call just produced.
480
+
396
481
  ## Storage management
397
482
 
398
483
  `GET /apk-vm/storage` reports the logical size of every AVD, its quick-boot snapshots, the
@@ -470,10 +555,10 @@ APK, private key or host-specific path is required.
470
555
  | Requirement | Notes |
471
556
  | --- | --- |
472
557
  | **DeepSeek Harness** | A profile that can install local plugin bundles (the desktop Web UI or any agent with the `plugin_manager` tool). |
473
- | **Android SDK** | `platform-tools` (adb), `emulator`, `build-tools` (for `aapt2`), command-line tools (`sdkmanager`/`avdmanager`) and an AOSP system image. A JDK (17 works) is needed by the SDK command-line tools. |
558
+ | **Android SDK** | `platform-tools` (adb), `emulator`, `build-tools` (for `aapt2`), command-line tools (`sdkmanager`/`avdmanager`) and an AOSP system image. The SDK command-line tools need a JDK (17 works); on a cold machine the default `autoSetup` downloads a portable Temurin JDK 17 and bootstraps the SDK itself. |
474
559
  | **AOSP system image** | `system-images;android-34;default;x86_64` (Android 14, API 34) — the image used for all measurements below. Configurable with `systemImage`. |
475
560
  | **Hardware virtualization** | Required for the x86_64 image: AEHD or WHPX on Windows, KVM on Linux, HVF on macOS. See [acceleration matrix](#cpu-acceleration-matrix). |
476
- | **Disk / RAM** | A few GB for the SDK + system image and the AVD; an emulator with a modern desktop GPU is recommended. |
561
+ | **Disk / RAM** | A few GB for the SDK + system image and the AVD (first-run provisioning downloads roughly 2.5 GB: JDK ≈190 MB + command-line tools + SDK packages + system image); an emulator with a modern desktop GPU is recommended. |
477
562
  | **Node.js 24+** *(optional)* | Only for running this repository's checks ([Verification](#verification)). The plugin itself has no npm dependencies. |
478
563
 
479
564
  The plugin's **Environment** card performs this check for you (see
@@ -527,13 +612,29 @@ Then pick one:
527
612
  After installing or upgrading the plugin, **reload the DSH Web page** so the new client bundle
528
613
  is loaded.
529
614
 
530
- ### 3. Provide an Android SDK, system image and AVD
615
+ ### 3. Provide an Android SDK, system image and AVD (automatic by default)
616
+
617
+ With the shipped `autoSetup: true` this step is automatic: the first `/apk-vm/state` or
618
+ `/apk-vm/setup` request — opening the panel, or an Agent's first `apk_vm` call — detects what is
619
+ missing and provisions it in the background while the **Environment** card shows the current
620
+ step. The chain is:
621
+
622
+ 1. **JDK 17** — when no system JDK/`JAVA_HOME` is found, a portable Temurin build is downloaded
623
+ from Adoptium (`api.adoptium.net`, SHA-256 verified) into `~/.dsh/apk-vm/jdk` (override with
624
+ `jdkRoot`). Adoptium's archive is hosted on GitHub; when that is unreachable (for example on
625
+ mainland-China networks) a built-in Tsinghua mirror is tried next with the same checksum.
626
+ 2. **Command-line tools** — `commandlinetools` are unpacked and SDK licenses accepted.
627
+ 3. **SDK packages** — `platform-tools`, `emulator`, `build-tools` and `platforms`.
628
+ 4. **System image** — the configured `systemImage` (default `system-images;android-34;default;x86_64`).
629
+ 5. **AVD** — `avdName` (default `dsh_apk`) is created.
630
+
631
+ **Cancel** / **Retry** are available in the card, and the same state is exposed as `autoSetup`
632
+ in `GET /apk-vm/setup`. Set `autoSetup: false` to provision manually instead:
531
633
 
532
634
  The plugin auto-discovers the SDK (`sdkRoot`, `ANDROID_HOME`, `ANDROID_SDK_ROOT`, then common
533
- per-OS locations) and adb/emulator. Fastest path: open the panel, check the **Environment**
534
- card, and use **Create AVD** once the system image is installed. If the image is missing and
535
- `allowSetupDownloads: true` is set, the card can also run `sdkmanager --install` for it;
536
- otherwise install it yourself:
635
+ per-OS locations) and adb/emulator; the Environment card's one-click actions remain available as
636
+ a fallback (including **Create AVD** and, with `allowSetupDownloads: true`, an
637
+ `sdkmanager --install` for the image). The manual commands are:
537
638
 
538
639
  ```bash
539
640
  sdkmanager --install "platform-tools" "emulator" "build-tools;34.0.0" \
@@ -575,7 +676,12 @@ config:
575
676
  instanceReapIntervalMs: 60000
576
677
  leaseTtlMs: 1800000 # VM owner lease lifetime; renewed by apk_vm calls
577
678
  allowRemote: false # reject non-loopback VM API clients
578
- allowSetupDownloads: false # gate the optional system-image download action
679
+ autoSetup: true # zero-config first run: auto-provision JDK 17 + SDK + image + AVD
680
+ # jdkRoot: 'C:/tools/dsh-jdk' # where the auto-downloaded JDK 17 lives
681
+ # jdkVersion: 17 # Temurin major version to provision (known-good table covers 17.0.21+9)
682
+ # jdkMirror: 'https://mirrors.tuna.tsinghua.edu.cn/Adoptium' # override the JDK mirror fallback
683
+ # activityDir: 'C:/tools/apk-vm-activity' # journal + screenshot storage (default <profile>/.apk-vm/activity)
684
+ allowSetupDownloads: false # gate the optional manual system-image download action
579
685
  scrcpy: true
580
686
  scrcpyMaxSize: 960
581
687
  scrcpyMaxFps: 60
@@ -590,10 +696,12 @@ to attach an existing device instead.
590
696
 
591
697
  ### 5. First run
592
698
 
593
- 1. Open the DSH sidebar and click **APK Virtual Machine**. Check the **Environment** card:
594
- green **Ready** means the SDK, image, AVD and acceleration were found; **Setup needed** lists
595
- what is missing and offers **Create AVD** (and optionally **Download image** when
596
- `allowSetupDownloads: true`).
699
+ 1. Open the DSH sidebar and click **APK Virtual Machine**. On a cold machine the **Environment**
700
+ card shows **Setup needed** and starts the automatic provisioning chain (progress with
701
+ **Cancel** / **Retry**; see
702
+ [step 3](#3-provide-an-android-sdk-system-image-and-avd-automatic-by-default)). Green
703
+ **Ready** means the SDK, image, AVD and acceleration were found. Hypervisor setup is the one
704
+ prerequisite the plugin cannot do for you — see [Prerequisites](#1-prerequisites).
597
705
  2. Press **Start VM** (or let `prewarm`/`autoStart` boot it). The **first start is a cold boot**
598
706
  (measured 29.5 s on the reference host); the plugin then saves the quick-boot snapshot
599
707
  `default_boot`, and later starts restore it (measured 8.4–10.5 s).
@@ -618,7 +726,7 @@ All keys are optional; defaults are shown in the **Default** column.
618
726
  | `port` | `5558` | Emulator console port used when spawning. |
619
727
  | `sdkRoot` | `ANDROID_HOME` / `ANDROID_SDK_ROOT` | Android SDK root for `adb`, `aapt2`, `emulator-check`, `sdkmanager`/`avdmanager`. |
620
728
  | `adbPath` | `<sdk>/platform-tools/adb` | Explicit adb executable. |
621
- | `systemImage` | `system-images;android-34;default;x86_64` | System image required by the Environment card and used for AVD creation. |
729
+ | `systemImage` | `system-images;android-34;default;x86_64` (`arm64-v8a` on arm64 hosts) | System image required by the Environment card and used for AVD creation. |
622
730
  | `spawnEmulator` | `true` | Set `false` to only attach (never spawn). |
623
731
  | `emulatorArgs` | `[]` | Extra argv appended to the emulator command line. |
624
732
  | `roots` | `[]` | Extra APK discovery roots. The DSH working directory, `process.cwd()` and the home directory are added automatically. |
@@ -632,6 +740,7 @@ All keys are optional; defaults are shown in the **Default** column.
632
740
  | `prewarm` | `false` | Boot the VM in the background shortly after plugin activation. |
633
741
  | `prewarmDelayMs` | `3000` | Delay before the prewarm start. |
634
742
  | `autoStart` | `true` | Start the VM on the first `/apk-vm/state` or `/apk-vm/frame` request. |
743
+ | `autoReinstall` | `true` | Remember APKs installed through the plugin and reinstall missing ones on the next boot (registry in `<profile>/.apk-vm/installed-apps.json`, archived APKs in `<profile>/.apk-vm/apks`). Set `false` to opt out. |
635
744
  | `multiInstance` | `true` | Allow isolated extra VMs for concurrent Agents. |
636
745
  | `maxInstances` | `3` | Maximum number of extra instances (in addition to the default VM). Each running instance costs guest RAM/CPU. |
637
746
  | `instanceIdleMs` | `900000` | Stop an extra instance after this long without panel frames, a video client, or an Agent command (AVD is kept). |
@@ -639,6 +748,11 @@ All keys are optional; defaults are shown in the **Default** column.
639
748
  | `leaseTtlMs` | `1800000` | Lifetime of a VM owner lease. Every `apk_vm` call that routes to the VM renews it; set `0` to disable expiry. |
640
749
  | `allowRemote` | `false` | Allow non-loopback clients to reach `/apk-vm/*` and `/apk-vm/ws` (only behind your own authenticated proxy). |
641
750
  | `allowSetupDownloads` | `false` | Allow the Environment card's `install-image` action to run `sdkmanager --install` (large download). |
751
+ | `autoSetup` | `true` | Provision a missing JDK 17 / SDK packages / system image / AVD automatically on first use (roughly 2.5 GB on a cold machine). Set `false` to keep setup manual. |
752
+ | `jdkRoot` | `~/.dsh/apk-vm/jdk` | Where the auto-downloaded Temurin JDK 17 is installed. A system JDK / `JAVA_HOME` is preferred when present. |
753
+ | `jdkVersion` | `17` | Temurin major version to provision when `autoSetup` needs a JDK. |
754
+ | `jdkMirror` | built-in Tsinghua mirror | Mirror base URL (or array of bases) used for the Temurin JDK archive when the GitHub-hosted Adoptium download is unreachable, verified with the same SHA-256 checksum. Env: `DSH_APK_VM_JDK_MIRROR`; an empty value disables the fallback. |
755
+ | `activityDir` | `<profile>/.apk-vm/activity` | Where the Agent activity journal (`activity.jsonl`) and its screenshots are stored. |
642
756
  | `frameFps` | `2` | PNG fallback target frame rate, 1–10 (the H.264 path is not affected). |
643
757
  | `scrcpy` | `true` | Enable the H.264/WebCodecs transport. |
644
758
  | `scrcpyMaxSize` | `960` | Encoder max size; 960 yields 540×960 video. |
@@ -649,8 +763,12 @@ All keys are optional; defaults are shown in the **Default** column.
649
763
 
650
764
  The Environment report (`GET /apk-vm/setup`) returns `ok`, `platform`, `sdkRoot`, `adbPath`,
651
765
  `emulatorPath`, `avdmanagerPath`, `sdkmanagerPath`, `emulatorVersion`, `systemImage` +
652
- `systemImagePresent`, `avdName` + `avdPresent` + `avdPath`, `accel { available, backend,
653
- detail }`, `hypervisorNotes`, `missing[]` and `actions[]` with per-action availability.
766
+ `systemImagePresent`, `avdName` + `avdPresent` + `avdPath`, `javaHome` + `javaPresent`,
767
+ `accel { available, backend, detail }`, `hypervisorNotes`, `missing[]` and `actions[]` with
768
+ per-action availability. It also carries the auto-setup state: `autoSetupEnabled` plus
769
+ `autoSetup { state, step, totalSteps, stepId, message, error, warnings[], startedAt,
770
+ finishedAt }`; `POST /apk-vm/setup` with `{ action: "auto-setup" }` starts/retries provisioning
771
+ and `{ action: "cancel-auto-setup" }` cancels it.
654
772
 
655
773
  ---
656
774
 
@@ -683,7 +801,9 @@ detail }`, `hypervisorNotes`, `missing[]` and `actions[]` with per-action availa
683
801
  | Layer | Implementation | Role |
684
802
  | --- | --- | --- |
685
803
  | VM | AOSP Android Emulator (`emulator` + `system-images;android-34;default;x86_64`) | Boots the open-source Android system image; driven through adb. |
686
- | Setup | [lib/setup.js](lib/setup.js) | Dependency-free SDK / adb / emulator / AVD / acceleration detection plus one-click `create-avd` and optional `install-image`. |
804
+ | Setup | [lib/setup.js](lib/setup.js), [lib/jdk.js](lib/jdk.js), [lib/autosetup.js](lib/autosetup.js) | Dependency-free SDK / adb / emulator / AVD / acceleration detection plus one-click `create-avd` and optional `install-image`; `lib/jdk.js` provisions a managed Temurin JDK 17 and `lib/autosetup.js` runs the first-use auto-provisioning chain. |
805
+ | Journal | [lib/activity-log.js](lib/activity-log.js) | Records every `apk_vm` tool call and every mutating panel/HTTP request (`source: tool|http|system`; action, argument preview, result/error, duration, instance, screenshot for mutating actions) as local JSONL + PNGs; backs the panel timeline and the `/apk-vm/activity` routes. |
806
+ | Installed apps | [lib/installed-apps.js](lib/installed-apps.js) | Persists APKs installed through the plugin (`<profile>/.apk-vm/installed-apps.json`, archived copies under `<profile>/.apk-vm/apks`) and re-installs missing packages on the next boot (`autoReinstall`). |
687
807
  | Streaming | scrcpy 5.0.1 server (`lib/vendor/scrcpy-server-v5.0.1.jar`, pushed to `/data/local/tmp/scrcpy-server.jar`) + [lib/scrcpy.js](lib/scrcpy.js) | H.264 screen capture and the scrcpy control protocol, without the desktop scrcpy client. |
688
808
  | Device bridge | `adb` from Android SDK platform-tools | install / launch / screencap / input / logcat / file push-pull. |
689
809
  | Plugin runtime | DSH plugin APIs (`slots`, `locale`, `webServer`, `tools`, `dsh.client`) | Sidebar entry, main panel, same-origin HTTP/WebSocket control plane, agent tool. |
@@ -736,7 +856,7 @@ JSON bodies are bounded to 64 KiB; the raw APK upload is bounded to 500 MiB.
736
856
  | --- | --- | --- |
737
857
  | GET | `/apk-vm/state` | VM state, serial, boot time/kind, accel/GPU, root/debug status, display size, current APK, stream counters, log tail. |
738
858
  | GET | `/apk-vm/setup?force=1` | Environment report (SDK/adb/emulator/tools/image/AVD/acceleration, missing items, available actions). Cached ~15 s. |
739
- | POST | `/apk-vm/setup` | `{"action":"refresh"\|"create-avd"\|"install-image"\|"install-tools"\|"bootstrap-sdk"}`. `install-tools`/`bootstrap-sdk` accept optional `packages`; all download actions require `allowSetupDownloads: true` (otherwise `403`) and are never automatic. |
859
+ | POST | `/apk-vm/setup` | `{"action":"refresh"\|"create-avd"\|"install-image"\|"install-tools"\|"bootstrap-sdk"}` plus `"auto-setup"` / `"cancel-auto-setup"` for first-use provisioning. `install-tools`/`bootstrap-sdk` accept optional `packages`; manual download actions require `allowSetupDownloads: true` or `confirmDownload: true` (otherwise `403`). |
740
860
  | GET | `/apk-vm/apks` | Discover `*.apk` files under the configured roots. |
741
861
  | GET | `/apk-vm/apk-info?path=…` | Static APK metadata (package/version/targetSdk/permissions/features/native code/launch activity/icon path) via `aapt2`. |
742
862
  | GET/HEAD | `/apk-vm/apk-icon?path=…` | Extract the raster launcher icon from the APK ZIP (PNG/WebP/JPEG). |
@@ -761,6 +881,9 @@ JSON bodies are bounded to 64 KiB; the raw APK upload is bounded to 500 MiB.
761
881
  | POST | `/apk-vm/instances` | `{"name":"agent-a","start":true}` — create an isolated AVD/VM; every extra instance has its own H.264 stream. |
762
882
  | DELETE | `/apk-vm/instances/:id` | Stop/dispose an extra instance (the default cannot be destroyed). |
763
883
  | GET/POST | `/apk-vm/instances/:id/...` | Per-instance mirror of `state`, `frame`, `vm`, `input`, `install`, `upload`, `debug/*`. |
884
+ | GET | `/apk-vm/activity?limit=&beforeId=&action=&instanceId=&ok=` | Agent activity journal, newest first, with `stats`; `enabled: true`. |
885
+ | GET | `/apk-vm/activity/<id>/shot` | PNG screenshot attached to one activity entry. |
886
+ | POST | `/apk-vm/activity/clear` | Clear the activity journal and its screenshots. |
764
887
 
765
888
  Uploaded APKs are written under `<os temp>/dsh-apk-vm-uploads` and that directory is removed
766
889
  when the plugin is disposed (best-effort stale-file cleanup also runs before each upload).
@@ -955,6 +1078,8 @@ for f in lib/*.js; do node --check "$f"; done
955
1078
  node spike/ui-smoke.cjs
956
1079
  node spike/ui-better-sidebar-smoke.cjs
957
1080
  node spike/setup-smoke.mjs
1081
+ node spike/cdp-test.mjs
1082
+ node spike/installed-apps-test.mjs
958
1083
  node spike/android/mock-device.mjs
959
1084
  node spike/android/launch-plan.mjs
960
1085
  ```
@@ -969,15 +1094,32 @@ node spike/android/launch-plan.mjs
969
1094
  ### The Environment card says "Setup needed"
970
1095
 
971
1096
  The report lists each missing item: SDK path, `adb`, emulator, `sdkmanager`/`avdmanager`, the
972
- configured system image, the AVD, or CPU acceleration.
973
-
974
- - Missing SDK/emulator: install Android SDK packages and/or set `sdkRoot` (or `ANDROID_HOME` /
975
- `ANDROID_SDK_ROOT`).
976
- - Missing system image: install it with `sdkmanager`, or set `allowSetupDownloads: true` and use
977
- **Download image** in the card (large download; never automatic).
978
- - Missing AVD: use **Create AVD** in the card (requires the system image and `avdmanager`) or run
1097
+ configured system image, the AVD, or CPU acceleration. With the default `autoSetup: true` the
1098
+ card starts provisioning automatically; while it runs you see the current step plus **Cancel** /
1099
+ **Retry**.
1100
+
1101
+ - Missing JDK: auto-setup downloads Temurin JDK 17 into `~/.dsh/apk-vm/jdk` automatically; a
1102
+ system JDK / `JAVA_HOME` is used instead when present.
1103
+ - Missing SDK/emulator: auto-setup installs the SDK packages; or set `sdkRoot` (or
1104
+ `ANDROID_HOME` / `ANDROID_SDK_ROOT`) to an existing SDK.
1105
+ - Missing system image: auto-setup installs it; or install it with `sdkmanager`, or set
1106
+ `allowSetupDownloads: true` and use **Download image** in the card.
1107
+ - Missing AVD: auto-setup creates it; or use **Create AVD** / run
979
1108
  `avdmanager create avd -n dsh_apk -k "system-images;android-34;default;x86_64"`.
980
- - Missing acceleration: see the next section.
1109
+ - Missing acceleration: see the next section — this is a host-level requirement auto-setup cannot
1110
+ satisfy.
1111
+
1112
+ ### Auto-setup fails or is stuck
1113
+
1114
+ The card shows the last step and the error (`autoSetup.error` in `GET /apk-vm/setup`). Common
1115
+ causes: no network access to `api.adoptium.net` / `dl.google.com` (or to `github.com`, where
1116
+ Adoptium hosts the JDK archive — the built-in Tsinghua mirror is tried automatically), a proxy or
1117
+ firewall, an antivirus locking freshly extracted files, or less than ~3 GB free disk space. Press
1118
+ **Retry**: the JDK archive is reused when its SHA-256 checksum matches, so retries do not
1119
+ re-download it; a mirror can be pinned with `jdkMirror` (or `DSH_APK_VM_JDK_MIRROR`).
1120
+ You can also set `autoSetup: false` and provision manually (see
1121
+ [step 3](#3-provide-an-android-sdk-system-image-and-avd-automatic-by-default)); parts that already
1122
+ succeeded are skipped on the next attempt.
981
1123
 
982
1124
  ### "No usable CPU hypervisor (AEHD/WHPX) was found"
983
1125
 
@@ -1027,6 +1169,92 @@ is not expected to finish booting that way.
1027
1169
  - If a stale offline adb emulator is attached, `adb kill-server` (or kill the leftover
1028
1170
  `emulator`/`qemu-system-*` process) and retry.
1029
1171
 
1172
+ ### `push` reports "outside the allowed roots" or "local file not found"
1173
+
1174
+ `apk_vm push` accepts only local files under the allowed roots: the DSH workspace,
1175
+ `process.cwd()`, the home directory and the OS temp dir, plus anything you add to `roots`.
1176
+ The two failures are distinct now — *outside the allowed roots* lists the roots and how to extend
1177
+ them; *local file not found* means the path really does not exist (both used to share one
1178
+ misleading message). On Windows the comparison is case- and separator-insensitive after
1179
+ `realpath` normalization, so mixed separators in the same home directory match. If the file legitimately
1180
+ lives elsewhere, add its directory to `roots` in the plugin config, or copy it under the
1181
+ workspace / temp dir first.
1182
+
1183
+ ### `adb` or `storage` tool actions fail with a JavaScript error
1184
+
1185
+ Fixed in 1.0.0: `adb` used to fail with `Cannot access 'api' before initialization` for every
1186
+ call (an initialization-order bug) and `storage` failed with `storageSdkRoot is not defined`.
1187
+ Both paths are covered by `spike/tool-core-test.mjs`; no configuration workaround is needed after
1188
+ updating.
1189
+
1190
+ ### A screenshot times out, the WebView UI tree is empty, or taps seem lost
1191
+
1192
+ - A screenshot that hangs usually means the guest UI is wedged (`SurfaceFlinger`/`system_server`
1193
+ stopped producing frames). The tool now returns a structured error (`DEVICE_UNRESPONSIVE` /
1194
+ `SCREENSHOT_TIMEOUT`) with a recovery hint instead of an opaque timeout, and the optional
1195
+ auto-recovery path (adb reconnect, then at most one emulator reboot with a cooldown) is used
1196
+ when enabled. A quick manual recovery is `apk_vm reboot`, or stop/start the VM in the panel.
1197
+ - `ui_dump` / `inspect_ui` on a WebView can return very few nodes with no visible text. The tool
1198
+ now supplements the tree with a guest-side `uiautomator dump` text pass, so card titles and
1199
+ button labels inside WebViews still show up (the original UIAutomator JSON shape is
1200
+ unchanged).
1201
+ - A `tap` inside a WebView that appears to do nothing may have been injected but ignored by the
1202
+ page. `tap` can verify the frame changed and retry once with a small offset; when the screen is
1203
+ byte-identical before and after, the result reports `changed: false` so you can distinguish a
1204
+ lost injection from a page that is genuinely stuck.
1205
+ - `shell` runs as the `shell` user (`uid 2000`) even though the VM is rooted. Use the explicit
1206
+ root path (`shell` with `root: true`, i.e. `su 0 sh -c …`) for `/data/data` reads and
1207
+ `shared_prefs` writes; writing app-private files also needs the app's SELinux category
1208
+ (`u:object_r:app_data_file:s0:c<…>`) because `toybox chcon` has no `--reference`.
1209
+ - Chinese `text` injection can succeed on the input channel but not reach a WebView field; the
1210
+ text path now verifies the field and falls back to a clipboard/`input text` style delivery,
1211
+ reporting which method worked.
1212
+
1213
+ ### Panel / WebView testing from a phone
1214
+
1215
+ Driving the panel and a hybrid App from a phone surfaces a few coordinate and lifecycle pitfalls:
1216
+
1217
+ - **Coordinates are physical pixels.** The panel streams a 720×1280 screen and `tap`/`swipe`
1218
+ take device pixels, while `getBoundingClientRect()` inside the WebView returns CSS pixels at
1219
+ the page's device pixel ratio (2 on the default AVD). Convert with `info.coordinateMap`:
1220
+ `device = round(css * dpr) + offset`. Prefer `tap_css` / `tap_selector` (both CDP-based) for
1221
+ DOM UI instead of converting by hand; `tap_css` is for canvas / non-DOM UI.
1222
+ - **Pin the instance.** When more than one VM exists, pass `instance: "default"` (or the id you
1223
+ own) on every `apk_vm` call so a start or install never lands on a clean extra instance.
1224
+ - **`webviewAction=eval` now returns values**, including non-JSON-by-value objects (`DOMRect`,
1225
+ `MediaQueryList`) via a property snapshot — see
1226
+ [WebView and Chrome DevTools Protocol](#webview-and-chrome-devtools-protocol).
1227
+ - **The soft keyboard moves the layout.** Typing raises the keyboard and pans the page, so a
1228
+ second `tap` can land on the previous field and concatenate account/password. Send `BACK` after
1229
+ each field before tapping the next one, or use `insert_text` / `type_text` with a selector.
1230
+ - **A wedged emulator can make the guest look reset.** If `screencap` hangs and the state flips to
1231
+ `starting`, stop/start the instance or `apk_vm reboot`. Installed APKs are remembered and
1232
+ re-installed after a quick-boot reset (`autoReinstall`, default on), but Android-side login state
1233
+ is app data: `clear_data` wipes it. The 180 s screenshot timeout and the `adb` action error are
1234
+ fixed in 1.0.0 (see the earlier sections).
1235
+
1236
+ ### The guest loses its network after switching to shared mode
1237
+
1238
+ Switching an instance to `shared` can leave the guest with a link-scope route but no default
1239
+ gateway, and a reboot clears it again. The plugin now detects and repairs the default route
1240
+ (`ip route add default via <emulator host alias>`) when the mode becomes shared, and the network
1241
+ status reports `ENETUNREACH` explicitly. If a repair still fails, reboot the VM once — the route
1242
+ is restored by the normal environment restore.
1243
+
1244
+ ### The VM stops responding after a watchdog / ANR crash
1245
+
1246
+ A `system_server` watchdog crash (`DeadSystemException`, `WAITED_HALF`) can kill the foreground
1247
+ app, drop focus to `FallbackHome` and make screenshots fail. The plugin now probes a few cheap
1248
+ health signals and reports a structured `unresponsive` status with the ANR trace location
1249
+ (`/data/anr`) and a recovery action; stop/start (or `apk_vm reboot`) restores the VM.
1250
+
1251
+ ### "Install unknown apps" is reset after reinstalling an APK
1252
+
1253
+ Android clears the per-package `REQUEST_INSTALL_PACKAGES` appop when a package is reinstalled, so
1254
+ an auto-update test can fail right after `install`. On debug/local VMs the plugin snapshots and
1255
+ re-grants the previously allowed appops after install (configurable); otherwise re-open the
1256
+ settings toggle for that package.
1257
+
1030
1258
  ### APK upload fails
1031
1259
 
1032
1260
  - The upload endpoint accepts raw `.apk`/ZIP bytes up to **500 MiB**; larger files return `413`
@@ -1093,8 +1321,12 @@ before pointing the DSH Web UI at an untrusted network.
1093
1321
  - **Upload and environment setup are privileged local actions.** Upload accepts only APK/ZIP
1094
1322
  bytes up to 500 MiB and installs them into the guest; `create-avd` writes an AVD; and
1095
1323
  `install-image` runs `sdkmanager --install` only when the user opted in with
1096
- `allowSetupDownloads: true` (default `false`). All of these are reachable only from the same
1097
- origin.
1324
+ `allowSetupDownloads: true` (default `false`). Automatic provisioning (`autoSetup`, default
1325
+ `true`) also downloads the JDK 17 from `api.adoptium.net` (SHA-256 verified; when the
1326
+ GitHub-hosted asset is unreachable the built-in mirror is used with the same checksum) and
1327
+ runs the user's own `sdkmanager`/`avdmanager` for the SDK packages, image and AVD on first
1328
+ use; set `autoSetup: false` to disable it. All of these are reachable only from the same origin and
1329
+ loopback clients.
1098
1330
  - **The `apk_vm` Agent tool is available to every agent in the DSH profile.** Grant agent access
1099
1331
  to this plugin with the same care as giving an agent a terminal on an Android device.
1100
1332
  - **Loopback-only by default.** In addition to the same-origin check, every `/apk-vm/*` HTTP
@@ -1104,10 +1336,14 @@ before pointing the DSH Web UI at an untrusted network.
1104
1336
  - **Keep the DSH Web server local.** If you expose the DSH Web UI beyond localhost (reverse
1105
1337
  proxy, LAN bind, tunnel), you also expose the plugin routes. Add authentication at the proxy
1106
1338
  layer or keep the port local; do not disable the same-origin/loopback checks.
1107
- - **No telemetry.** The plugin makes no network requests of its own to third-party services;
1108
- it only talks to the local adb/emulator and the same-origin DSH Web server (the opt-in
1109
- `install-image` action runs the user's own `sdkmanager`, which does contact Google's SDK
1110
- repository).
1339
+ - **No telemetry.** The plugin makes no network requests of its own to analytics or tracking
1340
+ services; network activity is limited to `autoSetup` provisioning (Temurin JDK from
1341
+ `api.adoptium.net` or its mirror, then the SDK packages/image through the user's own
1342
+ `sdkmanager`, which contacts Google's SDK repository) and the same-origin DSH Web server.
1343
+ - **The Agent activity log is local-only.** Tool-call journal entries and screenshots are written
1344
+ under `<profile>/.apk-vm/activity` on this host and are never sent anywhere. They can contain
1345
+ screen content and command arguments, so clear the journal before sharing a recording of the
1346
+ panel (the card has a confirmed **Clear** action, or `POST /apk-vm/activity/clear`).
1111
1347
 
1112
1348
  To report a vulnerability, follow [SECURITY.md](SECURITY.md) — please use private disclosure,
1113
1349
  not a public issue.
@@ -1119,13 +1355,11 @@ not a public issue.
1119
1355
  The features below are **not shipped yet** — they are tracked for future releases. Everything
1120
1356
  described above is implemented in this release.
1121
1357
 
1122
- - **Physical-device switching** — first-class selection/attachment of adb-attached physical
1123
- devices from the panel (config `serial` already supports attaching one; multi-AVD switching is
1124
- shipped via `/apk-vm/avds` + `/apk-vm/avd` and the Environment card).
1358
+ - **Physical-device attach is available but not exhaustively verified.** `/apk-vm/devices` +
1359
+ `/apk-vm/device` and the SSH adb tunnel are shipped; per-device quirks (OEM adb authorization,
1360
+ screen size/orientation, root availability) still need a device-specific smoke test.
1125
1361
  - **Audio streaming** — forward guest audio alongside the video stream.
1126
1362
  - **Cloud / remote VM execution** — run the guest on a remote host and stream it to the panel.
1127
- - **Static APK preview** *(optional)* — inspect an APK's manifest, resources and launcher UI
1128
- without booting a full VM.
1129
1363
 
1130
1364
  QEMU + Android-x86 for hosts without hardware virtualization and `-writable-system` image
1131
1365
  customization remain research notes in [DESIGN.md](DESIGN.md) §8.
@@ -1135,8 +1369,9 @@ customization remain research notes in [DESIGN.md](DESIGN.md) §8.
1135
1369
  ## Known limitations
1136
1370
 
1137
1371
  - **Windows x64 and Linux x86_64 are the end-to-end verified platforms.** macOS SDK/adb/
1138
- emulator/AVD discovery and headless checks are implemented, but emulator + H.264 behavior on
1139
- macOS (and `arm64-v8a` images on Apple Silicon) is unverified.
1372
+ emulator/AVD discovery is implemented and `arm64` hosts automatically select the
1373
+ `arm64-v8a` system image, but emulator + H.264 behavior on macOS/Apple Silicon is still
1374
+ unverified end-to-end.
1140
1375
  - **Hardware virtualization is mandatory** for the x86_64 AOSP image; pure TCG fails by design.
1141
1376
  - **Quick boot is snapshot-based.** Changing AVD configuration invalidates the snapshot; recreate
1142
1377
  it as described in [Troubleshooting](#quick-boot-fails-different-avd-configuration-black-screen-or-no-snapshot).
@@ -1144,8 +1379,10 @@ customization remain research notes in [DESIGN.md](DESIGN.md) §8.
1144
1379
  transport limitation.
1145
1380
  - **The rooted debug API is local-only by design.** Do not expose the DSH Web port to untrusted
1146
1381
  networks.
1147
- - **No audio and no physical-device switching yet** (multi-AVD switching is available; see
1148
- [Roadmap](#roadmap)).
1382
+ - **The activity journal records `apk_vm` tool calls** (the path Agents normally use). Direct HTTP
1383
+ calls to `/apk-vm/*` from a script are not journaled; the journal is capped at 1000 entries /
1384
+ 250 MB by default (`activityDir` changes the location; the caps are not configurable yet).
1385
+ - **No audio yet** (see [Roadmap](#roadmap)).
1149
1386
 
1150
1387
  ---
1151
1388
 
@@ -1166,10 +1403,12 @@ for f in lib/*.js; do node --check "$f"; done
1166
1403
  node spike/ui-smoke.cjs
1167
1404
  node spike/ui-better-sidebar-smoke.cjs
1168
1405
  node spike/setup-smoke.mjs
1406
+ node spike/cdp-test.mjs
1407
+ node spike/installed-apps-test.mjs
1169
1408
  node spike/android/mock-device.mjs
1170
1409
  node spike/android/launch-plan.mjs
1171
1410
  node spike/instances-smoke.mjs
1172
- node scripts/privacy-scan.mjs
1411
+ node scripts/privacy-scan.mjs --untracked
1173
1412
  ```
1174
1413
 
1175
1414
  Use [.github/ISSUE_TEMPLATE/bug_report.yml](.github/ISSUE_TEMPLATE/bug_report.yml) for bugs and
package/SECURITY.md CHANGED
@@ -4,8 +4,8 @@
4
4
 
5
5
  | Version | Supported |
6
6
  | --- | --- |
7
- | 0.3.x (current) | Yes |
8
- | < 0.3 | No |
7
+ | 1.0.x (current) | Yes |
8
+ | < 1.0 | No |
9
9
 
10
10
  The plugin is a local development tool. It is not designed or hardened as a multi-tenant or
11
11
  network-exposed service.
@@ -93,16 +93,32 @@ they demonstrate a way to exceed the stated boundaries.
93
93
  `create-avd` writes an AVD under the user's AVD home. `/apk-vm/setup` `install-image` runs
94
94
  `sdkmanager --install` only when `allowSetupDownloads: true` is configured (default `false`),
95
95
  because it is a large network download; it is never triggered automatically.
96
- 8. **The plugin does not send telemetry** or contact third-party services on its own; it talks to
97
- the local adb/emulator and the same-origin DSH Web server. The only network activity comes
98
- from the user's own `sdkmanager` when they explicitly run the opt-in `install-image` action.
96
+ 8. **Automatic provisioning (`autoSetup`, default `true`) performs network downloads on first
97
+ use.** On the first `/apk-vm/state` or `/apk-vm/setup` request the plugin may download a
98
+ portable Temurin JDK 17 from `https://api.adoptium.net` — when the GitHub-hosted asset is
99
+ unreachable, a pinned mirror (Tsinghua Adoptium mirror, overridable with `jdkMirror` /
100
+ `DSH_APK_VM_JDK_MIRROR`) is used instead; the SHA-256 checksum published by Adoptium is
101
+ verified for every source before extraction, and extraction uses `Expand-Archive`/`tar` with an
102
+ argv array and a bounded archive. It then runs the user's own `sdkmanager`/`avdmanager`
103
+ against Google's SDK repository to install the command-line tools, `platform-tools`,
104
+ `emulator`, `build-tools`, `platforms`, the configured system image and the AVD. A cold
105
+ machine downloads roughly 2.5 GB into `~/.dsh/apk-vm` (JDK; override with `jdkRoot`) and the
106
+ configured SDK root. The chain is cancellable and retryable from the panel, and
107
+ `autoSetup: false` disables it entirely. It never downloads arbitrary URLs: the JDK asset is
108
+ resolved from Adoptium's API and every SDK artifact comes through the user's own
109
+ `sdkmanager`.
110
+ 9. **The plugin does not send telemetry** or contact third-party services on its own; it talks
111
+ to the local adb/emulator and the same-origin DSH Web server. Network activity is limited to
112
+ the `autoSetup` provisioning described above and the user's own `sdkmanager`; no analytics,
113
+ identifiers or usage data are collected.
99
114
 
100
115
  ## Hardening status
101
116
 
102
117
  The released plugin applies same-origin and loopback checks to every `/apk-vm/*` HTTP route and
103
118
  the `/apk-vm/ws` upgrade, bounded payloads for JSON and uploads, argument-array process spawning,
104
- and a restricted push/pull path set. The multi-touch (`/touch`), clipboard (`/clipboard`) and
105
- artifact-download routes are part of the same origin/loopback surface. There is no separate
106
- authentication token of its own: it relies on the DSH Web server's session and on the operator
107
- keeping that server local/trusted. Run this plugin only on a machine and local network you trust;
108
- do not treat the rooted Android guest as a security boundary.
119
+ a restricted push/pull path set, and checksum-verified downloads for the auto-provisioned JDK.
120
+ The multi-touch (`/touch`), clipboard (`/clipboard`) and artifact-download routes are part of the
121
+ same origin/loopback surface. There is no separate authentication token of its own: it relies on
122
+ the DSH Web server's session and on the operator keeping that server local/trusted. Run this
123
+ plugin only on a machine and local network you trust; do not treat the rooted Android guest as a
124
+ security boundary.