dsh-apk-vm 0.12.3 → 0.12.5

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/CHANGELOG.md CHANGED
@@ -1,5 +1,54 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.12.5
4
+
5
+ ### Added
6
+
7
+ - **Download reliability for zero-config provisioning.** Every provisioning step now retries
8
+ transient network/command failures (`setupRetries`, default 3, exponential backoff via
9
+ `retryDelayMs`), and a 45 s no-progress watchdog aborts stalled downloads instead of hanging.
10
+ The JDK archive resumes from a `.partial` file with HTTP Range and is re-verified against the
11
+ SHA-256 on every attempt; the command-line-tools download now streams with a stall timeout,
12
+ size bound and optional checksum (`commandLineToolsUrl` / `commandLineToolsSha256`) and can be
13
+ pointed at a mirror; `sdkmanager` accepts mirror/proxy settings (`sdkManagerArgs`,
14
+ `sdkManagerEnv`, `networkProxy`); a cumulative free-disk budget (`minFreeDiskBytes`, default
15
+ 6 GB) is checked before provisioning starts. Retries surface `attempt` and `nextDelayMs` in
16
+ `autoSetup.detail`, and the Environment card shows "retry n/m in Ns" while backing off.
17
+ - **Memory-aware instance management.** New `lib/memory.js` reads host RAM and derives the
18
+ effective instance cap (`memoryGuard`, `hostReserveMb` 4 GB, `estimatedVmMb` 3 GB, clamped to
19
+ 1–8), exposed as `memory` on `GET /apk-vm/state`, `/apk-vm/emulators` and
20
+ `GET /apk-vm/instances`, and on the `apk_vm` `list_instances` action. Creating/starting a local
21
+ VM on a low-memory host fails with an actionable error instead of swapping the machine to
22
+ death; `memoryPressureReap` (default) stops the least-recently-used idle local VM first. The VM
23
+ instances card shows host RAM, the effective cap, the preset and the per-VM RAM/vCPU profile.
24
+ - **Lite mode.** `vmPreset: lite` shrinks the default AVD and extra instances to 1 GB guest RAM,
25
+ 2 vCPU, SwiftShader GPU and a 720×1280 / 30 fps H.264 stream (1 fps PNG fallback), for 8–16 GB
26
+ hosts.
27
+ - **Wedged-guest recovery.** A device that adb still lists but whose guest shell stops responding
28
+ is detected after two consecutive boot-probe timeouts, killed through the emulator console (and
29
+ its process tree), its broken snapshot is quarantined, and the instance is cold-started once
30
+ instead of staying `booting` forever. `_refresh()` no longer flips between `starting` and
31
+ `stopped` while a boot wait is in flight, and the instances card gains a Start button for
32
+ stopped VMs.
33
+ - **Chinese changelog.** `CHANGELOG.zh-CN.md` mirrors the 0.12.x entries of the English
34
+ changelog (the pre-0.12 history stays English-only in `CHANGELOG.md`) and release notes now
35
+ carry a Chinese summary; the release checklist requires keeping it in sync.
36
+
37
+ ## 0.12.4
38
+
39
+ ### Fixed
40
+
41
+ - **Hypervisor detection regression from 0.12.3.** A refactor of the boot-speed
42
+ bookkeeping dropped three constructor initialisers (`_accelAvailable`,
43
+ `_snapshotSave`, `_lastLaunchArgs`). `_accelAvailable` stayed `undefined`, so
44
+ `_detectAcceleration()` short-circuited on `!== null` and returned
45
+ `undefined`; every start then failed with a bogus "No usable CPU hypervisor
46
+ (AEHD/WHPX) was found" error even on hosts where `emulator -accel-check`
47
+ reported AEHD/WHPX usable. The fields are restored, and
48
+ `spike/snapshot-recovery-test.mjs` now asserts their initial values and that
49
+ `_detectAcceleration()` returns a boolean, so this regression cannot silently
50
+ ship again.
51
+
3
52
  ## 0.12.3
4
53
 
5
54
  ### Added
@@ -127,12 +176,16 @@ reset, and the plugin can provision its own JDK / Android SDK / system image / A
127
176
  - `webviewAction=eval` returned `null` for `DOMRect`/`MediaQueryList` and other non-by-value
128
177
  values; it now returns a readable snapshot.
129
178
 
130
- ## 1.0.0
179
+ ### Historical: planned 1.0.0, shipped as 0.12.0
180
+
181
+ > These notes were written for a 1.0.0 cut that was renumbered to 0.12.0 before
182
+ > release. They are kept here for history, so no 1.0.0 that never shipped appears
183
+ > between the 0.12.0 and 0.11.1 sections.
131
184
 
132
185
  Observability and reliability release: a local Agent activity journal, hardened device
133
186
  interactions, and a first-class zero-config provisioning chain.
134
187
 
135
- ### Added
188
+ #### Added
136
189
 
