dsh-apk-vm 0.12.4 → 0.13.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/cordis.patch.yml CHANGED
@@ -45,6 +45,39 @@
45
45
  # quick reuse. start()/the next Agent action boots it again.
46
46
  instanceIdleMs: 900000
47
47
  instanceReapIntervalMs: 60000
48
+ # Resident shared default VM: a lease can be released, but the VM and its
49
+ # AVD are never released or deleted. After sharedSuspendAfterMs idle the
50
+ # default VM suspends into its quick-boot snapshot (state "suspended",
51
+ # ~6 s to resume); after sharedStopAfterMs it is marked "stopped" (the
52
+ # snapshot and AVD are kept). Tool calls, panel actions and video clients
53
+ # reset the idle timer and a later start resumes it on demand.
54
+ sharedResident: true
55
+ sharedSuspendAfterMs: 300000
56
+ sharedStopAfterMs: 3600000
57
+ # Operation locks (lock_vm / panel Lock): a locked VM rejects other
58
+ # agents and users until the lock owner (or a local admin) unlocks it.
59
+ # lockEnforcement: all = hard lock for everyone; agents = only other
60
+ # agents are blocked, the local panel can still operate; off = locks are
61
+ # advisory markers only (never block).
62
+ lockEnforcement: all
63
+ # lockControl: all = agents or the panel may lock/unlock; user = only the
64
+ # panel/user can lock/unlock (tool lock_vm/unlock_vm return an error).
65
+ lockControl: all
66
+ # Host memory guard: refuse to start another local VM when the machine is
67
+ # low on memory, and cap the effective instance count from total RAM.
68
+ # A local emulator costs ~2-3 GB (AVD 1.5 GB + qemu/GPU overhead), so
69
+ # with 4 GB reserved for the host this allows 2 VMs on 16 GB and 1 on
70
+ # 8 GB (clamped to 1..8). Remote sessions do not count.
71
+ memoryGuard: true
72
+ # hostReserveMb: 4096
73
+ # estimatedVmMb: 3072
74
+ # Lite mode: smaller AVD hardware profile for memory-constrained hosts
75
+ # (1 GB guest RAM, 2 vCPU, SwiftShader GPU, 1 fps PNG / 720p30 H.264).
76
+ # Applies to the default AVD and to extra instances. standard | lite.
77
+ vmPreset: standard
78
+ # When memory is tight, stop the least recently used idle local VM
79
+ # before creating another one (extra VMs are stopped, never destroyed).
80
+ memoryPressureReap: true
48
81
  # H.264 stream: up to 60 fps via the vendored scrcpy server; 960 keeps
49
82
  # 540x960 video (plenty for the panel) so software WebCodecs decode can
50
83
  # sustain ~60 fps.
@@ -77,6 +110,29 @@
77
110
  # Manual (user-triggered only) system-image download from the
78
111
  # Environment card; autoSetup does not need this flag.
79
112
  allowSetupDownloads: false
113
+ # Download reliability for the zero-config first run: every provisioning
114
+ # step retries transient network failures with exponential backoff
115
+ # (setupRetries, retryDelayMs), no-data stalls are detected by a 45 s
116
+ # no-progress watchdog on the JDK/command-line-tools downloads, and the
117
+ # cumulative free-disk budget is checked before provisioning starts.
118
+ setupRetries: 3
119
+ retryDelayMs: 2000
120
+ # minFreeDiskBytes: 6442450944
121
+ # Optional mirrors/proxies for the Android SDK command-line tools and
122
+ # sdkmanager (the JDK already has jdkMirror). sdkManagerArgs are passed
123
+ # verbatim to sdkmanager; networkProxy becomes --proxy_* flags and is
124
+ # used only by sdkmanager, never by the plugin itself. commandLineToolsUrl
125
+ # overrides the Google command-line-tools archive.
126
+ # commandLineToolsUrl: 'https://example.com/commandlinetools-win-latest.zip'
127
+ # commandLineToolsSha256: '...'
128
+ # sdkManagerArgs: ['--no_https']
129
+ # sdkManagerEnv:
130
+ # SDK_TEST_BASE_URL: 'https://mirror.example.com/android/repository/'
131
+ # networkProxy:
132
+ # host: 127.0.0.1
133
+ # port: 7890
134
+ # user: ''
135
+ # password: ''
80
136
  # The VM routes accept root shell/debug actions, so they reject
81
137
  # non-loopback clients by default even if the DSH web UI is exposed to
82
138
  # the LAN. Set true only behind your own authenticated reverse proxy.
