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 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
@@ -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, and `since` / `lastSeenAt` timestamps; leases expire after
472
- 30 minutes (`leaseTtlMs`) and are renewed by `apk_vm` calls that route to that VM.
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
- - If an `instance` is explicitly requested and owned by another conversation, the call fails with
480
- `vm-busy` and the owner details. `ownerForce=true` is an explicit takeover and should be used
481
- only after checking `owner_status`.
482
- - The VM instances card shows the current owner/scope. The **VM usage** card in the panel
483
- shows a readable owner label and provides **Claim**, **Release** and a `shared` /
484
- `conversation` / `project` scope control for the human user.
485
- - The Web panel is an administrator: it can operate a VM held by an Agent conversation and may
486
- force **Claim** / **Release**, while ordinary Agent calls still get `409 vm-busy`. The panel
487
- sends `x-apk-vm-role: admin`; the Host accepts that role only from loopback requests and
488
- downgrades non-local callers to `user`.
489
- - `owner_status` lists default/extra VM leases; `claim_vm` and `release_vm` manage them.
490
- HTTP: `GET|POST /apk-vm/ownership` (`status`, `claim`, `release`, `touch`), while
491
- `GET /apk-vm/state` and `GET /apk-vm/instances` include owner metadata.
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
- supplies an owner header auto-claims a free VM; on a leased VM
497
- it must match the current owner key. `POST /apk-vm/*` control routes return `409 vm-busy` with
498
- the current owner when the header is missing or does not match. Read-only `GET` routes are
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 30-minute TTL as a fallback if that event is unavailable.
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 request a dedicated VM for the current DSH
1091
- session/workspace. `owner_status` lists leases, `claim_vm` / `release_vm` manage them, and
1092
- `ownerForce=true` is required for an explicit takeover. Each extra instance has its own H.264
1093
- WebSocket (`/apk-vm/instances/<id>/ws`) and falls back to PNG if WebCodecs is unavailable.
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"}`