137
190
  - **Agent activity log.** Every `apk_vm` tool call and every mutating panel/HTTP request is
138
191
  journaled locally as JSONL under `<profile>/.apk-vm/activity` (override with `activityDir`);
@@ -167,7 +220,7 @@ interactions, and a first-class zero-config provisioning chain.
167
220
  - WebView control docs and examples now point at `webview`/`tap_css`/`tap_selector`
168
221
  as the preferred path for DOM content.
169
222
 
170
- ### Changed
223
+ #### Changed
171
224
 
172
225
  - `sdkmanager` installs (`installSystemImage`, `installSdkPackages`) always pass
173
226
  `--sdk_root=<sdkRoot>`, so a `sdkmanager` found elsewhere on `PATH` cannot install into the
@@ -179,7 +232,7 @@ interactions, and a first-class zero-config provisioning chain.
179
232
  physical devices and snapshots; expanded troubleshooting for the fixes above; macOS/arm64
180
233
  image selection documented; demo media checked in.
181
234
 
182
- ### Fixed
235
+ #### Fixed
183
236
 
184
237
  - `adb` tool action failed with `Cannot access 'api' before initialization` on every call — the
185
238
  tool API is now resolved lazily per action.
@@ -214,15 +267,13 @@ interactions, and a first-class zero-config provisioning chain.
214
267
  and per-candidate timeouts plus the known-good JDK table make it fail over instead.
215
268
  - macOS arm64 provisioning selected the x86_64 image; it now defaults to `arm64-v8a`.
216
269
 
217
- ### Fixed
218
-
219
270
  - `GET/POST /apk-vm/camera` accepted poster paths that did not exist; save/apply now reject
220
271
  missing or unreadable `-virtualscene-poster` files with the offending poster name and path
221
272
  instead of failing later on the next emulator launch.
222
273
 
223
- ### Zero-config first run
274
+ ##### Zero-config first run
224
275
 
225
- ### Added
276
+ ##### Added
226
277
 
227
278
  - **Automatic environment provisioning (`autoSetup`, default `true`).** The first
228
279
  `GET /apk-vm/state` or `GET /apk-vm/setup` request — opening the panel, or an Agent's first
@@ -245,7 +296,7 @@ interactions, and a first-class zero-config provisioning chain.
245
296
  - `GET /apk-vm/setup` now reports `javaHome` / `javaPresent`; the Environment card shows a Java
246
297
  row plus live auto-setup progress with cancel/retry.
247
298
 
248
- ### Changed
299
+ ##### Changed
249
300
 
250
301
  - `findJavaHome()` also looks in the plugin-managed JDK directory and `extraJavaHomes`, so
251
302
  `sdkmanager`/`avdmanager` work without a system-wide JDK or `JAVA_HOME`.
@@ -254,7 +305,7 @@ interactions, and a first-class zero-config provisioning chain.
254
305
  `autoStart` flow — a cold install goes from zero to a running VM without extra clicks.
255
306
  - First-run documentation is now install → open the panel → automatic provisioning → VM start.
256
307
 
257
- ### Fixed
308
+ ##### Fixed
258
309
 
259
310
  - The Environment card could stay empty on exactly the machines that needed setup: a
260
311
  `GET /apk-vm/setup` payload with `ok: false` was treated as a failed request. It now renders