package/docs/AGENTS.md CHANGED
@@ -26,9 +26,11 @@ or `GET /apk-vm/guide`. The tool description also points here.
26
26
 
27
27
  ## Mental model
28
28
 
29
- - The VM is a **leased device**. Leases have a scope (`shared`, `conversation`, `project`).
30
- A VM owned by another conversation returns a `vm-busy` error; `ownerForce: true` is an
31
- explicit takeover and should only be used when the user asked for it.
29
+ - The VM is a **leased device**. Leases have a scope (`shared`, `conversation`, `project`) and are
30
+ persisted to `<profile>/.apk-vm/leases.json`. A VM owned by another conversation returns a
31
+ `vm-busy` error (or `vm-takeover-required` for an admin panel action); `ownerForce: true`
32
+ (alias `force: true`) is an explicit takeover and should only be used when the user asked for
33
+ it. Dedicated (`conversation`/`project`) leases stay reserved for 24 h by default.
32
34
  - **Only `ready` VMs accept input.** `info` returns `state`, `root`, `serial`, `size`,
33
35
  `density`, `dpr` and `coordinateMap`.
34
36
  - `instance` selects the VM: omit it to use the calling agent's assignment (the first
@@ -74,7 +76,7 @@ or `GET /apk-vm/guide`. The tool description also points here.
74
76
  (`overlay: true` draws UIAutomator boxes), `record`, `perf`, `rotate`
75
77
  - **Instances & leases:** `list_instances`, `create_instance`, `rename_instance`, `destroy_instance`,
76
78
  `owner_status`, `claim_vm`, `release_vm`, `ownerScope` (`shared|conversation|project`),
77
- `ownerForce`
79
+ `ownerForce` (alias `force`)
78
80
  - **Network / environment:** `network`, `proxy`, `env_snapshot`, `env_restore`, `install_ca`
