dsh-apk-vm 0.12.5 → 0.14.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/CHANGELOG.md +92 -0
- package/CHANGELOG.zh-CN.md +73 -0
- package/README.md +94 -28
- package/client.js +250 -7
- package/cordis.patch.yml +25 -1
- package/docs/AGENTS.md +52 -12
- package/docs/PRIVACY.md +6 -0
- package/index.js +328 -31
- package/lib/activity-log.js +22 -0
- package/lib/android.js +174 -2
- package/lib/http-owner.js +101 -10
- package/lib/instances.js +210 -5
- package/lib/lease-store.js +67 -0
- package/lib/setup.js +27 -1
- package/lib/storage.js +125 -4
- package/lib/vm-ownership.js +233 -20
- package/package.json +4 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,97 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.14.0 — 2026-11-21
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **ARM translation (arm64-v8a APKs on x86_64 hosts).** `armTranslation: true` selects the
|
|
8
|
+
Google APIs image (`system-images;android-34;google_apis;x86_64`), which ships Google's
|
|
9
|
+
`libndk_translation.so` native bridge plus the `arm64-v8a` ABI, so arm64-only APKs install and
|
|
10
|
+
run without bundling a proprietary blob. `apk_vm info` and `/apk-vm/state` report the guest
|
|
11
|
+
`abilist`/`nativeBridge`/`armTranslation` state, and an APK whose native libraries match no
|
|
12
|
+
guest ABI now fails with an actionable error that names this option. The AOSP `default` image
|
|
13
|
+
remains the zero-config default.
|
|
14
|
+
|
|
15
|
+
## 0.13.0
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- **Persistent VM leases and reserved dedicated VMs.** Leases are now persisted to
|
|
20
|
+
`<profile>/.apk-vm/leases.json` and restored when the plugin starts, so a dedicated
|
|
21
|
+
`conversation`/`project` VM stays reserved for its owner across DSH restarts instead of being
|
|
22
|
+
handed to the first session that asks. Dedicated leases carry a `reservedUntil` deadline
|
|
23
|
+
(`leaseReservationTtlMs`, default 24 hours); after it expires the VM can be claimed normally
|
|
24
|
+
again.
|
|
25
|
+
- **Explicit and audited takeover.** A lease held by another owner now reports the owner short id
|
|
26
|
+
and reservation deadline in `409 vm-busy` / `409 vm-takeover-required` responses. The panel shows
|
|
27
|
+
the reservation, keeps a VM held by another owner read-only and offers a **Take over** button;
|
|
28
|
+
admin mutations that are not an explicit takeover are rejected with `vm-takeover-required`
|
|
29
|
+
(`x-apk-vm-takeover: 1`) instead of silently operating another owner's VM. Claim, release and
|
|
30
|
+
takeover transitions are recorded in the activity journal with the previous and incoming owner.
|
|
31
|
+
- **`force` alias for `ownerForce`.** `apk_vm` accepts `force: true` as a synonym for
|
|
32
|
+
`ownerForce: true`, so the error text and the actual parameter no longer disagree;
|
|
33
|
+
`claim_vm`/`release_vm` report the previous owner on takeover.
|
|
34
|
+
- **Owner attribution in the activity journal.** Activity entries record `owner`
|
|
35
|
+
(`key`, `label`, `scope`, `role`) — sanitized and redacted like every other field — so "who did
|
|
36
|
+
what" stays visible when several conversations and the panel drive the same machine.
|
|
37
|
+
- **Resident shared default VM.** The default VM is never released or deleted. After
|
|
38
|
+
`sharedSuspendAfterMs` idle (default 5 minutes) it suspends into its quick-boot snapshot (state
|
|
39
|
+
`suspended`, about 6 seconds to resume) and after `sharedStopAfterMs` (default 1 hour) it is
|
|
40
|
+
marked `stopped` with the snapshot and AVD kept. Tool calls, panel actions and video clients
|
|
41
|
+
reset the idle timer and a later start resumes it on demand.
|
|
42
|
+
- **Storage accounting for crash debris and orphan AVDs.** `GET /apk-vm/storage` now reports
|
|
43
|
+
quarantined `*.corrupt-*` snapshot backups, emulator crash dumps and a `reclaimableBytes`
|
|
44
|
+
total. `POST /apk-vm/storage` gained `corrupt-snapshots` and `crash-dumps` actions (both
|
|
45
|
+
require `confirm: true`), and the Storage card shows the reclaimable amount with cleanup
|
|
46
|
+
buttons.
|
|
47
|
+
- **Confirmations for destructive actions.** `destroy_instance` now requires `confirm: true`,
|
|
48
|
+
and the panel asks for a second click, so neither an agent nor a mis-click can delete an
|
|
49
|
+
instance AVD and its data by accident. The instance DELETE route also rejects requests
|
|
50
|
+
without `?confirm=1`.
|
|
51
|
+
- **VM operation locks.** `lock_vm` / `unlock_vm` (and `POST /apk-vm/ownership` actions
|
|
52
|
+
`lock`/`unlock`) turn the caller's lease into a hard lock: while locked, every mutating
|
|
53
|
+
request from another agent or the panel is rejected with `409 vm-locked`; `ownerForce` and
|
|
54
|
+
takeover do not break a lock, and only the lock owner (or a local admin unlock) can control
|
|
55
|
+
the VM. Locks are persisted in `leases.json` and the panel shows Lock/Unlock. Two configuration
|
|
56
|
+
keys tune the policy: `lockEnforcement` (`all` | `agents` | `off`) and `lockControl`
|
|
57
|
+
(`all` | `user`).
|
|
58
|
+
|
|
59
|
+
### Changed
|
|
60
|
+
|
|
61
|
+
- Panel claim/release no longer forces by default: `POST /apk-vm/ownership` only forces when the
|
|
62
|
+
request body sets `force: true`, and every owner change is journaled.
|
|
63
|
+
- **Bounded tool waits.** An action that has to boot the VM fails after about 120 s (explicit
|
|
64
|
+
`start`: 180 s, override with `timeoutMs`) with an actionable error instead of blocking for the
|
|
65
|
+
1200 s boot timeout; the VM keeps booting, so a later call can observe it ready, and
|
|
66
|
+
`maybeAutoStart` skips a VM that is in a crash loop.
|
|
67
|
+
|
|
68
|
+
### Fixed
|
|
69
|
+
|
|
70
|
+
- A reserved lease could be silently taken over by another session or by the admin panel without
|
|
71
|
+
an explicit takeover request.
|
|
72
|
+
- Leases lived only in memory and disappeared on plugin reload, which let dedicated VMs be
|
|
73
|
+
re-assigned after a DSH restart.
|
|
74
|
+
- An explicit `claim_vm` could leave implicit tool calls on the previously assigned VM: claiming
|
|
75
|
+
the default VM now updates the session mapping for the conversation, project and shared scopes,
|
|
76
|
+
so the next call without an `instance` argument resolves to the VM that was just claimed.
|
|
77
|
+
- The activity journal recorded the requested instance id (falling back to `default` when omitted)
|
|
78
|
+
instead of the VM that actually served the call, which hid such mismatches from the log.
|
|
79
|
+
|
|
80
|
+
- A `ReferenceError: recordOwnershipAction is not defined` broke takeovers started from
|
|
81
|
+
`apk_vm` tool calls and the `/apk-vm/ownership` HTTP route (the journal helper was defined
|
|
82
|
+
inside the route mount scope). The helper now lives at plugin scope, so takeovers are
|
|
83
|
+
recorded again.
|
|
84
|
+
- The Windows emulator can crash (status `0xC0000005`) while writing or shortly after writing a
|
|
85
|
+
quick-boot snapshot. Snapshot saves are tracked now: a `start` that arrives during a save
|
|
86
|
+
waits for it to finish, a crash that follows a save disables further quick-boot saving, and
|
|
87
|
+
the partially written snapshot is quarantined and the boot retried once as a cold boot.
|
|
88
|
+
- An incomplete quick-boot snapshot (tiny `ram.bin` or a half-written `snapshot.pb`) is now
|
|
89
|
+
quarantined before launch and the plan uses `-no-snapshot-load` for a cold boot, so a broken
|
|
90
|
+
snapshot can no longer crash the emulator in a restart loop.
|
|
91
|
+
- **Crash-loop breaker.** Three non-zero emulator exits within 15 minutes pause automatic
|
|
92
|
+
recovery/auto-start and disable snapshot saving, with the reason written to the state error
|
|
93
|
+
and logTail; inspect the emulator log/crash dump, then start the VM manually.
|
|
94
|
+
|
|
3
95
|
## 0.12.5
|
|
4
96
|
|
|
5
97
|
### Added
|
package/CHANGELOG.zh-CN.md
CHANGED
|
@@ -4,6 +4,79 @@
|
|
|
4
4
|
0.12.0 之前的历史仅保留在英文文件中。发布时请在 [docs/RELEASING.md](docs/RELEASING.md)
|
|
5
5
|
的检查清单里确认本文件已同步更新。
|
|
6
6
|
|
|
7
|
+
## 0.14.0 — 2026-11-21
|
|
8
|
+
|
|
9
|
+
### 新增
|
|
10
|
+
|
|
11
|
+
- **ARM 转译(x86_64 主机运行 arm64-v8a APK)。** 设置 `armTranslation: true` 后使用 Google APIs
|
|
12
|
+
镜像(`system-images;android-34;google_apis;x86_64`),该镜像自带 Google 的
|
|
13
|
+
`libndk_translation.so` 原生桥与 `arm64-v8a` ABI,因此仅含 arm64 原生库的 APK 可直接安装运行,
|
|
14
|
+
无需插件捆绑任何专有库。`apk_vm info` 与 `/apk-vm/state` 会报告 guest 的
|
|
15
|
+
`abilist`/`nativeBridge`/`armTranslation` 状态;若 APK 的原生库与 guest 所有 ABI 都不匹配,
|
|
16
|
+
安装会返回可操作的错误并提示该配置项。AOSP `default` 镜像仍为零配置默认。
|
|
17
|
+
|
|
18
|
+
## 0.13.0
|
|
19
|
+
|
|
20
|
+
归属管理版本:专属虚拟机在重启后依然保留,接管必须显式确认。
|
|
21
|
+
|
|
22
|
+
- **虚拟机操作锁。** `lock_vm` / `unlock_vm`(以及 `POST /apk-vm/ownership` 的 `lock`/`unlock`)
|
|
23
|
+
会把租约变成硬锁:锁定期间其他 Agent 与面板的变更请求一律返回 `409 vm-locked`,
|
|
24
|
+
`ownerForce` 与接管都无法绕过;只有锁所有者(或本地管理员解锁)可以继续操作。
|
|
25
|
+
锁会持久化到 `leases.json`,面板提供「锁定/解锁」按钮。两个配置项可调整策略:
|
|
26
|
+
`lockEnforcement`(`all` | `agents` | `off`)与 `lockControl`(`all` | `user`)。
|
|
27
|
+
### 新增
|
|
28
|
+
|
|
29
|
+
- **租约持久化与专属保留。** 租约写入 `<profile>/.apk-vm/leases.json`,并在插件下次启动时
|
|
30
|
+
恢复。专属(`conversation`/`project`)虚拟机在 DSH 重启后仍保留给原 owner,不会再被第一个
|
|
31
|
+
请求的会话拿走。专属租约带 `reservedUntil` 截止时间(`leaseReservationTtlMs`,默认 24 小时),
|
|
32
|
+
过期后可正常认领。
|
|
33
|
+
- **接管显式化并留痕。** 被他人占用的租约会在 409 响应中携带 owner 短 id 与保留截止时间;
|
|
34
|
+
面板显示保留信息、对其他 owner 保持只读,并提供「接管」按钮;非显式接管的管理员变更返回
|
|
35
|
+
`vm-takeover-required`(`x-apk-vm-takeover: 1`),不再静默操作他人虚拟机。claim/release/takeover
|
|
36
|
+
变更会记录到活动日志(含前后 owner)。
|
|
37
|
+
- **`force` 作为 `ownerForce` 的别名。** `apk_vm` 接受 `force: true`,错误文案与实际参数一致;
|
|
38
|
+
`claim_vm`/`release_vm` 在接管时会报告前一个 owner。
|
|
39
|
+
- **活动日志补充 owner 维度。** 记录 `owner`(key/label/scope/role),并经过统一脱敏,便于多会话
|
|
40
|
+
与面板同时操作时追溯「谁做了什么」。
|
|
41
|
+
- **常驻共享默认虚拟机。** 默认虚拟机永不释放、永不删除。空闲 `sharedSuspendAfterMs`(默认 5 分钟)
|
|
42
|
+
后挂起到快速启动快照(状态 `suspended`,约 6 秒恢复);再空闲 `sharedStopAfterMs`(默认 1 小时)
|
|
43
|
+
后标记为 `stopped`,快照与 AVD 均保留。工具调用、面板操作与视频客户端都会重置空闲计时,下次启动
|
|
44
|
+
按需恢复。
|
|
45
|
+
- **存储统计覆盖崩溃残留与孤儿 AVD。** `GET /apk-vm/storage` 现在报告隔离的 `*.corrupt-*`
|
|
46
|
+
快照备份、模拟器崩溃转储以及可回收总量 `reclaimableBytes`;`POST /apk-vm/storage` 新增
|
|
47
|
+
`corrupt-snapshots` 与 `crash-dumps`(均需 `confirm: true`),存储卡片显示可回收大小并可
|
|
48
|
+
一键清理。
|
|
49
|
+
- **危险操作二次确认。** `destroy_instance` 需要 `confirm: true`,面板删除按钮需点击两次,
|
|
50
|
+
避免 agent 或误点直接删除实例 AVD 与数据;实例 DELETE 路由也拒绝不带 `?confirm=1` 的请求。
|
|
51
|
+
|
|
52
|
+
### 变更
|
|
53
|
+
|
|
54
|
+
- 面板的 claim/release 不再默认强制:`POST /apk-vm/ownership` 仅在请求体带 `force: true` 时强制,
|
|
55
|
+
并且所有 owner 变更都会写入活动日志。
|
|
56
|
+
- **工具等待有上界。** 需要启动 VM 的设备操作约 120 秒后(显式 `start` 为 180 秒,可用
|
|
57
|
+
`timeoutMs` 覆盖)返回可操作错误,而不是等满 1200 秒启动超时;VM 仍在后台继续启动,稍后
|
|
58
|
+
再调用可观察到 ready;另外 `maybeAutoStart` 会跳过处于崩溃循环的 VM。
|
|
59
|
+
|
|
60
|
+
### 修复
|
|
61
|
+
|
|
62
|
+
- 保留中的租约可能被其他会话或管理面板静默抢占。
|
|
63
|
+
- 租约只存在内存中,插件重载后丢失,导致专属 VM 在重启后被重新分配。
|
|
64
|
+
- 显式 `claim_vm` 后,未指定 `instance` 的后续工具调用可能仍落在之前分配的虚拟机上:现在
|
|
65
|
+
认领会同步更新该会话在 conversation/project/shared 三种范围下的实例映射,下一次调用会
|
|
66
|
+
解析到刚刚认领的虚拟机。
|
|
67
|
+
- 活动日志记录的是「请求的实例 id」(未指定时按 `default` 记录),而不是实际执行调用的
|
|
68
|
+
虚拟机,导致这类错配在日志里看不出来;现在记录实际解析到的实例。
|
|
69
|
+
|
|
70
|
+
- 修复 `recordOwnershipAction is not defined`(`ReferenceError`)导致工具与 HTTP 接管路径
|
|
71
|
+
失败:日志助手改在插件作用域定义,`claim_vm`/`vm` 接管与归属活动记录恢复正常。
|
|
72
|
+
- Windows 模拟器在写入 quick-boot 快照时或之后可能崩溃(`0xC0000005`):现在会跟踪快照保存
|
|
73
|
+
状态——保存期间到来的 `start` 会等待完成;保存后崩溃会禁用后续快照保存、隔离损坏快照并
|
|
74
|
+
以冷启动重试一次。
|
|
75
|
+
- 不完整的 quick-boot 快照(`ram.bin` 过小或 `snapshot.pb` 写了一半)现在会在启动前被隔离,
|
|
76
|
+
启动计划改用 `-no-snapshot-load` 冷启动,损坏快照不会再导致模拟器反复崩溃重启。
|
|
77
|
+
- **崩溃循环熔断。** 15 分钟内三次非零退出会暂停自动恢复/自动启动并禁用快照保存,原因写入
|
|
78
|
+
state error 与 logTail;请检查模拟器日志/崩溃转储后手动启动。
|
|
79
|
+
|
|
7
80
|
## 0.12.5
|
|
8
81
|
|
|
9
82
|
可靠性版本:零配置首次启动的抗网络故障能力,以及多 VM 宿主机的内存管理。
|
package/README.md
CHANGED
|
@@ -468,38 +468,76 @@ instrumentation.
|
|
|
468
468
|
|
|
469
469
|
Every running VM has a renewable **owner lease**, so two DSH conversations cannot silently drive
|
|
470
470
|
the same emulator. A lease records the owner key, display label, scope (`shared`, `conversation`
|
|
471
|
-
or `project`), session id, workspace,
|
|
472
|
-
|
|
471
|
+
or `project`), session id, workspace, `since` / `lastSeenAt` timestamps and, for dedicated VMs, a
|
|
472
|
+
`reservedUntil` deadline. Leases are persisted to `<profile>/.apk-vm/leases.json` and restored on
|
|
473
|
+
the next plugin start, so a dedicated VM stays reserved across DSH restarts. Shared leases expire
|
|
474
|
+
after 30 minutes (`leaseTtlMs`); dedicated (`conversation`/`project`) leases keep a reservation for
|
|
475
|
+
24 hours (`leaseReservationTtlMs`) that is renewed by `apk_vm` calls that route to that VM.
|
|
476
|
+
|
|
477
|
+
The default VM is also **resident**: releasing its lease does not release or delete the VM. After
|
|
478
|
+
`sharedSuspendAfterMs` idle (5 minutes by default) it suspends into its quick-boot snapshot (state
|
|
479
|
+
`suspended`; the next start resumes in about 6 seconds), and after `sharedStopAfterMs` (1 hour)
|
|
480
|
+
suspended it is marked `stopped`. The AVD and snapshot are always kept, and any `apk_vm` call,
|
|
481
|
+
panel action or video client resets the idle timer and a later start resumes it on demand.
|
|
473
482
|
|
|
474
483
|
- The first conversation that needs a VM claims the default instance. A different conversation
|
|
475
484
|
gets a dedicated extra instance instead of taking the default one.
|
|
476
485
|
- `ownerScope=conversation` gives the current DSH session a VM that follows it across turns;
|
|
477
486
|
`ownerScope=project` does the same for the current workspace. `ownerScope=shared` keeps the
|
|
478
487
|
first-come default behaviour.
|
|
479
|
-
-
|
|
480
|
-
`vm-busy`
|
|
481
|
-
only after checking `owner_status`.
|
|
482
|
-
- The VM instances card shows the current owner/scope. The **VM usage** card in the
|
|
483
|
-
shows a readable owner label and provides **Claim**, **Release** and a `shared` /
|
|
484
|
-
`conversation` / `project` scope control for the human user.
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
488
|
+
- A reserved VM cannot be claimed by another owner without an explicit takeover. The response is
|
|
489
|
+
`409 vm-busy` with the owner short id and reservation deadline; pass `ownerForce=true` (alias
|
|
490
|
+
`force=true`) only after checking `owner_status`.
|
|
491
|
+
- The VM instances card shows the current owner/scope/reservation. The **VM usage** card in the
|
|
492
|
+
panel shows a readable owner label and provides **Claim**, **Release** and a `shared` /
|
|
493
|
+
`conversation` / `project` scope control for the human user. For a VM held by another owner the
|
|
494
|
+
panel keeps the controls read-only and offers **Take over**.
|
|
495
|
+
- The Web panel is an administrator, but admin mutations on a VM held by another owner are not
|
|
496
|
+
silent: they must be an explicit takeover, either by clicking **Take over** in the panel or by
|
|
497
|
+
sending `x-apk-vm-takeover: 1`. Otherwise the request fails with `409 vm-takeover-required`.
|
|
498
|
+
The panel sends `x-apk-vm-role: admin`; the Host accepts that role only from loopback requests
|
|
499
|
+
and downgrades non-local callers to `user`.
|
|
500
|
+
- `owner_status` lists default/extra VM leases; `claim_vm` and `release_vm` manage them and report
|
|
501
|
+
the previous owner when a takeover happens. HTTP: `GET|POST /apk-vm/ownership` (`status`,
|
|
502
|
+
`claim`, `release`, `touch`), while `GET /apk-vm/state` and `GET /apk-vm/instances` include owner
|
|
503
|
+
metadata.
|
|
492
504
|
- When the panel makes a mutating HTTP request it sends
|
|
493
505
|
`x-apk-vm-owner`, `x-apk-vm-scope`, `x-apk-vm-session`, `x-apk-vm-workspace` and
|
|
494
506
|
`x-apk-vm-label`. Header values may be percent-encoded (UTF-8); the Host decodes them, so
|
|
495
|
-
non-ASCII labels and workspace paths remain valid for browser `fetch`. A request that
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
the current owner when the header is missing or does not match. Read-only
|
|
499
|
-
never blocked.
|
|
507
|
+
non-ASCII labels and workspace paths remain valid for browser `fetch`. A request that supplies
|
|
508
|
+
an owner header auto-claims a free VM; on a leased VM it must match the current owner key.
|
|
509
|
+
`POST /apk-vm/*` control routes return `409 vm-busy` (or `409 vm-takeover-required` for an
|
|
510
|
+
admin takeover) with the current owner when the header is missing or does not match. Read-only
|
|
511
|
+
`GET` routes are never blocked.
|
|
500
512
|
- Closing a DSH conversation (the `session/disposed` event) automatically releases its leases,
|
|
501
|
-
with the
|
|
502
|
-
|
|
513
|
+
with the TTL as a fallback if that event is unavailable. Claim, release and takeover changes are
|
|
514
|
+
recorded in the activity journal together with the previous and incoming owner.
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
VM operation locks go further than ownership: `lock_vm` / `unlock_vm` (or `POST /apk-vm/ownership`
|
|
518
|
+
actions `lock`/`unlock`) make the current owner's lease a hard lock. While locked, every mutating
|
|
519
|
+
request from another agent or the panel is rejected with `409 vm-locked`; `ownerForce`/takeover
|
|
520
|
+
cannot break it, and only the lock owner can control the VM (a local admin can force-unlock from
|
|
521
|
+
the panel). Locks are persisted in `<profile>/.apk-vm/leases.json` and the owner card shows
|
|
522
|
+
Lock/Unlock.
|
|
523
|
+
|
|
524
|
+
The lock policy is configurable. `lockEnforcement` is `all` (default: the lock blocks every
|
|
525
|
+
other mutating client, including a panel takeover), `agents` (only other agents are blocked;
|
|
526
|
+
the local panel is the human operator and can still operate a locked VM) or `off` (locks are
|
|
527
|
+
advisory markers and never block). `lockControl` is `all` (default: an agent or the panel may
|
|
528
|
+
lock/unlock) or `user` (only the panel/user may lock or unlock; the `lock_vm`/`unlock_vm`
|
|
529
|
+
actions return an error).
|
|
530
|
+
|
|
531
|
+
### ARM translation (arm64-v8a APKs on x86_64 hosts)
|
|
532
|
+
|
|
533
|
+
Android 14 Google APIs images ship Google's `libndk_translation.so` native bridge and advertise the
|
|
534
|
+
`arm64-v8a` ABI, so APKs with only arm64 native libraries install and run on the x86_64 emulator.
|
|
535
|
+
Set `armTranslation: true` (or point `systemImage` at a Google APIs image yourself) to use
|
|
536
|
+
`system-images;android-34;google_apis;x86_64` instead of the AOSP image; the image is provisioned
|
|
537
|
+
through `sdkmanager` (about 1.3 GB, first download needs `allowSetupDownloads: true`). The guest
|
|
538
|
+
reports its ABI list and native bridge in `apk_vm info` (`abilist`, `nativeBridge`,
|
|
539
|
+
`armTranslation`) and `/apk-vm/state` (`armTranslation`). Installing an APK whose native libraries
|
|
540
|
+
match no ABI of the guest returns an actionable error that names this option.
|
|
503
541
|
## Multiple instances, physical devices and snapshots
|
|
504
542
|
|
|
505
543
|
- **Isolated extra instances.** `POST /apk-vm/instances {"name":"agent-a","start":true}` creates a
|
|
@@ -571,6 +609,8 @@ card uses the same endpoint.
|
|
|
571
609
|
{ "action": "temp" }
|
|
572
610
|
{ "action": "snapshots", "avdName": "dsh_apk", "confirm": true }
|
|
573
611
|
{ "action": "orphan-avds", "confirm": true }
|
|
612
|
+
{ "action": "corrupt-snapshots", "confirm": true }
|
|
613
|
+
{ "action": "crash-dumps", "confirm": true }
|
|
574
614
|
```
|
|
575
615
|
|
|
576
616
|
- `temp` removes only screenshots, MP4 recordings, uploaded APKs and flow JSON created by this
|
|
@@ -579,6 +619,13 @@ card uses the same endpoint.
|
|
|
579
619
|
boot is a cold boot.
|
|
580
620
|
- `orphan-avds` removes only `dsh_apk_*` AVDs that are not registered to any instance and are
|
|
581
621
|
not active.
|
|
622
|
+
- `corrupt-snapshots` deletes quarantined `*.corrupt-*` snapshot backups; `crash-dumps` deletes
|
|
623
|
+
emulator crash reports under the temp directory. `totals.reclaimableBytes` sums orphan AVDs,
|
|
624
|
+
corrupt backups, crash dumps and temp files, so it is the upper bound for one cleanup pass.
|
|
625
|
+
- Every destructive action (`snapshots`, `orphan-avds`, `corrupt-snapshots`, `crash-dumps`,
|
|
626
|
+
`destroy_instance`) requires `confirm: true`; the panel asks for a second click.
|
|
627
|
+
- An action that has to boot a VM fails after about 120 s (explicit `start`: 180 s, override
|
|
628
|
+
with `timeoutMs`) instead of blocking for the full boot timeout; the VM keeps booting.
|
|
582
629
|
- `apk_vm` tool actions: `storage`, `clean_storage` (`storageAction`, `avdName`, `confirm`).
|
|
583
630
|
|
|
584
631
|
## Network controls
|
|
@@ -755,12 +802,22 @@ config:
|
|
|
755
802
|
maxInstances: 3 # extra VMs (default VM is always available)
|
|
756
803
|
instanceIdleMs: 900000 # stop idle extra VMs after 15 min (AVD kept)
|
|
757
804
|
instanceReapIntervalMs: 60000
|
|
805
|
+
# Resident shared default VM: lease can be released, VM/AVD are never deleted.
|
|
806
|
+
# Idle -> suspend into the quick-boot snapshot; longer idle -> state "stopped"
|
|
807
|
+
# (snapshot kept). Activity resets the timer and resumes it on demand.
|
|
808
|
+
sharedResident: true
|
|
809
|
+
sharedSuspendAfterMs: 300000 # suspend the default VM after 5 min idle
|
|
810
|
+
sharedStopAfterMs: 3600000 # mark it "stopped" after 1 h suspended
|
|
758
811
|
memoryGuard: true # cap instances from host RAM; refuse low-memory starts
|
|
759
812
|
# hostReserveMb: 4096 # RAM kept for the host/other apps
|
|
760
813
|
# estimatedVmMb: 3072 # estimated cost of one local emulator
|
|
761
814
|
vmPreset: standard # standard | lite (1 GB / 2 vCPU / SwiftShader / 720p30)
|
|
762
815
|
memoryPressureReap: true # stop LRU idle VMs before creating another one
|
|
763
816
|
leaseTtlMs: 1800000 # VM owner lease lifetime; renewed by apk_vm calls
|
|
817
|
+
leaseReservationTtlMs: 86400000 # dedicated (conversation/project) lease reservation; 24h
|
|
818
|
+
lockEnforcement: all # all | agents | off (operation-lock policy)
|
|
819
|
+
lockControl: all # all | user (who may lock/unlock a VM)
|
|
820
|
+
# armTranslation: true # use the Google APIs image (libndk_translation + arm64-v8a ABIs)
|
|
764
821
|
allowRemote: false # reject non-loopback VM API clients
|
|
765
822
|
autoSetup: true # zero-config first run: auto-provision JDK 17 + SDK + image + AVD
|
|
766
823
|
setupRetries: 3 # retries per provisioning step (exponential backoff)
|
|
@@ -820,7 +877,7 @@ All keys are optional; defaults are shown in the **Default** column.
|
|
|
820
877
|
| `port` | `5558` | Emulator console port used when spawning. |
|
|
821
878
|
| `sdkRoot` | `ANDROID_HOME` / `ANDROID_SDK_ROOT` | Android SDK root for `adb`, `aapt2`, `emulator-check`, `sdkmanager`/`avdmanager`. |
|
|
822
879
|
| `adbPath` | `<sdk>/platform-tools/adb` | Explicit adb executable. |
|
|
823
|
-
| `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. |
|
|
880
|
+
| `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. Set `armTranslation: true` instead to use the Google APIs image, which ships `libndk_translation.so` and the `arm64-v8a` ABI. |
|
|
824
881
|
| `spawnEmulator` | `true` | Set `false` to only attach (never spawn). |
|
|
825
882
|
| `emulatorArgs` | `[]` | Extra argv appended to the emulator command line. |
|
|
826
883
|
| `roots` | `[]` | Extra APK discovery roots. The DSH working directory, `process.cwd()` and the home directory are added automatically. |
|
|
@@ -847,7 +904,14 @@ All keys are optional; defaults are shown in the **Default** column.
|
|
|
847
904
|
| `memoryPressureReap` | `true` | When memory is tight, stop the least-recently-used idle local VM before creating another one. Extra VMs are stopped, never destroyed. |
|
|
848
905
|
| `instanceIdleMs` | `900000` | Stop an extra instance after this long without panel frames, a video client, or an Agent command (AVD is kept). |
|
|
849
906
|
| `instanceReapIntervalMs` | `60000` | How often the idle reaper checks extra instances. |
|
|
907
|
+
| `sharedResident` | `true` | Keep the default VM resident: leases can be released, but the VM and its AVD are never released/deleted. After `sharedSuspendAfterMs` idle it suspends into its quick-boot snapshot (state `suspended`, ~6 s resume); after `sharedStopAfterMs` it is marked `stopped` (snapshot/AVD kept). Any tool/panel/stream activity resets the idle timer. |
|
|
908
|
+
| `sharedSuspendAfterMs` | `300000` | Idle time (ms) before the resident default VM suspends into its quick-boot snapshot. |
|
|
909
|
+
| `sharedStopAfterMs` | `3600000` | How long the resident default VM may stay suspended before it is marked `stopped` (snapshot is kept). |
|
|
850
910
|
| `leaseTtlMs` | `1800000` | Lifetime of a VM owner lease. Every `apk_vm` call that routes to the VM renews it; set `0` to disable expiry. |
|
|
911
|
+
| `leaseReservationTtlMs` | `86400000` | How long a `conversation`/`project` lease stays reserved for its owner across restarts. The VM cannot be claimed by another owner until it expires (explicit takeover still allowed). |
|
|
912
|
+
| `lockEnforcement` | `all` | Operation-lock policy: `all` (hard lock for every other mutating client, including a panel takeover), `agents` (only other agents are blocked; the local panel may still operate a locked VM), `off` (locks are advisory and never block). |
|
|
913
|
+
| `lockControl` | `all` | Who may lock/unlock: `all` (agents or the panel) or `user` (panel/user only; `lock_vm`/`unlock_vm` return an error). |
|
|
914
|
+
| `armTranslation` | `false` | Use the Google APIs system image (`system-images;android-34;google_apis;x86_64`), which ships Google's `libndk_translation.so` and the `arm64-v8a` ABI so arm64-only APKs install and run on the x86_64 emulator. An explicit `systemImage` wins over this flag. |
|
|
851
915
|
| `allowRemote` | `false` | Allow non-loopback clients to reach `/apk-vm/*` and `/apk-vm/ws` (only behind your own authenticated proxy). |
|
|
852
916
|
| `allowSetupDownloads` | `false` | Allow the Environment card's `install-image` action to run `sdkmanager --install` (large download). |
|
|
853
917
|
| `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. |
|
|
@@ -1000,7 +1064,7 @@ JSON bodies are bounded to 64 KiB; the raw APK upload is bounded to 500 MiB.
|
|
|
1000
1064
|
| POST | `/apk-vm/stream` | `{"fps":1–10}` — set the PNG fallback target frame rate. |
|
|
1001
1065
|
| POST | `/apk-vm/stream/quality` | `{"preset":"low\|balanced\|high"}` — change H.264 resolution/bitrate/fps; the scrcpy session reconnects. |
|
|
1002
1066
|
| GET (upgrade) | `/apk-vm/ws` | WebSocket H.264 stream (see above). |
|
|
1003
|
-
| GET/POST | `/apk-vm/ownership` | `GET` lists VM leases; `POST {"action":"claim\|release\|touch","instanceId":"default","ownerScope":"shared\|conversation\|project","sessionId"?,"workspace"?,"force"?}` manages the owner lease. |
|
|
1067
|
+
| GET/POST | `/apk-vm/ownership` | `GET` lists VM leases; `POST {"action":"claim\|release\|touch","instanceId":"default","ownerScope":"shared\|conversation\|project","sessionId"?,"workspace"?,"force"?}` manages the owner lease. `force:true` is only for an explicit takeover; an admin call on a foreign reservation must send `x-apk-vm-takeover: 1`. |
|
|
1004
1068
|
| GET | `/apk-vm/instances` | List default + extra VM instances, including `name`, `owner`, `ownerInfo` (`key`, `label`, `scope`, `sessionId`, `workspace`, `since`, `lastSeenAt`), `lastUsedAt`, `idleMs`, `idleTimeoutMs`, `videoClients`. |
|
|
1005
1069
|
| POST | `/apk-vm/instances` | `{"name":"agent-a","start":true}` — create an isolated AVD/VM; every extra instance has its own H.264 stream. `{"action":"rename","instance":"default","name":"QA phone"}` sets a display name. |
|
|
1006
1070
|
| DELETE | `/apk-vm/instances/:id` | Stop/dispose an extra instance (the default cannot be destroyed). |
|
|
@@ -1087,10 +1151,12 @@ its home screen.
|
|
|
1087
1151
|
For concurrent Agents, pass `instance` to target a specific VM; when omitted, the tool resolves
|
|
1088
1152
|
the calling Agent's lease and assigned instance (first conversation → default VM, later
|
|
1089
1153
|
conversations → isolated instances created on demand until `maxInstances`). Set
|
|
1090
|
-
`ownerScope=conversation` or `ownerScope=project` to
|
|
1091
|
-
session/workspace
|
|
1092
|
-
`
|
|
1093
|
-
|
|
1154
|
+
`ownerScope=conversation` or `ownerScope=project` to reserve a dedicated VM for the current DSH
|
|
1155
|
+
session/workspace; the reservation survives plugin restarts (24 h by default,
|
|
1156
|
+
`leaseReservationTtlMs`). `owner_status` lists leases, `claim_vm` / `release_vm` manage them, and
|
|
1157
|
+
`ownerForce=true` (alias `force=true`) is required for an explicit takeover. Each extra instance
|
|
1158
|
+
has its own H.264 WebSocket (`/apk-vm/instances/<id>/ws`) and falls back to PNG if WebCodecs is
|
|
1159
|
+
unavailable.
|
|
1094
1160
|
|
|
1095
1161
|
UI automation is live-verified against a multi-instance VM: `find_ui {"text":"Phone"}` returned
|
|
1096
1162
|
`Phone @ 102,1121`, `assert_text {"text":"Phone"}` found one node, `tap_text {"text":"Phone"}`
|