@@ -0,0 +1,129 @@
1
+ # 更新日志(中文)
2
+
3
+ 本文件提供 **0.12.x** 各版本的中文更新日志,与英文版 [`CHANGELOG.md`](CHANGELOG.md) 同步;
4
+ 0.12.0 之前的历史仅保留在英文文件中。发布时请在 [docs/RELEASING.md](docs/RELEASING.md)
5
+ 的检查清单里确认本文件已同步更新。
6
+
7
+ ## 0.12.5
8
+
9
+ 可靠性版本:零配置首次启动的抗网络故障能力,以及多 VM 宿主机的内存管理。
10
+
11
+ ### 新增
12
+
13
+ - **零配置供应的下载可靠性。** 每个供应步骤都会自动重试临时性的网络/命令失败
14
+ (`setupRetries`,默认 3 次;`retryDelayMs` 指数退避),45 秒无进展看门狗会中止卡死的
15
+ 下载,而不是一直挂起。JDK 压缩包从 `.partial` 文件用 HTTP Range 续传,每次尝试都重新校验
16
+ SHA-256;命令行工具下载现在带 stall 超时、大小上限和可选校验
17
+ (`commandLineToolsUrl` / `commandLineToolsSha256`),并支持镜像地址;`sdkmanager`
18
+ 支持镜像/代理配置(`sdkManagerArgs`、`sdkManagerEnv`、`networkProxy`);供应开始前先检查
19
+ 累计可用磁盘预算(`minFreeDiskBytes`,默认 6 GB)。重试会在 `autoSetup.detail` 中报告
20
+ `attempt` 与 `nextDelayMs`,环境卡片在退避期间显示「retry n/m in Ns」。
21
+ - **内存感知的实例管理。** 新增 `lib/memory.js`:读取宿主内存并推导有效实例上限
22
+ (`memoryGuard`,`hostReserveMb` 4 GB,`estimatedVmMb` 3 GB,限制在 1–8 之间),通过
23
+ `GET /apk-vm/state`、`/apk-vm/emulators`、`GET /apk-vm/instances` 和 `apk_vm`
24
+ `list_instances` 的 `memory` 对象暴露。低内存宿主上创建/启动本地 VM 会给出可操作的错误,
25
+ 而不是把整机换页致死;`memoryPressureReap`(默认开启)先停止最久未使用的空闲本地 VM。
26
+ VM 实例卡片显示宿主内存、有效上限、预设以及每个 VM 的 RAM/vCPU 配置。
27
+ - **Lite 模式。** `vmPreset: lite` 把默认 AVD 和额外实例缩小到 1 GB 客机内存、2 vCPU、
28
+ SwiftShader GPU 以及 720×1280 / 30 fps 的 H.264 流(PNG 回退 1 fps),适合 8–16 GB 的
29
+ 宿主机。
30
+ - **卡死 guest 的自动恢复。** 如果 adb 仍能列出设备但客机 shell 已无响应,插件会在连续两次
31
+ 启动探测超时后判定为 wedged:通过模拟器控制台(以及进程树)结束该模拟器、隔离损坏快照,
32
+ 并冷启动重试一次,而不是永远停在 `booting`。`_refresh()` 在启动等待进行中不再于
33
+ `starting` 与 `stopped` 之间来回切换,实例卡片也为已停止的 VM 增加了「启动」按钮。
34
+ - **中文更新日志。** `CHANGELOG.zh-CN.md` 提供 0.12.x 条目的中文版本,发布说明也带中文摘要;
35
+ 发布检查清单要求保持同步。
36
+
37
+ ## 0.12.4
38
+
39
+ ### 修复
40
+
41
+ - **0.12.3 引入的 hypervisor 检测回归。** 启动速度统计的重构丢失了三个构造器初始化字段
42
+ (`_accelAvailable`、`_snapshotSave`、`_lastLaunchArgs`),导致 `_detectAcceleration()`
43
+ 在 `!== null` 处短路并返回 `undefined`,于是每次启动都误报「找不到可用的 CPU
44
+ hypervisor(AEHD/WHPX)」,即使 `emulator -accel-check` 报告可用。本次恢复这三个字段,
45
+ 并在 `spike/snapshot-recovery-test.mjs` 中断言其初始值以及 `_detectAcceleration()` 返回
46
+ 布尔值,防止该回归再次静默发布。
47
+
48
+ ## 0.12.3
49
+
50
+ ### 新增
51
+
52
+ - **Agent 操作手册。** 包内新增 [`docs/AGENTS.md`](docs/AGENTS.md),可在运行时通过
53
+ `apk_vm` 的 `guide` 动作(或 `GET /apk-vm/guide`)读取;内容覆盖标准循环、动作地图、
54
+ 设备像素与 CSS 坐标规则、WebView/CDP、实例与远端会话、错误恢复和安全边界。
55
+ - **新会话强制引导。** 每个新会话的第一次 `apk_vm` 调用会先返回一次操作手册
56
+ (`result.guideRequired: true`)而不执行原动作;阅读后重复调用即可。`action=guide`
57
+ 始终可用。
58
+ - **共享与专用 VM 指引。** 手册和 README 说明默认实例是共享、短命的设备,长时间调试建议
59
+ claim 一个专用 VM,并说明从其它会话进入共享 VM 会把客机重置回桌面。
60
+ - **Quick-boot 快照自愈。** 恢复时会让模拟器崩溃(Windows 访问冲突 `0xC0000005`)或看起来
61
+ 只写了一半(`snapshot.pb` 远新于 `ram.bin`)的快照会被自动隔离、以冷启动重试一次并重建;
62
+ 隔离情况通过 `status().snapshotRecovery` 暴露。
63
+ - **VM 命名与按会话自动选中。** 每个实例(包括 `default` 和远端会话)都可以有持久化的显示名
64
+ (`<profile>/.apk-vm/instance-names.json`);可用 `apk_vm` 的 `rename_instance`、
65
+ `POST /apk-vm/instances {"action":"rename",…}` 或面板的 Rename 按钮重命名。面板会跟随当前
66
+ 会话,选中租约属于该会话的 VM,而不是永远显示共享的 default。
67
+
68
+ ### 变更
69
+
70
+ - **DSH 兼容性元数据。** `package.json` 现在声明 `engines.dsh`
71
+ (`>=0.2.1-rc.3 || >=0.2.2-rc.1`)和 `dsh.compatibility.dshReleases`(`0.2.1-rc.3+`、
72
+ `0.2.2-rc.1+` → `compatible`),插件管理器和市场可以在安装/启用前校验支持的 DSH 版本。
73
+ README 增加「Supported DSH versions」一节,`docs/SUBMISSION.md` 列出同样的测试矩阵。
74
+
75
+ ## 0.12.2
76
+
77
+ ### 修复
78
+
79
+ - **面板版本标签显示 `v0.11.1`。** `client.js` 里手写的 `CLIENT_VERSION` 常量在 0.11.1 之后
80
+ 没有再更新,导致 0.12.0/0.12.1 的标题栏胶囊显示错误版本。现在胶囊优先使用宿主上报的版本,
81
+ 常量更新为当前版本,并且 `npm run check` 会运行 `scripts/check-version.mjs`,在
82
+ `CLIENT_VERSION` 与 `package.json` 不一致时让构建失败。
83
+
84
+ ## 0.12.1
85
+
86
+ ### 新增
87
+
88
+ - **远端 VM 多会话。** 远端主机成为一类 VM 来源:配置文件保存在
89
+ `<profile>/.apk-vm/remote-profiles.json`(只存校验后的非敏感字段,不存密钥内容),
90
+ `RemoteSessionManager` 可并发运行多个会话(`remoteMaxSessions`,默认 4),每个会话有自己
91
+ 的 AVD、adb 隧道、H.264 流和实例 id。
92
+ - **模拟器清单。** `GET /apk-vm/emulators` 把本地 AVD/设备状态与每个已保存的远端主机合并
93
+ (`lib/emulator-inventory.js`),面板增加「Available emulators」卡片。
94
+ - **虚拟摄像头。** 支持摄像头前后置模式与 `-virtualscene-poster` 海报,由
95
+ `GET/POST /apk-vm/camera`、面板 Media 卡片或 `cfg.camera` 管理(`lib/media.js`)。
96
+ - **虚拟麦克风。** 麦克风模式 `off` / `host` / `file`;file 模式把音频循环进虚拟
97
+ PulseAudio 源(null-sink + remap-source),在 Linux 和远端主机可用;由
98
+ `GET/POST /apk-vm/mic`、面板 Media 卡片或 `cfg.mic` 管理。
99
+ - **SSH 远端虚拟机(远端 VM 主机)。** `/apk-vm/remote` 现在把一台 SSH 可达主机变成 VM
100
+ 代理:转发本地回环端口到远端模拟器的 adb 端口,执行 `adb connect` 并把设备接入正常的
101
+ 启动等待/H.264/输入/调试链路。`launch: true` 会在远端用固定命令启动无窗口模拟器
102
+ (`-no-window -no-audio -no-boot-anim -gpu swiftshader_indirect`),`disconnect` 可以停止
103
+ 它。经验证的配置(主机/用户/端口/AVD,不含密钥)持久化在
104
+ `<profile>/.apk-vm/remote-profile.json`,面板卡片会预填并每两秒轮询隧道/启动状态。
105
+
106
+ ### 变更
107
+
108
+ - 新的插件图标(`icon.svg`,36×36):柠檬/草绿与紫色分层屏幕,替换原先在深色磁贴上几乎不可见
109
+ 的细线 `currentColor` 图标。
110
+ - 使用 0.12.0 面板 UI 重新生成演示截图(主面板、Activity 卡片、客机、Environment、APK 文件
111
+ 和 Rooted debug 卡片);Windows 用户名、真实 APK 名称/路径和助手头像做了高斯模糊。
112
+
113
+ ### 移除
114
+
115
+ - `docs/screenshot-sidebar.png`:由重新拍摄的面板与卡片截图替代。
116
+
117
+ ## 0.12.0
118
+
119
+ WebView 读取、记住已装 APK 和零配置首次运行。
120
+
121
+ - `webviewAction=eval` 现在返回真实值(普通 JSON 值直接返回;`DOMRect`、`MediaQueryList`
122
+ 这类不能按值穿过 JSON 的对象返回属性快照),不再需要截图。
123
+ - 记住已安装的 APK:通过工具或面板安装的 APK 记录在
124
+ `<profile>/.apk-vm/installed-apps.json`,上传的 APK 归档在 `<profile>/.apk-vm/apks`
125
+ (最新 10 个);客机重置/AVD 重建/插件升级后会按需自动重装(`autoReinstall`,默认开)。
126
+ - 零配置首次运行:`autoSetup`(默认开)在第一次使用时自动准备 JDK 17、SDK 命令行工具、
127
+ system image 和 AVD;可在环境卡片查看进度、取消和重试,也可用 `autoSetup: false` 保持手动。
128
+ - Agent 活动日志、设备韧性/恢复、quick-boot 快照恢复、多实例隔离等 0.12.0 的完整说明见
129
+ [`CHANGELOG.md`](CHANGELOG.md) 的 0.12.0 一节(含 Historical: planned 1.0.0 的历史记录)。
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.12.3` · Apache-2.0 · no npm runtime dependencies · no build step.
48
+ **Status:** `0.12.5` · 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).
@@ -96,7 +96,10 @@ and Agent-facing UI automation for development workflows.
96
96
  - Hardware virtualization: AEHD/WHPX on Windows, KVM on Linux, or HVF on macOS.
97
97
  - Node.js ≥ 20 only for the repository's headless checks; the plugin itself has no npm
98
98
  dependencies or build step.
99
- - Each running VM costs roughly 2.5 GB RAM; `maxInstances` defaults to 3 extra VMs.
99
+ - Each running VM costs roughly 2–3 GB of host RAM (`hw.ramSize` 1.5 GB default plus
100
+ emulator/GPU overhead); `maxInstances` defaults to 3 extra VMs. The `memoryGuard` (default on)
101
+ caps the effective count from total host RAM and the `vmPreset: lite` preset shrinks the guest
102
+ to 1 GB / 2 vCPU for 8–16 GB machines.
100
103
 
101
104
  **Permissions / risk**
102
105
 
@@ -197,6 +200,26 @@ key {"text":"HOME"} -> returned to launcher
197
200
  configured system image and the AVD, with live progress plus cancel/retry in the Environment
198
201
  card (`autoSetup` on `GET/POST /apk-vm/setup`). The normal `autoStart` flow then boots the VM;
199
202
  set `autoSetup: false` to keep setup manual.
203
+ - **Download resilience for the zero-config first run.** Every provisioning step retries
204
+ transient network failures with exponential backoff (`setupRetries: 3`, `retryDelayMs: 2000`)
205
+ and no-data stalls are detected by a 45 s no-progress watchdog, so a link that dies at 10 %
206
+ resumes instead of hanging. The JDK archive resumes from a `.partial` file with HTTP Range and
207
+ is re-verified against the SHA-256 checksum on each attempt; a configurable mirror
208
+ (`jdkMirror`) bypasses unreachable GitHub assets. The command-line-tools archive can point at
209
+ a mirror or proxy (`commandLineToolsUrl`, `commandLineToolsSha256`, `sdkManagerArgs`,
210
+ `sdkManagerEnv`, `networkProxy`), and the cumulative free-disk budget
211
+ (`minFreeDiskBytes`, default 6 GB) is checked before provisioning starts.
212
+ - **Memory guard, Lite mode and instance management.** A local emulator costs ~2–3 GB of host
213
+ RAM, so with `memoryGuard` on (default) the effective `maxInstances` is derived from total
214
+ host RAM (8 GB → 1; 16 GB → 3 with the default requested cap; clamped to 1–8), free host RAM
215
+ is checked at start, and a low-memory machine refuses to start another VM with a clear error
216
+ instead of swapping itself to death. On a 16 GB desktop that also runs an IDE and a browser,
217
+ keep `maxInstances` at 2 or switch to `vmPreset: lite`, which
218
+ shrinks the AVD to 1 GB RAM / 2 vCPU / SwiftShader with a 720p30 H.264 stream, and
219
+ `memoryPressureReap` (default on) stops the least-recently-used idle local VM when memory is
220
+ tight (extra VMs are stopped, never destroyed). The VM instances card shows host RAM, the
221
+ effective cap, the preset and the per-VM RAM/vCPU profile; `GET /apk-vm/state` and
222
+ `GET /apk-vm/emulators` expose the same `memory` object.
200
223
  - **Multi-agent isolation / multi-instance.** Several DSH Agents can drive separate VMs at the
201
224
  same time: each conversation owns a renewable lease on the VM it uses, so a second
202
225
  conversation never silently steals the first one's emulator. The first conversation gets the
@@ -732,14 +755,27 @@ config:
732
755
  maxInstances: 3 # extra VMs (default VM is always available)
733
756
  instanceIdleMs: 900000 # stop idle extra VMs after 15 min (AVD kept)
734
757
  instanceReapIntervalMs: 60000
758
+ memoryGuard: true # cap instances from host RAM; refuse low-memory starts
759
+ # hostReserveMb: 4096 # RAM kept for the host/other apps
760
+ # estimatedVmMb: 3072 # estimated cost of one local emulator
761
+ vmPreset: standard # standard | lite (1 GB / 2 vCPU / SwiftShader / 720p30)
762
+ memoryPressureReap: true # stop LRU idle VMs before creating another one
735
763
  leaseTtlMs: 1800000 # VM owner lease lifetime; renewed by apk_vm calls
736
764
  allowRemote: false # reject non-loopback VM API clients
737
765
  autoSetup: true # zero-config first run: auto-provision JDK 17 + SDK + image + AVD
766
+ setupRetries: 3 # retries per provisioning step (exponential backoff)
767
+ retryDelayMs: 2000
768
+ # minFreeDiskBytes: 6442450944 # cumulative free-disk budget before provisioning
738
769
  # jdkRoot: 'C:/tools/dsh-jdk' # where the auto-downloaded JDK 17 lives
739
770
  # jdkVersion: 17 # Temurin major version to provision (known-good table covers 17.0.21+9)
740
771
  # jdkMirror: 'https://mirrors.tuna.tsinghua.edu.cn/Adoptium' # override the JDK mirror fallback
741
772
  # activityDir: 'C:/tools/apk-vm-activity' # journal + screenshot storage (default <profile>/.apk-vm/activity)
742
773
  allowSetupDownloads: false # gate the optional manual system-image download action
774
+ # commandLineToolsUrl: 'https://example.com/commandlinetools-win-latest.zip' # mirror for the tools archive
775
+ # commandLineToolsSha256: '...' # checksum for the custom archive
776
+ # sdkManagerArgs: ['--no_https'] # passed verbatim to sdkmanager (mirrors / flags)
777
+ # sdkManagerEnv: { SDK_TEST_BASE_URL: 'https://mirror.example.com/android/repository/' }
778
+ # networkProxy: { host: 127.0.0.1, port: 7890 } # --proxy_* flags for sdkmanager only
743
779
  scrcpy: true
744
780
  scrcpyMaxSize: 960
745
781
  scrcpyMaxFps: 60
@@ -804,6 +840,11 @@ All keys are optional; defaults are shown in the **Default** column.
804
840
  | `mic` | `{ mode: "off" }` | Guest microphone: `off` / `host` (host input passthrough) / `file` (loop an audio file into a virtual source; Linux and remote hosts). Optional `backend`, `filePath`. |
805
841
  | `multiInstance` | `true` | Allow isolated extra VMs for concurrent Agents. |
806
842
  | `maxInstances` | `3` | Maximum number of extra instances (in addition to the default VM). Each running instance costs guest RAM/CPU. |
843
+ | `memoryGuard` | `true` | Cap the effective instance count from host RAM and refuse to start a local VM when free memory is below the reserve. Remote sessions are not counted. |
844
+ | `hostReserveMb` | `4096` | Host RAM kept free when computing the effective cap / deciding whether a new VM fits. |
845
+ | `estimatedVmMb` | `3072` | Estimated host RAM used by one local emulator (AVD RAM + qemu/GPU overhead) for the guard and the panel estimate. |
846
+ | `vmPreset` | `standard` | `standard` or `lite` (1 GB guest RAM, 2 vCPU, SwiftShader GPU, 1 fps PNG / 720p30 H.264). Applies to the default AVD (rewritten on activation) and to extra instances. |
847
+ | `memoryPressureReap` | `true` | When memory is tight, stop the least-recently-used idle local VM before creating another one. Extra VMs are stopped, never destroyed. |
807
848
  | `instanceIdleMs` | `900000` | Stop an extra instance after this long without panel frames, a video client, or an Agent command (AVD is kept). |
808
849
  | `instanceReapIntervalMs` | `60000` | How often the idle reaper checks extra instances. |
809
850
  | `leaseTtlMs` | `1800000` | Lifetime of a VM owner lease. Every `apk_vm` call that routes to the VM renews it; set `0` to disable expiry. |
@@ -813,6 +854,14 @@ All keys are optional; defaults are shown in the **Default** column.
813
854
  | `jdkRoot` | `~/.dsh/apk-vm/jdk` | Where the auto-downloaded Temurin JDK 17 is installed. A system JDK / `JAVA_HOME` is preferred when present. |
814
855
  | `jdkVersion` | `17` | Temurin major version to provision when `autoSetup` needs a JDK. |
815
856
  | `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. |