79
81
  - **Flows and skills:** `flow_*` (record/replay a journey), `skill_*` (persisted app-operation
80
82
  skills with a Control Codebook), `control_*` (semantic-code tap/input, more layout-stable
@@ -116,10 +118,13 @@ call. `action=guide` is always available and never touches a VM.
116
118
 
117
119
  ## Shared vs dedicated VMs
118
120
 
119
- The default instance is a **shared** device: every conversation may use it, it is
120
- short-lived, and entering it from a different conversation resets the guest to the home
121
- screen (so you never inherit someone else's foreground app). Use it for one-off inspection
122
- and short automations.
121
+ The default instance is a **shared, resident** device: every conversation may use it, and it is
122
+ never released or deleted. When idle for `sharedSuspendAfterMs` (5 min) it suspends into its
123
+ quick-boot snapshot (state `suspended`; a start resumes it in ~6 s); after `sharedStopAfterMs`
124
+ (1 h) suspended it is marked `stopped`. The AVD and snapshot are kept. Any `apk_vm` call, panel
125
+ action or video client resets the idle timer, and a later start resumes it on demand.
126
+ Entering it from a different conversation resets the guest to the home screen (so you never
127
+ inherit someone else's foreground app). Use it for one-off inspection and short automations.
123
128
 
124
129
  If this conversation needs a long-lived debugging device — logins, installed apps, stable
125
130
  state — claim a dedicated VM instead of holding the shared one:
@@ -130,7 +135,22 @@ state — claim a dedicated VM instead of holding the shared one:
130
135
  - `owner_status` inspects leases; `release_vm` gives a VM back.
131
136
 
132
137
  Don't keep several agents on one shared VM. Leases are visible in the panel, and a VM owned
133
- by another conversation returns `vm-busy` unless you force a takeover (`ownerForce=true`).
138
+ by another conversation returns `vm-busy` unless you force a takeover (`ownerForce=true`, alias
139
+ `force=true`). Dedicated reservations survive plugin restarts; the panel needs an explicit takeover
140
+ (`x-apk-vm-takeover: 1`) for a VM held by another owner.
141
+
142
+ ## VM operation locks
143
+
144
+ `lock_vm` / `unlock_vm` (or `POST /apk-vm/ownership` actions `lock`/`unlock`) make the current
145
+ owner's lease a hard lock. While locked, every mutating request from another agent or the panel
146
+ is rejected with `409 vm-locked`; `ownerForce`/takeover cannot break it. The panel owner card
147
+ shows the lock and offers Lock/Unlock; a local admin can force-unlock. A lock does not block
148
+ read-only calls (`owner_status`, `list_instances`, `info`).
149
+
150
+ The plugin configuration can relax this: `lockEnforcement: agents` blocks only other agents
151
+ (the local panel can still operate a locked VM) and `off` makes locks advisory only;
152
+ `lockControl: user` limits lock/unlock to the panel/user (`lock_vm`/`unlock_vm` return a
153
+ `vm-lock-restricted` error).
134
154
 
135
155
  ## Instances and remote VMs
136
156
 
@@ -142,6 +162,26 @@ by another conversation returns `vm-busy` unless you force a takeover (`ownerFor
142
162
  - Each instance has its own WebSocket (`/apk-vm/instances/<id>/ws`), unless the panel falls back
143
163
  to PNG frames.
144
164
 
165
+ ## Host memory, Lite mode and instance caps
166
+
167
+ A local emulator costs roughly 2–3 GB of host RAM. With `memoryGuard` on (the default) the
168
+ effective `maxInstances` is derived from total host RAM (`hostReserveMb` 4 GB reserve,
169
+ `estimatedVmMb` 3 GB per VM): **8 GB → 1 VM, 16 GB → 3 with the default requested cap,
170
+ 32 GB+ → 3**. A 16 GB desktop that also runs an IDE and a browser is happier with
171
+ `maxInstances: 2`, or with `vmPreset: lite` (1 GB guest RAM / 2 vCPU / SwiftShader / 720p30),
172
+ which can fit a third VM.
173
+
174
+ - `create_instance` / local starts can fail with a `host memory guard` error: stop an idle
175
+ instance, lower `maxInstances`, or pass `memoryOverride: true` when you knowingly
176
+ over-commit.
177
+ - `memoryPressureReap` (on by default) stops the least-recently-used idle local VM when free
178
+ host memory is low; extra VMs are only stopped, never destroyed.
179
+ - `list_instances`, `GET /apk-vm/state` and `/apk-vm/emulators` expose the same `memory`
180
+ object: `effectiveMaxInstances`, `requestedMaxInstances`, `limited`, `host.freeMb/totalMb`,
181
+ the active `profile` and `pressureReap`.
182
+ - The guard estimates from host totals: an emulator started outside the plugin, and remote
183
+ sessions, are not counted. Use Lite mode on 8–16 GB hosts when running several agents.
184
+
145
185
  ## VM names and per-conversation selection
146
186
 
147
187
  - Every VM can have a human-friendly display name; ids stay stable (`default`, `frontend`,
@@ -159,11 +199,21 @@ by another conversation returns `vm-busy` unless you force a takeover (`ownerFor
159
199
  readiness usually arrives within a couple of seconds.
160
200
  - Screenshot or device timeouts return structured error codes (for example
161
201
  `EDEVICE_UNRESPONSIVE`); if the guest is wedged, `stop` + `start` is the recovery.
162
- - `vm-busy`: inspect with `owner_status`; `release_vm` frees a lease, `claim_vm` with
163
- `ownerForce: true` is an explicit takeover.
202
+ - `vm-busy` / `vm-takeover-required`: inspect with `owner_status`; `release_vm` frees a lease,
203
+ `claim_vm` with `ownerForce: true` (alias `force: true`) is an explicit takeover. A reserved
204
+ lease stays reserved until `reservedUntil`, even across plugin restarts.
164
205
  - Failed calls are journaled too (`ok: false` with the error); read the activity log before
165
206
  retrying the same action.
166
-
207
+ - Destructive actions need explicit confirmation: `destroy_instance` requires `confirm: true`,
208
+ and `clean_storage` requires `confirm: true` for `snapshots`, `orphan-avds`,
209
+ `corrupt-snapshots` and `crash-dumps`. Never set `confirm` before checking the instance name
210
+ and the reported reclaimable bytes.
211
+ - An action that has to boot a VM now fails after about 120 s (explicit `start`: 180 s) with an
212
+ actionable error instead of blocking for the 20-minute boot timeout; inspect `state`/
213
+ `logTail`, stop a wedged VM, then retry.
214
+
215
+ - `vm-locked`: the VM is hard-locked by its owner; `ownerForce`/takeover does not override a
216
+ lock. The lock owner can `unlock_vm`; the local panel offers Unlock (admin can force-unlock).
167
217
  ## Suggested agent instructions
168
218
 
169
219
  ```text
package/docs/PRIVACY.md CHANGED
@@ -30,6 +30,12 @@ reporting, advertising or a remote backend.
30
30
  default) and can be cleared from the panel or with `POST /apk-vm/activity/clear`.
31
31
  Because entries can contain screen content and command arguments (typed text is recorded
32
32
  as a character count only), clear the journal before sharing the panel or its recordings.
33
+ - **Persisted VM leases.** `<profile>/.apk-vm/leases.json` stores the owner key, scope, session id,
34
+ workspace, display label and dedicated-reservation deadline for VM leases so that a
35
+ `conversation`/`project` VM stays reserved across DSH restarts. It is written only for VM
36
+ ownership bookkeeping, stays on this host and contains no screen content; delete the file
37
+ (or release the lease) to clear it. Leases record the DSH session id and workspace path, which
38
+ may be visible to other local conversations if the panel or activity log is shared.
33
39
  - **Remembered installed apps.** `<profile>/.apk-vm/installed-apps.json` stores the APK path,
34
40
  package name, label, launch activity and instance for APKs installed through the plugin, and
35
41
  archived copies live under `<profile>/.apk-vm/apks` (newest 10). Both stay on this host and are
@@ -50,7 +56,11 @@ reporting, advertising or a remote backend.
50
56
  base. Every archive is verified against Adoptium's published SHA-256 checksum; the plugin sends
51
57
  no identifying headers, cookies or user data. It then runs the user's own `sdkmanager` for the
52
58
  Android SDK command-line tools, build-tools, platform and system image from the official Google
53
- Android SDK repository. The plugin does not proxy or collect those downloads. Those downloads
59
+ Android SDK repository. The plugin does not proxy or collect those downloads. Optional
60
+ overrides (`jdkMirror`, `commandLineToolsUrl`/`commandLineToolsSha256`, `sdkManagerArgs`,
61
+ `sdkManagerEnv`, `networkProxy`) only redirect the plugin's own downloader and the
62
+ `sdkmanager` child process to a user-chosen mirror or proxy; proxy credentials passed this way
63
+ are used only for that child process and are never logged. Those downloads
54
64
  are size- and time-bounded and HTTPS-only, and can be disabled with `autoSetup: false` (the
55
65
  Environment card then offers the manual actions as before). No analytics, telemetry,
56
66
  advertising or remote backend is involved, and no third-party endpoint other than the ones
package/docs/RELEASING.md CHANGED
@@ -8,12 +8,13 @@ Repository: <https://github.com/yuxiaole-bili/dsh-apk-vm>.
8
8
  ## Publish to npm
9
9
 
10
10
  The package is intentionally public and has no build step; publishing the repository directory is
11
- enough:
11
+ enough. **The default registry on the reference host is a mirror (`registry.npmmirror.com`);
12
+ publishing must target npm explicitly**, otherwise `npm publish` fails with `E404`:
12
13
 
13
14
  ```bash
14
- npm login # once per machine, as the npm account that owns dsh-apk-vm
15
- npm publish --access public # prepublish uses the packed file list
16
- npm view dsh-apk-vm version # verify the published version
15
+ npm whoami --registry=https://registry.npmjs.org # once per machine/account
16
+ npm publish --access public --registry=https://registry.npmjs.org
17
+ npm view dsh-apk-vm version --registry=https://registry.npmjs.org # verify
17
18
  ```
18
19
 
19
20
  The GitHub release tarball and the npm tarball are produced from the same `npm pack` output.
@@ -78,7 +79,10 @@ The in-app Plugin Manager title/description comes from `locale/en.json` and `loc
78
79
 
79
80
  ## Versioning
80
81
 
81
- - `package.json` and `CHANGELOG.md` move together.
82
+ - `package.json`, `CHANGELOG.md` and `CHANGELOG.zh-CN.md` move together (the Chinese file mirrors
83
+ the 0.12.x entries; the pre-0.12 history stays English-only in `CHANGELOG.md`).
84
+ - `client.js` `CLIENT_VERSION` must match `package.json`; `npm run check` runs
85
+ `scripts/check-version.mjs` and fails the release if they disagree.
82
86
  - Use `0.x.y` while the plugin API/route surface may still change.
83
87
  - Keep `SECURITY.md` supported-version table in sync.
84
88
  - Tag the release (`git tag -a v0.3.12 -m ...`) and attach the tarball produced by
@@ -94,6 +98,8 @@ The in-app Plugin Manager title/description comes from `locale/en.json` and `loc
94
98
  - [ ] Demo media (if any) recorded on a real host and listed in `docs/README.md`
95
99
  - [ ] README install instructions use `<path-to-repo>` / user-chosen paths
96
100
  - [ ] Release notes call out known limitations (Windows E2E only, no audio, etc.)
101
+ - [ ] `CHANGELOG.zh-CN.md` updated for the release (0.12.5+ promise; keep it in sync with
102
+ `CHANGELOG.md`)
97
103
 
98
104
  ## Known limitations to state in the release
99
105