dsh-apk-vm 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.5.0
+
+Storage management.
+
+### Added
+
+- Storage panel: AVD / snapshot / SDK / plugin temp / free-disk footprint, with guarded
+  cleanup actions (two-click confirmation for destructive actions).
+- `GET /apk-vm/storage` and `POST /apk-vm/storage` (`temp`, `snapshots`, `orphan-avds`).
+- `apk_vm` actions `storage` and `clean_storage`.
+- `lib/storage.js` with dependency-free size accounting and cleanup helpers; unit coverage for
+  temp cleanup, orphan AVD detection and snapshot-aware accounting.
+
+### Notes
+
+- Snapshot cleanup only targets a stopped plugin-managed AVD; the active VM is never deleted.
+- Orphan cleanup only matches `dsh_apk_*` AVDs that are not registered to an instance.
+
+## 0.4.1
+
+Privacy cleanup for the published proof assets.
+
+### Changed
+
+- Cropped `docs/screenshot-sidebar.png` to the plugin panel only (removes the center session
+  area and workspace label; the APK paths were already redacted).
+- Removed host account names from `docs/LINUX-E2E.md`; the document now describes the KVM
+  group requirement without identifying accounts.
+
 ## 0.4.0
 
 Substantive feature release: inspection, replay, package bundles, network debugging,

package/README.md

@@ -21,9 +21,10 @@ same-origin, loopback-only debug HTTP API and an `apk_vm` Agent tool.
 > 点击、滑动、按键、文本输入送回虚拟机。支持拖拽 APK 上传、环境自检卡片、root 调试
 > API 与 `apk_vm` Agent 工具；多个 Agent 可各自使用独立的隔离虚拟机实例（多开）。
 > 参考机上冷启动约 29.5 s、快照快速启动约 8.4–10.5 s。
-> 当前 **Windows x64 为端到端已验证平台**；SDK/模拟器探测已覆盖 Windows / macOS / Linux。
+> 当前 **Windows x64 与 Linux x86_64（headless）为端到端已验证平台**；macOS 仅做探测/CI
+> 覆盖，详见 `docs/LINUX-E2E.md`。
 