857
+ | `setupRetries` | `3` | Automatic retries per provisioning step after a transient network/command failure (exponential backoff). |
858
+ | `retryDelayMs` | `2000` | Base delay between provisioning retries; doubled each attempt. |
859
+ | `minFreeDiskBytes` | `6442450944` (6 GB) | Cumulative free-disk budget checked before provisioning starts (JDK + tools + image + AVD). |
860
+ | `commandLineToolsUrl` | Google archive | Optional mirror URL for the command-line-tools archive (checksum option below). |
861
+ | `commandLineToolsSha256` | — | Optional SHA-256 for `commandLineToolsUrl`; the download is verified like the JDK. |
862
+ | `sdkManagerArgs` | `[]` | Extra arguments passed verbatim to `sdkmanager` (for example `["--no_https"]` for a mirror). |
863
+ | `sdkManagerEnv` | `{}` | Extra environment variables for `sdkmanager` (for example `SDK_TEST_BASE_URL` for an SDK mirror). |
864
+ | `networkProxy` | — | `{host, port, user, password}` translated into `--proxy_*` flags for `sdkmanager` only; the plugin itself never proxies its own requests. |
816
865
  | `activityDir` | `<profile>/.apk-vm/activity` | Where the Agent activity journal (`activity.jsonl`) and its screenshots are stored. |
817
866
  | `frameFps` | `2` | PNG fallback target frame rate, 1–10 (the H.264 path is not affected). |
818
867
  | `scrcpy` | `true` | Enable the H.264/WebCodecs transport. |
@@ -831,6 +880,15 @@ per-action availability. It also carries the auto-setup state: `autoSetupEnabled
831
880
  finishedAt }`; `POST /apk-vm/setup` with `{ action: "auto-setup" }` starts/retries provisioning
832
881
  and `{ action: "cancel-auto-setup" }` cancels it.
833
882
 
883
+ `GET /apk-vm/state`, `GET /apk-vm/emulators`, `GET /apk-vm/instances` and the
884
+ `apk_vm` `list_instances` action also expose a `memory` object:
885
+ `{ available, totalMb, freeMb, reserveMb, estimatedVmMb, guard, pressureReap,
886
+ requestedMaxInstances, effectiveMaxInstances, preset: { name, ramSizeMb, cores, ... },
887
+ limited, reason }`. It is the same object the panel uses for the host-memory line and the
888
+ instance cap. `POST /apk-vm/instances` (create) and `create_instance` honour it: when a local VM
889
+ does not fit, the request fails with an actionable error, or `memoryPressureReap` stops an idle
890
+ VM first.
891
+
834
892
  ---