-**Status:** `0.4.0` · Apache-2.0 · no npm runtime dependencies · no build step.
+**Status:** `0.5.0` · Apache-2.0 · no npm runtime dependencies · no build step.
 
 This is an open-source DSH plugin published on npm as **`dsh-apk-vm`**. Repository:
 [github.com/yuxiaole-bili/dsh-apk-vm](https://github.com/yuxiaole-bili/dsh-apk-vm).
@@ -173,6 +174,10 @@ key {"text":"HOME"}       -> returned to launcher
   (`settings put global http_proxy`) and installs a local `.pem`/`.crt` CA into the rooted
   Android user CA store with the correct OpenSSL subject-hash filename; the system CA store is
   updated when the guest allows a remount.
+- **Storage panel + guarded cleanup.** A Storage card reports the AVD, snapshot, SDK, temp-file
+  and free-disk footprint and offers explicit cleanups: plugin temp files, quick-boot
+  snapshots for a stopped AVD, and orphan `dsh_apk_*` AVDs. Destructive actions need a second
+  click and never touch the active VM.
 - **Installed-app management.** The panel's **Installed apps** card lists third-party packages
   for the active instance and offers force-stop, clear-data and uninstall; it uses the same
   rooted `debug/packages` + `debug/action` API as the Agent tool.
@@ -236,6 +241,28 @@ key {"text":"HOME"}       -> returned to launcher
 - `POST /apk-vm/debug/ca` accepts a host `.pem`/`.crt` path and installs it under the guest's
   user CA directory with the correct subject hash.
 
+## Storage management
+
+`GET /apk-vm/storage` reports the logical size of every AVD, its quick-boot snapshots, the
+Android SDK, plugin temp files and the free space on the AVD volume. The panel's **Storage**
+card uses the same endpoint.
+
+`POST /apk-vm/storage` accepts:
+
+```json
+{ "action": "temp" }
+{ "action": "snapshots", "avdName": "dsh_apk", "confirm": true }
+{ "action": "orphan-avds", "confirm": true }
+```
+
+- `temp` removes only screenshots, MP4 recordings, uploaded APKs and flow JSON created by this
+  plugin.
+- `snapshots` deletes the quick-boot snapshots of a **stopped** plugin-managed AVD; the next
+  boot is a cold boot.
+- `orphan-avds` removes only `dsh_apk_*` AVDs that are not registered to any instance and are
+  not active.
+- `apk_vm` tool actions: `storage`, `clean_storage` (`storageAction`, `avdName`, `confirm`).
+
 ## Reproducible demo
 
 A public, dependency-free demo lives in [examples](examples/README.md):
@@ -849,9 +876,12 @@ before pointing the DSH Web UI at an untrusted network.
 
 - **The plugin manages processes on your machine.** It spawns the Android emulator, `adb`,
   `sdkmanager` and `avdmanager` with `child_process.spawn(exe, argv)` — never through a shell —
-  so user-supplied strings are not shell-interpreted. Paths are validated (APK paths must exist
-  and end in `.apk`; push/pull paths are restricted to `/data/local/tmp`, `/sdcard`,
-  `/storage/emulated/0` and allowed local roots).
+  so user-supplied strings are not shell-interpreted. Paths are validated (APK/bundle paths must
+  exist and end in `.apk`/`.apks`/`.xapk`; push/pull paths are restricted to `/data/local/tmp`,
+  `/sdcard`, `/storage/emulated/0` and allowed local roots).
+- **Only emulators spawned by this plugin are stopped.** `stop()` sends `adb emu kill` only when
+  this process owns the emulator; a pre-existing/attached device (physical, remote adb or a
+  manually started emulator) is detached and left running.
 - **The guest is deliberately rooted and debuggable.** `adb root`, `ro.debuggable=1` and
   `ro.adb.secure=0` mean anything you install inside the VM is not sandboxed from root. Do not
   put real secrets or personal data in the AVD.

package/client.js

@@ -200,6 +200,21 @@ window.__ModuleLoader__.load({
       'flow.saved': 'Saved {name}',
       'flow.done': 'Replayed {name}',
       'flow.count': '{n} step(s)',
+      'storage.title': 'Storage',
+      'storage.refresh': 'Refresh',
+      'storage.cleanTemp': 'Clean temp',
+      'storage.cleanSnapshots': 'Clean snapshots',
+      'storage.cleanOrphans': 'Clean orphan AVDs',
+      'storage.confirm': 'Click again to confirm',
+      'storage.freed': 'Freed {size}',
+      'storage.avds': '{size} AVDs',
+      'storage.snapshots': 'Snapshots',
+      'storage.sdk': 'SDK',
+      'storage.temp': 'Temp',
+      'storage.free': 'Free disk',
+      'storage.active': 'active',
+      'storage.orphan': 'orphan',
+      'storage.empty': 'No AVDs found',
       'apk.bundle': 'Bundle',
       'setup.title': 'Environment',
       'setup.ok': 'Ready',
@@ -398,6 +413,21 @@ window.__ModuleLoader__.load({
       'flow.saved': '已保存 {name}',
       'flow.done': '已回放 {name}',
       'flow.count': '{n} 步',
+      'storage.title': '存储',
+      'storage.refresh': '刷新',
+      'storage.cleanTemp': '清理临时文件',
+      'storage.cleanSnapshots': '清理快照',
+      'storage.cleanOrphans': '清理孤立 AVD',
+      'storage.confirm': '再点一次确认',
+      'storage.freed': '已释放 {size}',
+      'storage.avds': '{size} 个 AVD',
+      'storage.snapshots': '快照',
+      'storage.sdk': 'SDK',
+      'storage.temp': '临时文件',
+      'storage.free': '磁盘剩余',
+      'storage.active': '运行中',
+      'storage.orphan': '孤立',
+      'storage.empty': '没有找到 AVD',
       'apk.bundle': '安装包',
       'setup.title': '环境',
       'setup.ok': '就绪',
@@ -1207,6 +1237,19 @@ window.__ModuleLoader__.load({
         var flowBusy = flowBusyState[0];
         var setFlowBusy = flowBusyState[1];
 
+        var storageState = React.useState(null);
+        var storage = storageState[0];
+        var setStorage = storageState[1];
+        var storageBusyState = React.useState('');
+        var storageBusy = storageBusyState[0];
+        var setStorageBusy = storageBusyState[1];
+        var storageErrorState = React.useState('');
+        var storageError = storageErrorState[0];
+        var setStorageError = storageErrorState[1];
+        var storageConfirmState = React.useState('');
+        var storageConfirm = storageConfirmState[0];
+        var setStorageConfirm = storageConfirmState[1];
+
         var proxyState = React.useState({ host: '', port: '' });
         var proxy = proxyState[0];
         var setProxy = proxyState[1];
@@ -1392,6 +1435,7 @@ window.__ModuleLoader__.load({
           loadInstances();
           loadDevices();
           loadFlows();
+          loadStorage();
           var pollId = setInterval(function () {
             if (stateBusyRef.current) return;
             stateBusyRef.current = true;
@@ -2173,6 +2217,67 @@ window.__ModuleLoader__.load({
           });
         }
 
+        function loadStorage() {
+          setStorageBusy('load');
+          setStorageError('');
+          return requestJson('/apk-vm/storage', null, T).then(function (result) {
+            if (!mountedRef.current) return result;
+            setStorageBusy('');
+            if (!result.ok) {
+              setStorageError(result.error || T('err.action'));
+              return result;
+            }
+            setStorage(isObject(result.data) ? result.data : null);
+            return result;
+          });
+        }
+
+        function storageSnapshotAvd() {
+          var list = storage && Array.isArray(storage.avds) ? storage.avds : [];
+          var current = snapshot && snapshot.vm && snapshot.vm.avd ? String(snapshot.vm.avd) : '';
+          var match = list.find(function (item) {
+            return item.name === current;
+          });
+          if (match) return match.name;
+          var active = list.find(function (item) {
+            return item.active && item.managed;
+          });
+          if (active) return active.name;
+          var managed = list.find(function (item) {
+            return item.managed;
+          });
+          return managed ? managed.name : 'dsh_apk';
+        }
+
+        function cleanStorage(action) {
+          if (storageBusy) return;
+          var destructive = action === 'snapshots' || action === 'orphan-avds';
+          if (destructive && storageConfirm !== action) {
+            setStorageConfirm(action);
+            pushToast('success', T('storage.confirm'));
+            return;
+          }
+          setStorageConfirm('');
+          setStorageBusy(action);
+          var payload = { action: action };
+          if (action === 'snapshots') {
+            payload.avdName = storageSnapshotAvd();
+            payload.confirm = true;
+          }
+          if (action === 'orphan-avds') payload.confirm = true;
+          requestJson('/apk-vm/storage', { method: 'POST', body: JSON.stringify(payload) }, T).then(function (result) {
+            if (!mountedRef.current) return;
+            setStorageBusy('');
+            if (!result.ok) {
+              pushToast('error', T('err.action') + ': ' + result.error);
+              return;
+            }
+            var freed = result.data && Number(result.data.freedBytes) ? Number(result.data.freedBytes) : 0;
+            pushToast('success', T('storage.freed', { size: formatBytes(freed) }));
+            loadStorage();
+          });
+        }
+
         function refreshAll() {
           loadState();
           loadApks();
@@ -3814,6 +3919,124 @@ window.__ModuleLoader__.load({
           )
         );
 
+        var storageCard = h(
+          'details',
+          { className: 'apkvm-card apkvm-debug' },
+          h(
+            'summary',
+            { className: 'apkvm-debug-summary' },
+            h('span', { className: 'apkvm-card-title' }, T('storage.title')),
+            h(
+              'span',
+              { className: 'apkvm-dim', style: { marginLeft: 'auto' } },
+              storage ? formatBytes((storage.totals && storage.totals.avdBytes) || 0) : '…'
+            ),
+            h('span', { className: 'apkvm-chevron', 'aria-hidden': 'true' }, '▸')
+          ),
+          h(
+            'div',
+            { className: 'apkvm-debug-body' },
+            !storage
+              ? h('div', { className: 'apkvm-dim' }, storageError || T('storage.empty'))
+              : h(
+                  'div',
+                  { style: { display: 'flex', flexDirection: 'column', gap: '5px', minWidth: 0 } },
+                  h(
+                    'div',
+                    { className: 'apkvm-dim', style: { display: 'flex', flexWrap: 'wrap', gap: '8px' } },
+                    h('span', null, T('storage.avds', { size: (storage.avds || []).length }) + ': ' + formatBytes((storage.totals && storage.totals.avdBytes) || 0)),
+                    h('span', null, T('storage.snapshots') + ': ' + formatBytes((storage.totals && storage.totals.snapshotBytes) || 0)),
+                    h('span', null, T('storage.sdk') + ': ' + formatBytes((storage.totals && storage.totals.sdkBytes) || 0)),
+                    h('span', null, T('storage.temp') + ': ' + formatBytes((storage.totals && storage.totals.tempBytes) || 0)),
+                    storage.disk
+                      ? h('span', null, T('storage.free') + ': ' + formatBytes(storage.disk.freeBytes))
+                      : null
+                  ),
+                  (storage.avds || []).slice(0, 4).map(function (avd) {
+                    return h(
+                      'div',
+                      {
+                        key: 'storage-' + avd.name,
+                        className: 'apkvm-apk',
+                        style: { padding: '5px 7px', gap: '3px' },
+                      },
+                      h(
+                        'div',
+                        { style: { display: 'flex', alignItems: 'center', gap: '6px', minWidth: 0 } },
+                        h('span', { className: 'apkvm-apk-name', title: avd.path }, avd.name),
+                        avd.active ? h('span', { className: 'apkvm-tag ok' }, T('storage.active')) : null,
+                        avd.orphan ? h('span', { className: 'apkvm-tag' }, T('storage.orphan')) : null
+                      ),
+                      h(
+                        'div',
+                        { className: 'apkvm-dim' },
+                        formatBytes(avd.totalBytes || 0) +
+                          ' · ' +
+                          T('storage.snapshots') +
+                          ' ' +
+                          formatBytes(avd.snapshotBytes || 0)
+                      )
+                    );
+                  }),
+                  h(
+                    'div',
+                    { style: { display: 'flex', alignItems: 'center', gap: '5px', flexWrap: 'wrap' } },
+                    actionBtn(storageBusy === 'load' ? '…' : T('storage.refresh'), {
+                      key: 'storage-refresh',
+                      small: true,
+                      disabled: Boolean(storageBusy),
+                      onClick: loadStorage,
+                    }),
+                    actionBtn(storageBusy === 'temp' ? '…' : T('storage.cleanTemp'), {
+                      key: 'storage-temp',
+                      small: true,
+                      disabled: Boolean(storageBusy),
+                      onClick: function () {
+                        cleanStorage('temp');
+                      },
+                    }),
+                    actionBtn(
+                      storageConfirm === 'snapshots'
+                        ? T('storage.confirm')
+                        : storageBusy === 'snapshots'
+                          ? '…'
+                          : T('storage.cleanSnapshots'),
+                      {
+                        key: 'storage-snapshots',
+                        small: true,
+                        disabled: Boolean(storageBusy),
+                        onClick: function () {
+                          cleanStorage('snapshots');
+                        },
+                      }
+                    ),
+                    (storage.recommendations || []).some(function (item) {
+                      return item.code === 'orphan-avds';
+                    }) || (storage.avds || []).some(function (item) {
+                      return item.orphan;
+                    })
+                      ? actionBtn(
+                          storageConfirm === 'orphan-avds'
+                            ? T('storage.confirm')
+                            : storageBusy === 'orphan-avds'
+                              ? '…'
+                              : T('storage.cleanOrphans'),
+                          {
+                            key: 'storage-orphans',
+                            small: true,
+                            disabled: Boolean(storageBusy),
+                            onClick: function () {
+                              cleanStorage('orphan-avds');
+                            },
+                          }
+                        )
+                      : null
+                  ),
+                  storageError ? h('div', { className: 'apkvm-dim' }, storageError) : null
+                )
+          )
+        );
+
         var primaryAction =
           ready || busyState
             ? actionBtn(vmBusy ? T('action.stopping') : T('action.stop'), {
@@ -4149,6 +4372,7 @@ window.__ModuleLoader__.load({
               debugCard,
               flowCard,
               networkCard,
+              storageCard,
               appsCard,
               diagCard,
               h('div', { className: 'apkvm-footnote', title: T('hint.boot') }, T('hint.short')),

package/docs/LINUX-E2E.md

@@ -18,10 +18,10 @@ CI-only check.
 | System image | `system-images;android-34;default;x86_64` |
 | AVD | `dsh_linux_test` (1080×2340, pixel_5) |
 
-The regular `OPENCODE` account is **not in the `kvm` group** and has no passwordless sudo;
-`/dev/kvm` is denied for it. The emulator portion was therefore run as the provided
-`OPENCODE_100` account (same SSH key), which is in the `kvm` group. The plugin itself never
-requires sudo or system-wide changes.
+The regular login account is **not in the `kvm` group** and has no passwordless sudo;
+`/dev/kvm` is denied for it. The emulator portion was therefore run as a second account on
+the same host (authenticated with the same SSH key), which is in the `kvm` group. The plugin
+itself never requires sudo or system-wide changes.
 
 ## Emulator launch
 
@@ -66,7 +66,7 @@ The final tree should be re-run in CI for the release tag.
   screenshots; the screenshots still succeed.
 - The emulator prints a metrics-collection warning; the launch args now include
   `-no-metrics`.
-- `OPENCODE` without `kvm` group membership gets the documented "No usable CPU hypervisor"
+- An account without `kvm` group membership gets the documented "No usable CPU hypervisor"
   error instead of a hung boot. Add the user to `kvm` (or use an account that has it) for
   hardware acceleration.
 - The platform still requires an Android SDK and AVD; only the SDK install and test harness

package/index.js

@@ -1,5 +1,5 @@
 /**
- * dsh-apk-vm — Host half.
+ * dsh-apk-vm 鈥?Host half.
  *
  * Mounts the APK Virtual Machine bridge behind the Web server:
  *   GET  /apk-vm/state    VM lifecycle snapshot (adb/emulator state, display size)
@@ -28,6 +28,7 @@ import { detectEnvironment, createAvd, installSystemImage, installSdkPackages, b
 import { acceptWebSocket } from './lib/ws.js';
 import { parseUiHierarchy, decorateUiNodes, buildInspectorPayload } from './lib/ui-inspector.js';
 import { FlowRecorder } from './lib/flows.js';
+import { collectStorage, cleanTempFiles, cleanSnapshots, cleanOrphanAvds, formatBytes } from './lib/storage.js';
 
 export const name = 'dsh-apk-vm';
 
@@ -298,7 +299,7 @@ export function apply(ctx, config = {}) {
   /* ---- H.264 video stream (scrcpy) ---------------------------------- *
    * The PNG screencap path is capped near 1-2 fps by adb. For real frame
    * rates the plugin runs the Apache-2.0 scrcpy server (vendored jar), parses
-   * its H.264 stream with lib/scrcpy.js, converts Annex-B → AVCC, and relays
+   * its H.264 stream with lib/scrcpy.js, converts Annex-B 鈫?AVCC, and relays
    * the packets over a no-dependency WebSocket (/apk-vm/ws) to the panel,
    * which decodes them with WebCodecs VideoDecoder. Input still goes through
    * the existing /apk-vm/input routes.                                    */
@@ -868,6 +869,75 @@ export function apply(ctx, config = {}) {
       });
     });
 
+    function storageSdkRoot() {
+      if (vm.sdkRoot) return vm.sdkRoot;
+      if (vm.adbPath) return path.dirname(path.dirname(vm.adbPath));
+      return process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || null;
+    }
+
+    register('/apk-vm/storage', async (req, res) => {
+      const known = () => {
+        const names = new Set();
+        if (vm.avdName) names.add(vm.avdName);
+        if (instanceManager) {
+          for (const item of instanceManager.list()) if (item.avdName) names.add(item.avdName);
+        }
+        return [...names];
+      };
+      const active = () => {
+        const names = new Set();
+        if (vm.avdName && ['ready', 'booting', 'starting'].includes(vm._state)) names.add(vm.avdName);
+        if (instanceManager) {
+          for (const item of instanceManager.list()) {
+            if (item.avdName && ['ready', 'booting', 'starting'].includes(item.state)) names.add(item.avdName);
+          }
+        }
+        return [...names];
+      };
+      if (req.method === 'GET') {
+        try {
+          sendJson(
+            res,
+            200,
+            await collectStorage({
+              sdkRoot: storageSdkRoot(),
+              avdRoot: undefined,
+              knownAvds: known(),
+              activeAvds: active(),
+            }),
+          );
+        } catch (error) {
+          sendError(res, 500, error.message);
+        }
+        return;
+      }
+      if (req.method !== 'POST') {
+        sendError(res, 405, 'GET or POST only');
+        return;
+      }
+      const body = await readJsonBody(req);
+      const action = String(body.action || '').toLowerCase();
+      try {
+        let result;
+        if (action === 'temp') {
+          result = await cleanTempFiles();
+        } else if (action === 'snapshots') {
+          if (body.confirm !== true) throw new Error('snapshot cleanup requires confirm:true');
+          const name = String(body.avdName || vm.avdName || 'dsh_apk');
+          if (active().includes(name)) throw new Error(`AVD ${name} is active; stop it before deleting snapshots`);
+          result = await cleanSnapshots({ avdName: name });
+        } else if (action === 'orphan-avds') {
+          if (body.confirm !== true) throw new Error('orphan AVD cleanup requires confirm:true');
+          result = await cleanOrphanAvds({ knownAvds: known(), activeAvds: active() });
+        } else {
+          throw new Error(`unsupported storage action: ${action || '(missing)'}`);
+        }
+        sendJson(res, 200, result);
+      } catch (error) {
+        sendError(res, 400, error.message);
+      }
+    });
+
     register('/apk-vm/state', async (req, res) => {
       if (req.method !== 'GET' && req.method !== 'HEAD') {
         sendError(res, 405, 'GET only');
@@ -2369,7 +2439,7 @@ export function apply(ctx, config = {}) {
       'The VM is usually already running (warm start); adbd runs as root once ready. ' +
       'Actions: info, shell, logcat, getprop, setprop, packages, install, push, pull, reboot, root, ' +
       'force_stop, clear_data, uninstall, rotate, ui_dump, inspect_ui, proxy, install_ca, record, perf, screenshot, tap, swipe, long_press, key, text, ' +
-      'apk_info, find_ui, assert_text, tap_text, clipboard_get, clipboard_set, devices, attach_device, detach_device, start, stop, list_instances, create_instance, destroy_instance, flow_start, flow_stop, flow_list, flow_replay. ' +
+      'apk_info, find_ui, assert_text, tap_text, clipboard_get, clipboard_set, devices, attach_device, detach_device, start, stop, list_instances, create_instance, destroy_instance, flow_start, flow_stop, flow_list, flow_replay, storage, clean_storage. ' +
       'Multi-instance: pass `instance` to target an isolated VM; omit it to use the calling Agent\'s ' +
       'assigned instance (first Agent gets the default VM, later Agents get isolated instances). ' +
       'Use shell for low-level Android commands, logcat for logs, ' +
@@ -2382,7 +2452,7 @@ export function apply(ctx, config = {}) {
       properties: {
         action: {
           type: 'string',
-          description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|inspect_ui|proxy|install_ca|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance|flow_start|flow_stop|flow_list|flow_replay',
+          description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|inspect_ui|proxy|install_ca|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance|flow_start|flow_stop|flow_list|flow_replay|storage|clean_storage',
         },
         instance: { type: 'string', description: 'Target VM instance id (default or an extra instance from list_instances). Omit for the calling Agent\'s assigned instance.' },
         instanceName: { type: 'string', description: 'create_instance: optional name for the new isolated instance.' },
@@ -2418,6 +2488,9 @@ export function apply(ctx, config = {}) {
         port: { type: 'integer', description: 'proxy: HTTP proxy port (1-65535).' },
         bypass: { type: 'string', description: 'proxy: optional no-proxy/exclusion list.' },
         flowId: { type: 'string', description: 'flow_replay: saved flow id from flow_list.' },
+        storageAction: { type: 'string', description: 'clean_storage: temp|snapshots|orphan-avds.' },
+        avdName: { type: 'string', description: 'clean_storage snapshots: target AVD (defaults to the active AVD).' },
+        confirm: { type: 'boolean', description: 'clean_storage: required true for snapshot or orphan AVD deletion.' },
       },
       required: ['action'],
     },
@@ -2544,6 +2617,65 @@ export function apply(ctx, config = {}) {
         });
         return { ok: true, summary: `replayed ${replayed.steps} step(s) from ${replayed.name}`, result: replayed };
       }
+      if (action === 'storage') {
+        const report = await collectStorage({
+          sdkRoot: storageSdkRoot(),
+          knownAvds: [
+            vm.avdName,
+            ...(instanceManager ? instanceManager.list().map((item) => item.avdName) : []),
+          ].filter(Boolean),
+          activeAvds: [
+            ...(['ready', 'booting', 'starting'].includes(vm._state) ? [vm.avdName] : []),
+            ...(instanceManager
+              ? instanceManager
+                  .list()
+                  .filter((item) => ['ready', 'booting', 'starting'].includes(item.state))
+                  .map((item) => item.avdName)
+              : []),
+          ].filter(Boolean),
+        });
+        return {
+          ok: true,
+          summary:
+            `AVD ${formatBytes(report.totals.avdBytes)}, snapshots ` +
+            `${formatBytes(report.totals.snapshotBytes)}, SDK ${formatBytes(report.totals.sdkBytes)}, ` +
+            `temp ${formatBytes(report.totals.tempBytes)}, free ${formatBytes(report.totals.freeBytes)}`,
+          result: report,
+        };
+      }
+      if (action === 'clean_storage') {
+        if (!args.storageAction) throw new Error('action=clean_storage requires storageAction');
+        const storageAction = String(args.storageAction).toLowerCase();
+        const knownAvds = [
+          vm.avdName,
+          ...(instanceManager ? instanceManager.list().map((item) => item.avdName) : []),
+        ].filter(Boolean);
+        const activeAvds = [
+          ...(['ready', 'booting', 'starting'].includes(vm._state) ? [vm.avdName] : []),
+          ...(instanceManager
+            ? instanceManager
+                .list()
+                .filter((item) => ['ready', 'booting', 'starting'].includes(item.state))
+                .map((item) => item.avdName)
+            : []),
+        ].filter(Boolean);
+        let result;
+        if (storageAction === 'temp') result = await cleanTempFiles();
+        else if (storageAction === 'snapshots') {
+          if (args.confirm !== true) throw new Error('clean_storage snapshots requires confirm=true');
+          const target = String(args.avdName || vm.avdName || 'dsh_apk');
+          if (activeAvds.includes(target)) throw new Error(`AVD ${target} is active; stop it first`);
+          result = await cleanSnapshots({ avdName: target });
+        } else if (storageAction === 'orphan-avds') {
+          if (args.confirm !== true) throw new Error('clean_storage orphan-avds requires confirm=true');
+          result = await cleanOrphanAvds({ knownAvds, activeAvds });
+        } else throw new Error(`unsupported storageAction: ${storageAction}`);
+        return {
+          ok: true,
+          summary: `${storageAction}: freed ${formatBytes(result.freedBytes)}`,
+          result,
+        };
+      }
       if (action === 'start') {
         const snapshot = await api.start();
         return { ok: true, summary: `started ${api.id}`, result: snapshot || {} };
@@ -2766,3 +2898,4 @@ export function apply(ctx, config = {}) {
     }, 'dsh-apk-vm: apk_vm tool');
   });
 }
+

package/lib/storage.js

@@ -0,0 +1,296 @@
+/**
+ * Storage accounting and housekeeping for the Android VM.
+ *
+ * All reported sizes are logical bytes (sparse files are counted by length), so
+ * the panel distinguishes apparent AVD size from actual free space. Cleanup is
+ * explicit: this module never deletes an AVD or snapshot unless the caller asks
+ * for that exact action.
+ */
+import { promises as fsp } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const MAX_FILES = 200000;
+
+async function walkSize(root, options = {}) {
+  const result = { bytes: 0, files: 0, skipped: false };
+  const stack = [String(root)];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await fsp.readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (options.stopAt && result.bytes > options.stopAt) {
+        result.skipped = true;
+        return result;
+      }
+      if (result.files >= MAX_FILES) {
+        result.skipped = true;
+        return result;
+      }
+      const full = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      try {
+        const stat = await fsp.stat(full);
+        result.bytes += stat.size;
+        result.files += 1;
+      } catch {
+        /* vanished */
+      }
+    }
+  }
+  return result;
+}
+
+async function readAvdIni(avdRoot, name) {
+  try {
+    const text = await fsp.readFile(path.join(avdRoot, `${name}.ini`), 'utf8');
+    const match = /^path=(.+)$/m.exec(text);
+    return match ? match[1].trim() : path.join(avdRoot, `${name}.avd`);
+  } catch {
+    return path.join(avdRoot, `${name}.avd`);
+  }
+}
+
+function formatBytes(bytes) {
+  const value = Number(bytes) || 0;
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let index = 0;
+  let size = value;
+  while (size >= 1024 && index < units.length - 1) {
+    size /= 1024;
+    index += 1;
+  }
+  return `${size >= 10 || index === 0 ? Math.round(size) : size.toFixed(1)} ${units[index]}`;
+}
+
+async function fileStatOrNull(file) {
+  try {
+    return await fsp.stat(file);
+  } catch {
+    return null;
+  }
+}
+
+/** Collect AVD sizes, SDK sizes, plugin temp files and free disk space. */
+export async function collectStorage(options = {}) {
+  const home = options.home || os.homedir();
+  const avdRoot = path.resolve(options.avdRoot || path.join(home, '.android', 'avd'));
+  const tempRoot = path.resolve(options.tempRoot || os.tmpdir());
+  const sdkRoot = options.sdkRoot ? path.resolve(options.sdkRoot) : null;
+  const activeAvds = new Set((options.activeAvds || []).map(String));
+  const knownAvds = new Set((options.knownAvds || []).map(String));
+
+  const avds = [];
+  let avdEntries = [];
+  try {
+    avdEntries = await fsp.readdir(avdRoot, { withFileTypes: true });
+  } catch {
+    avdEntries = [];
+  }
+  for (const entry of avdEntries) {
+    if (!entry.isDirectory() || !entry.name.endsWith('.avd')) continue;
+    const name = entry.name.slice(0, -4);
+    const avdPath = await readAvdIni(avdRoot, name);
+    const total = await walkSize(avdPath);
+    const snapshotsDir = path.join(avdPath, 'snapshots');
+    const snapshots = await walkSize(snapshotsDir);
+    avds.push({
+      name,
+      path: avdPath,
+      totalBytes: total.bytes,
+      totalFiles: total.files,
+      snapshotBytes: snapshots.bytes,
+      userdataBytes: Math.max(0, total.bytes - snapshots.bytes),
+      active: activeAvds.has(name),
+      registered: knownAvds.has(name),
+      managed: name === 'dsh_apk' || name.startsWith('dsh_apk_'),
+      orphan: name.startsWith('dsh_apk_') && !knownAvds.has(name) && !activeAvds.has(name),
+    });
+  }
+  avds.sort((a, b) => b.totalBytes - a.totalBytes);
+
+  const temp = {
+    uploadsBytes: (await walkSize(path.join(tempRoot, 'dsh-apk-vm-uploads'))).bytes,
+    flowsBytes: (await walkSize(path.join(tempRoot, 'dsh-apk-vm-flows'))).bytes,
+    screenshotsBytes: 0,
+    recordingsBytes: 0,
+    files: 0,
+  };
+  try {
+    const entries = await fsp.readdir(tempRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!/^(apk-vm-shot-|dsh-apk-vm-record-)/.test(entry.name)) continue;
+      const stat = await fileStatOrNull(path.join(tempRoot, entry.name));
+      if (!stat) continue;
+      temp.files += 1;
+      if (entry.name.startsWith('apk-vm-shot-')) temp.screenshotsBytes += stat.size;
+      else temp.recordingsBytes += stat.size;
+    }
+  } catch {
+    /* ignore */
+  }
+
+  let sdk = null;
+  if (sdkRoot) {
+    const total = await walkSize(sdkRoot);
+    const parts = {};
+    for (const part of ['system-images', 'emulator', 'build-tools', 'platform-tools', 'platforms']) {
+      parts[part] = (await walkSize(path.join(sdkRoot, part))).bytes;
+    }
+    sdk = { root: sdkRoot, totalBytes: total.bytes, totalFiles: total.files, parts };
+  }
+
+  let disk = null;
+  try {
+    const stats = await fsp.statfs(avdRoot || home);
+    disk = {
+      totalBytes: Number(stats.blocks) * Number(stats.bsize),
+      freeBytes: Number(stats.bavail) * Number(stats.bsize),
+      availableBytes: Number(stats.bavail) * Number(stats.bsize),
+      path: avdRoot || home,
+    };
+  } catch {
+    disk = null;
+  }
+  let sdkDisk = null;
+  if (sdkRoot) {
+    try {
+      const stats = await fsp.statfs(sdkRoot);
+      sdkDisk = {
+        totalBytes: Number(stats.blocks) * Number(stats.bsize),
+        freeBytes: Number(stats.bavail) * Number(stats.bsize),
+        path: sdkRoot,
+      };
+    } catch {
+      sdkDisk = null;
+    }
+  }
+
+  const snapshotTotal = avds.reduce((sum, item) => sum + item.snapshotBytes, 0);
+  const tempTotal = temp.uploadsBytes + temp.flowsBytes + temp.screenshotsBytes + temp.recordingsBytes;
+  const recommendations = [];
+  if (snapshotTotal > 1024 * 1024 * 1024) {
+    recommendations.push({
+      code: 'snapshots',
+      bytes: snapshotTotal,
+      text: `Quick-boot snapshots use ${formatBytes(snapshotTotal)}; disable quickBoot/saveSnapshotAfterBoot or delete a snapshot to free it.`,
+    });
+  }
+  if (tempTotal > 0) {
+    recommendations.push({ code: 'temp', bytes: tempTotal, text: `Plugin temp files use ${formatBytes(tempTotal)}; safe to clean.` });
+  }
+  const orphans = avds.filter((item) => item.orphan);
+  if (orphans.length) {
+    recommendations.push({
+      code: 'orphan-avds',
+      bytes: orphans.reduce((sum, item) => sum + item.totalBytes, 0),
+      text: `${orphans.length} orphan dsh_apk_* AVD(s) are not registered to a running instance.`,
+    });
+  }
+
+  return {
+    ok: true,
+    sampledAt: new Date().toISOString(),
+    home,
+    avdRoot,
+    tempRoot,
+    sdk,
+    sdkDisk,
+    avds,
+    temp,
+    disk,
+    totals: {
+      avdBytes: avds.reduce((sum, item) => sum + item.totalBytes, 0),
+      snapshotBytes: snapshotTotal,
+      sdkBytes: sdk ? sdk.totalBytes : 0,
+      tempBytes: tempTotal,
+      freeBytes: disk ? disk.freeBytes : 0,
+    },
+    recommendations,
+    formatter: 'bytes',
+  };
+}
+
+async function removeTree(target) {
+  const existed = await fsp.stat(target).catch(() => null);
+  if (!existed) return 0;
+  const measured = await walkSize(target);
+  await fsp.rm(target, { recursive: true, force: true }).catch(() => {});
+  return measured.bytes;
+}
+
+/** Delete only the plugin's own temporary artifacts. */
+export async function cleanTempFiles(options = {}) {
+  const tempRoot = path.resolve(options.tempRoot || os.tmpdir());
+  let freed = 0;
+  let files = 0;
+  for (const name of ['dsh-apk-vm-uploads', 'dsh-apk-vm-flows']) {
+    const dir = path.join(tempRoot, name);
+    const measured = await walkSize(dir);
+    await removeTree(dir);
+    freed += measured.bytes;
+    files += measured.files;
+  }
+  const entries = await fsp.readdir(tempRoot, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (!entry.isFile() || !/^(apk-vm-shot-|dsh-apk-vm-record-)/.test(entry.name)) continue;
+    const full = path.join(tempRoot, entry.name);
+    const stat = await fileStatOrNull(full);
+    if (!stat) continue;
+    await fsp.unlink(full).catch(() => {});
+    freed += stat.size;
+    files += 1;
+  }
+  return { ok: true, action: 'temp', freedBytes: freed, files };
+}
+
+/** Delete snapshots for one AVD by name. Refuses active or non-managed AVDs unless forced. */
+export async function cleanSnapshots(options = {}) {
+  const avdRoot = path.resolve(options.avdRoot || path.join(os.homedir(), '.android', 'avd'));
+  const name = String(options.avdName || '').trim();
+  if (!/^[A-Za-z0-9._-]{1,80}$/.test(name)) throw new Error('invalid AVD name');
+  if (name !== 'dsh_apk' && !name.startsWith('dsh_apk_')) {
+    throw new Error('only plugin-managed dsh_apk* AVDs can have snapshots cleaned');
+  }
+  const avdPath = await readAvdIni(avdRoot, name);
+  if (!avdPath.startsWith(avdRoot + path.sep)) throw new Error('AVD path escapes the AVD root');
+  const snapshotsDir = path.join(avdPath, 'snapshots');
+  const measured = await walkSize(snapshotsDir);
+  await removeTree(snapshotsDir);
+  return { ok: true, action: 'snapshots', avdName: name, freedBytes: measured.bytes, files: measured.files };
+}
+
+/** Delete only orphan dsh_apk_* AVDs that are not registered/active. */
+export async function cleanOrphanAvds(options = {}) {
+  const avdRoot = path.resolve(options.avdRoot || path.join(os.homedir(), '.android', 'avd'));
+  const known = new Set((options.knownAvds || []).map(String));
+  const active = new Set((options.activeAvds || []).map(String));
+  const entries = await fsp.readdir(avdRoot, { withFileTypes: true }).catch(() => []);
+  const removed = [];
+  let freed = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.endsWith('.avd')) continue;
+    const name = entry.name.slice(0, -4);
+    if (!name.startsWith('dsh_apk_') || known.has(name) || active.has(name)) continue;
+    const avdPath = path.join(avdRoot, entry.name);
+    const measured = await walkSize(avdPath);
+    await fsp.rm(avdPath, { recursive: true, force: true }).catch(() => {});
+    await fsp.unlink(path.join(avdRoot, `${name}.ini`)).catch(() => {});
+    freed += measured.bytes;
+    removed.push({ name, bytes: measured.bytes });
+  }
+  return { ok: true, action: 'orphan-avds', freedBytes: freed, removed };
+}
+
+export { formatBytes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-apk-vm",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Local AOSP Android VM for DeepSeek Harness: preview rooted APKs at up to 60 fps, automate UIAutomator flows, and give each Agent an isolated VM.",
   "license": "Apache-2.0",
@@ -25,7 +25,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "check": "node --check index.js && node --check client.js && node --check lib/android.js && node --check lib/apk-bundle.js && node --check lib/flows.js && node --check lib/ui-inspector.js && node --check lib/x509.js && node --check lib/scrcpy.js && node --check lib/ws.js && node --check lib/setup.js && node --check lib/instances.js && node --check lib/video-stream.js",
+    "check": "node --check index.js && node --check client.js && node --check lib/android.js && node --check lib/apk-bundle.js && node --check lib/flows.js && node --check lib/storage.js && node --check lib/ui-inspector.js && node --check lib/x509.js && node --check lib/scrcpy.js && node --check lib/ws.js && node --check lib/setup.js && node --check lib/instances.js && node --check lib/video-stream.js",
     "privacy": "node scripts/privacy-scan.mjs",
     "test": "node spike/ui-smoke.cjs && node spike/ui-better-sidebar-smoke.cjs && node spike/setup-smoke.mjs && node spike/android/mock-device.mjs && node spike/android/launch-plan.mjs && node spike/instances-smoke.mjs && node spike/features.mjs"
   },
@@ -44,6 +44,7 @@
     "lib/apk-bundle.js",
     "lib/flows.js",
     "lib/scrcpy.js",
+    "lib/storage.js",
     "lib/ui-inspector.js",
     "lib/ws.js",
     "lib/setup.js",