835
893
 
836
894
  ## Architecture
@@ -865,6 +923,7 @@ and `{ action: "cancel-auto-setup" }` cancels it.
865
923
  | 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. |
866
924
  | 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. |
867
925
  | 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`). |
926
+ | Memory | [lib/memory.js](lib/memory.js) | Host RAM snapshot, effective instance cap derived from RAM, `standard` / `lite` preset resolution and the low-memory start checks used by `lib/instances.js`; exposed as `memory` on `GET /apk-vm/state`, `/apk-vm/emulators` and `/apk-vm/instances`. |
868
927
  | 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. |
869
928
  | Device bridge | `adb` from Android SDK platform-tools | install / launch / screencap / input / logcat / file push-pull. |
870
929
  | Plugin runtime | DSH plugin APIs (`slots`, `locale`, `webServer`, `tools`, `dsh.client`) | Sidebar entry, main panel, same-origin HTTP/WebSocket control plane, agent tool. |
@@ -1095,6 +1154,13 @@ screen legitimately shows a low FPS. The 60 Hz animation test sustains ~59 fps o
1095
1154
  The `Target FPS` selector applies only to the PNG fallback; the H.264 path is capped by
1096
1155
  `scrcpyMaxFps`.
1097
1156
 
1157
+ Host memory is the other cost driver: each local emulator costs roughly 2–3 GB (1.5 GB AVD RAM
1158
+ plus qemu/GPU overhead). With `memoryGuard: true` the effective instance cap is derived from
1159
+ total RAM minus `hostReserveMb` (4 GB) divided by `estimatedVmMb` (3 GB), then clamped by
1160
+ `maxInstances`: 8 GB → 1 VM, 16 GB → 3 (the default requested cap), 32 GB+ → 3. A 16 GB desktop
1161
+ that also runs an IDE and a browser is happier with `maxInstances: 2`; `vmPreset: lite` lowers
1162
+ the guest to 1 GB / 2 vCPU / SwiftShader and a 720p30 stream when you need a third.
1163
+
1098
1164
  ---
1099
1165
 
1100
1166
  ## Verification
@@ -1188,16 +1254,33 @@ card starts provisioning automatically; while it runs you see the current step p
1188
1254
 
1189
1255
  ### Auto-setup fails or is stuck
1190
1256
 
1191
- The card shows the last step and the error (`autoSetup.error` in `GET /apk-vm/setup`). Common
1192
- causes: no network access to `api.adoptium.net` / `dl.google.com` (or to `github.com`, where
1193
- Adoptium hosts the JDK archive — the built-in Tsinghua mirror is tried automatically), a proxy or
1194
- firewall, an antivirus locking freshly extracted files, or less than ~3 GB free disk space. Press
1195
- **Retry**: the JDK archive is reused when its SHA-256 checksum matches, so retries do not
1196
- re-download it; a mirror can be pinned with `jdkMirror` (or `DSH_APK_VM_JDK_MIRROR`).
1197
- You can also set `autoSetup: false` and provision manually (see
1257
+ The card shows the last step and the error (`autoSetup.error` in `GET /apk-vm/setup`). Each
1258
+ provisioning step is retried automatically (`setupRetries`, default 3, exponential backoff) and
1259
+ downloads that stop transferring data are aborted by a 45 s no-progress watchdog, so a link that
1260
+ dies mid-download recovers instead of hanging. Common causes: no network access to
1261
+ `api.adoptium.net` / `dl.google.com` (or to `github.com`, where Adoptium hosts the JDK archive —
1262
+ the built-in Tsinghua mirror is tried automatically), a proxy or firewall, an antivirus locking
1263
+ freshly extracted files, or less than the required free disk space (`minFreeDiskBytes`, default
1264
+ 6 GB, is checked before provisioning). Press **Retry**: the JDK archive is reused when its
1265
+ SHA-256 checksum matches and resumes from a `.partial` file with HTTP Range otherwise; a mirror
1266
+ can be pinned with `jdkMirror` (or `DSH_APK_VM_JDK_MIRROR`). For proxies and mirrors behind the
1267
+ SDK downloads set `networkProxy` (translated to `sdkmanager --proxy_*` flags), `sdkManagerArgs`,
1268
+ `sdkManagerEnv`, or point `commandLineToolsUrl` / `commandLineToolsSha256` at your own tools
1269
+ archive. You can also set `autoSetup: false` and provision manually (see
1198
1270
  [step 3](#3-provide-an-android-sdk-system-image-and-avd-automatic-by-default)); parts that already
1199
1271
  succeeded are skipped on the next attempt.
1200
1272
 
1273
+ ### The VM refuses to start because the host is low on memory
1274
+
1275
+ With `memoryGuard: true` (default) a local emulator is only started when the host has room for
1276
+ it: total RAM minus `hostReserveMb` (4 GB) divided by `estimatedVmMb` (~3 GB) gives the
1277
+ effective instance cap (`GET /apk-vm/state` → `memory.effectiveMaxInstances`; the panel shows it
1278
+ on the VM instances card). Close other emulators/apps, raise `hostReserveMb`/`estimatedVmMb` only
1279
+ after measuring, set `vmPreset: lite` to shrink new guests to 1 GB / 2 vCPU, enable
1280
+ `memoryPressureReap` (default) so idle VMs are stopped first, or move work to a remote VM
1281
+ (`/apk-vm/remote`, see [Remote VM host over SSH](#remote-vm-host-over-ssh)). `memoryGuard: false`
1282
+ disables the check.
1283
+
1201
1284
  ### "No usable CPU hypervisor (AEHD/WHPX) was found"
1202
1285
 
1203
1286
  The plugin fails fast (`requireAccel: true` by default) because an x86_64 system image cannot
@@ -1423,6 +1506,11 @@ before pointing the DSH Web UI at an untrusted network.
1423
1506
  services; network activity is limited to `autoSetup` provisioning (Temurin JDK from
1424
1507
  `api.adoptium.net` or its mirror, then the SDK packages/image through the user's own
1425
1508
  `sdkmanager`, which contacts Google's SDK repository) and the same-origin DSH Web server.
1509
+ - **Provisioning proxy/mirror settings stay with the child process.** `networkProxy` is translated
1510
+ into `sdkmanager --proxy_*` flags only, and `sdkManagerArgs` / `sdkManagerEnv` are passed to the
1511
+ child `sdkmanager` invocation only. The plugin never proxies its own requests, and none of these
1512
+ values (including a proxy password) is written to the activity journal or exposed on HTTP
1513
+ routes.
1426
1514
  - **The Agent activity log is local-only.** Tool-call journal entries and screenshots are written
1427
1515
  under `<profile>/.apk-vm/activity` on this host and are never sent anywhere. They can contain
1428
1516
  screen content and command arguments, so clear the journal before sharing a recording of the
@@ -1464,6 +1552,17 @@ customization remain research notes in [DESIGN.md](DESIGN.md) §8.
1464
1552
  - **The virtual microphone `file` mode needs a Linux/PulseAudio host.** On Windows only `host`
1465
1553
  passthrough is available, and camera/mic changes apply to a running default VM only after it is
1466
1554
  restarted.
1555
+ - **The memory guard is an estimate, not a hard limit.** It reads host totals (`os` APIs), assumes
1556
+ `estimatedVmMb` per local VM and refuses/clamps new local VMs, but it cannot stop an externally
1557
+ started emulator and it counts remote sessions as zero host RAM. Set `memoryGuard: false` if the
1558
+ estimate is too conservative for your machine.
1559
+ - **`vmPreset: lite` resizes hardware profiles, not a running guest.** The default AVD's
1560
+ `hw.ramSize`/`hw.cpu.ncore` are rewritten on activation and extra instances get them at create
1561
+ time; an already running VM must be restarted to pick them up.
1562
+ - **Download resume is partial.** The JDK archive resumes from `.partial` with HTTP Range and is
1563
+ checksum-verified on every retry; the command-line-tools archive, SDK packages and system image
1564
+ are retried per step (whole-file), and `sdkmanager` owns its own retry/proxy behaviour. The 45 s
1565
+ no-progress watchdog applies to the JDK and command-line-tools downloads.
1467
1566
 
1468
1567
  - **Windows x64 and Linux x86_64 are the end-to-end verified platforms.** macOS SDK/adb/
1469
1568
  emulator/AVD discovery is implemented and `arm64` hosts automatically select the