dsh-apk-vm 0.12.4 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/instances.js CHANGED
@@ -14,6 +14,7 @@ import net from 'node:net';
14
14
 
15
15
  import { AndroidVm } from './android.js';
16
16
  import { InstanceNameBook, sanitizeDisplayName } from './instance-names.js';
17
+ import { loadLeaseStore, saveLeaseStore } from './lease-store.js';
17
18
  import { createAvd, DEFAULT_SYSTEM_IMAGE } from './setup.js';
18
19
  import { ScrcpyStream } from './video-stream.js';
19
20
  import {
@@ -26,6 +27,16 @@ import {
26
27
  normalizeScope,
27
28
  shortKey,
28
29
  } from './vm-ownership.js';
30
+ import {
31
+ DEFAULT_ESTIMATED_VM_BYTES,
32
+ DEFAULT_HOST_RESERVE_BYTES,
33
+ VM_PRESETS,
34
+ canStartInstance,
35
+ effectiveMaxInstances,
36
+ formatMemory,
37
+ hostMemoryInfo,
38
+ resolveVmPreset,
39
+ } from './memory.js';
29
40
 
30
41
  const AVD_HOME = process.env.ANDROID_AVD_HOME
31
42
  ? String(process.env.ANDROID_AVD_HOME)
@@ -66,7 +77,12 @@ async function pickPort(preferred) {
66
77
  return preferred;
67
78
  }
68
79
 
69
- async function patchAvdConfig(avdName) {
80
+ /**
81
+ * Rewrite the per-AVD config.ini so the next boot uses the plugin's preferred
82
+ * fast-boot/display settings, plus the optional VM hardware profile (Lite
83
+ * mode). `profile === null` keeps the historical behaviour byte-for-byte.
84
+ */
85
+ export async function patchAvdConfig(avdName, profile = null) {
70
86
  const dir = path.join(AVD_HOME, `${avdName}.avd`);
71
87
  const file = path.join(dir, 'config.ini');
72
88
  await fsp.mkdir(dir, { recursive: true });
@@ -87,6 +103,19 @@ async function patchAvdConfig(avdName) {
87
103
  'hw.lcd.height': '1280',
88
104
  'hw.lcd.density': '320',
89
105
  };
106
+ // Lite profile: smaller guest RAM + fewer vCPUs. `null`/undefined fields are
107
+ // deliberately skipped so the AVD's existing (or avdmanager default) values
108
+ // stay untouched.
109
+ if (profile && typeof profile === 'object') {
110
+ const ramSizeMb = Number(profile.ramSizeMb);
111
+ if (Number.isFinite(ramSizeMb) && ramSizeMb > 0) {
112
+ desired['hw.ramSize'] = `${Math.round(ramSizeMb)}M`;
113
+ }
114
+ const cores = Number(profile.cores);
115
+ if (Number.isFinite(cores) && cores > 0) {
116
+ desired['hw.cpu.ncore'] = String(Math.round(cores));
117
+ }
118
+ }
90
119
  for (const [key, value] of Object.entries(desired)) {
91
120
  const regex = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*=.*$`, 'm');
92
121
  if (regex.test(text)) text = text.replace(regex, `${key} = ${value}`);
@@ -96,7 +125,7 @@ async function patchAvdConfig(avdName) {
96
125
  }
97
126
 
98
127
  export class ExtraVmInstance {
99
- constructor({ id, avdName, port, name, options, log }) {
128
+ constructor({ id, avdName, port, name, options = {}, log, profile = null }) {
100
129
  this.id = id;
101
130
  this.avdName = avdName;
102
131
  this.name = sanitizeDisplayName(name) || null;
@@ -105,6 +134,15 @@ export class ExtraVmInstance {
105
134
  this.frame = { buffer: null, at: 0, inFlight: null };
106
135
  this.lastApk = null;
107
136
  this.installInFlight = null;
137
+ // Hardware profile resolved by InstanceManager (Lite mode). Kept on a
138
+ // dedicated `vmProfile` field: remote instances use `profile` for their SSH
139
+ // profile, so this must never collide with that.
140
+ const requestedProfile = profile && typeof profile === 'object'
141
+ ? profile
142
+ : options && typeof options.profile === 'object'
143
+ ? options.profile
144
+ : null;
145
+ this.vmProfile = requestedProfile || { name: 'standard', ...VM_PRESETS.standard };
108
146
  this.vm = new AndroidVm({
109
147
  ...options,
110
148
  avdName,
@@ -113,6 +151,8 @@ export class ExtraVmInstance {
113
151
  // AndroidVm would attach to whichever adb device happens to be online
114
152
  // (normally the first/default VM).
115
153
  serial: `emulator-${port}`,
154
+ // Lite mode pins a software GPU (standard keeps the plugin option).
155
+ gpuMode: this.vmProfile.gpuMode || options.gpuMode,
116
156
  // Media (virtual camera/mic) flags resolved by the plugin at create time;
117
157
  // they are stored by AndroidVm and used on every emulator (re)spawn.
118
158
  extraEmulatorArgs: options.extraEmulatorArgs,
@@ -123,9 +163,9 @@ export class ExtraVmInstance {
123
163
  ? new ScrcpyStream({
124
164
  vm: this.vm,
125
165
  jarPath: options.scrcpyJarPath,
126
- maxSize: options.scrcpyMaxSize || 960,
166
+ maxSize: this.vmProfile.scrcpyMaxSize || options.scrcpyMaxSize || 960,
127
167
  bitrate: options.scrcpyBitrate || 6_000_000,
128
- maxFps: options.scrcpyMaxFps || 60,
168
+ maxFps: this.vmProfile.scrcpyMaxFps || options.scrcpyMaxFps || 60,
129
169
  preferredPort: 27183 + port,
130
170
  log: (line) => this._log(line),
131
171
  })
@@ -142,6 +182,18 @@ export class ExtraVmInstance {
142
182
  if (this.logSink) this.logSink(`[${this.id}] ${line}`);
143
183
  }
144
184
 
185
+ /** Hardware profile fields shown by status()/list() (null = AVD default). */
186
+ _profileFields() {
187
+ const profile = this.vmProfile || {};
188
+ const ramSizeMb = Number(profile.ramSizeMb);
189
+ const cores = Number(profile.cores);
190
+ return {
191
+ ramSizeMb: Number.isFinite(ramSizeMb) && ramSizeMb > 0 ? Math.round(ramSizeMb) : null,
192
+ cores: Number.isFinite(cores) && cores > 0 ? Math.round(cores) : null,
193
+ profileName: typeof profile.name === 'string' && profile.name ? profile.name : null,
194
+ };
195
+ }
196
+
145
197
  async status() {
146
198
  const status = await this.vm.status();
147
199
  return {
@@ -154,6 +206,7 @@ export class ExtraVmInstance {
154
206
  debugPrepared: status.debugPrepared === true,
155
207
  debugToolkit: status.debugToolkit || null,
156
208
  identity: status.identity || null,
209
+ ...this._profileFields(),
157
210
  };
158
211
  }
159
212
 
@@ -379,10 +432,56 @@ export class ExtraVmInstance {
379
432
  }
380
433
  }
381
434
 
435
+ function positiveByteOption(bytesOption, mbOption, fallback) {
436
+ const bytes = Number(bytesOption);
437
+ if (Number.isFinite(bytes) && bytes > 0) return Math.floor(bytes);
438
+ const mb = Number(mbOption);
439
+ if (Number.isFinite(mb) && mb > 0) return Math.floor(mb * 1024 * 1024);
440
+ return fallback;
441
+ }
442
+
443
+ /**
444
+ * Pick the least recently used *idle* local instance that memory-pressure
445
+ * reaping may stop. Pure helper (accepts a Map or an array) so it can be
446
+ * unit-tested without a real manager/emulator.
447
+ *
448
+ * Excluded: remote instances (their SSH session manager owns them), VMs with
449
+ * video clients, installs in flight, an owner/lease, or an in-flight frame.
450
+ */
451
+ export function pickMemoryPressureVictim(instances) {
452
+ const list = instances instanceof Map
453
+ ? [...instances.values()]
454
+ : Array.isArray(instances)
455
+ ? instances
456
+ : [];
457
+ let victim = null;
458
+ let victimLastUsedAt = Infinity;
459
+ for (const instance of list) {
460
+ if (!instance || typeof instance !== 'object') continue;
461
+ if ((instance.kind || 'extra') === 'remote') continue;
462
+ const state = instance.vm ? instance.vm._state : instance._state;
463
+ if (state !== 'ready' && state !== 'booting' && state !== 'running') continue;
464
+ if (instance.stream && instance.stream.clients && instance.stream.clients.size > 0) continue;
465
+ if (instance.installInFlight) continue;
466
+ if (instance.owner) continue;
467
+ if (instance.frame && instance.frame.inFlight) continue;
468
+ const lastUsedAt = Number(instance.lastUsedAt);
469
+ if (!Number.isFinite(lastUsedAt)) continue;
470
+ if (lastUsedAt < victimLastUsedAt) {
471
+ victim = instance;
472
+ victimLastUsedAt = lastUsedAt;
473
+ }
474
+ }
475
+ return victim;
476
+ }
477
+
382
478
  export class InstanceManager {
383
479
  constructor(options = {}) {
384
480
  this.options = options;
385
481
  this.namesFile = options.namesFile ? String(options.namesFile) : null;
482
+ // Dedicated VMs must survive DSH/plugin restarts: leases are persisted to
483
+ // <profile>/.apk-vm/leases.json (index.js passes the shared data root).
484
+ this.leasesFile = options.leasesFile ? String(options.leasesFile) : null;
386
485
  this.names = new InstanceNameBook({ file: this.namesFile });
387
486
  this.sdkRoot = options.sdkRoot || null;
388
487
  this.emulatorPath = options.emulatorPath || null;
@@ -397,6 +496,19 @@ export class InstanceManager {
397
496
  this.scrcpyBitrate = options.scrcpyBitrate || 6_000_000;
398
497
  this.scrcpyMaxFps = options.scrcpyMaxFps || 60;
399
498
  this.idleTimeoutMs = Math.max(60_000, Number(options.idleTimeoutMs) || 15 * 60 * 1000);
499
+ // Resident shared default VM: never deleted/released. After
500
+ // `sharedSuspendAfterMs` idle it suspends into a quick-boot snapshot
501
+ // (emulator exits, state `suspended`), after `sharedStopAfterMs` it is
502
+ // marked `stopped` (snapshot + AVD kept). Any tool/panel/stream activity
503
+ // resets the idle timer and a later start resumes on demand.
504
+ this.defaultVm = options.defaultVm || null;
505
+ this.sharedResident = options.sharedResident !== false;
506
+ this.sharedSuspendAfterMs = Math.max(60_000, Number(options.sharedSuspendAfterMs) || 5 * 60 * 1000);
507
+ this.sharedStopAfterMs = Math.max(
508
+ this.sharedSuspendAfterMs,
509
+ Number(options.sharedStopAfterMs) || 60 * 60 * 1000,
510
+ );
511
+ this._sharedLastActivityAt = Date.now();
400
512
  this.dnsServers = Array.isArray(options.dnsServers) ? options.dnsServers.map(String) : [];
401
513
  this.networkMode = options.networkMode === 'shared' ? 'shared' : 'isolated';
402
514
  this.tcpdumpPath = options.tcpdumpPath ? String(options.tcpdumpPath) : null;
@@ -405,13 +517,37 @@ export class InstanceManager {
405
517
  this.mediaOptionsProvider = typeof options.mediaOptionsProvider === 'function' ? options.mediaOptionsProvider : null;
406
518
  this.mediaOptions = null;
407
519
  this.logSink = typeof options.log === 'function' ? options.log : null;
520
+ // Host memory guard / Lite mode. Every memory helper is injectable so the
521
+ // spike tests can exercise the guard against synthetic host memory without
522
+ // depending on the machine they run on.
523
+ const memoryProvider = options.memoryProvider && typeof options.memoryProvider === 'object'
524
+ ? options.memoryProvider
525
+ : {};
526
+ this.memoryProvider = {
527
+ hostMemoryInfo: typeof memoryProvider.hostMemoryInfo === 'function' ? memoryProvider.hostMemoryInfo : hostMemoryInfo,
528
+ effectiveMaxInstances: typeof memoryProvider.effectiveMaxInstances === 'function'
529
+ ? memoryProvider.effectiveMaxInstances
530
+ : effectiveMaxInstances,
531
+ canStartInstance: typeof memoryProvider.canStartInstance === 'function' ? memoryProvider.canStartInstance : canStartInstance,
532
+ formatMemory: typeof memoryProvider.formatMemory === 'function' ? memoryProvider.formatMemory : formatMemory,
533
+ };
534
+ this.vmProfile = this._resolveVmProfile(options.vmPreset);
535
+ this.memoryGuard = options.memoryGuard !== false;
536
+ this.memoryPressureReap = options.memoryPressureReap !== false;
537
+ this.hostReserveBytes = positiveByteOption(options.hostReserveBytes, options.hostReserveMb, DEFAULT_HOST_RESERVE_BYTES);
538
+ this.estimatedVmBytes = positiveByteOption(options.estimatedVmBytes, options.estimatedVmMb, DEFAULT_ESTIMATED_VM_BYTES);
408
539
  this.instances = new Map();
409
540
  this.agentInstances = new Map();
410
541
  this.defaultClaimed = false;
411
542
  this.defaultOwner = null;
412
543
  this.leaseBook = new VmLeaseBook({
413
544
  ttlMs: Number(options.leaseTtlMs) > 0 ? Number(options.leaseTtlMs) : DEFAULT_LEASE_TTL_MS,
545
+ ...(Number(options.leaseReservationTtlMs) > 0
546
+ ? { reservationTtlMs: Number(options.leaseReservationTtlMs) }
547
+ : {}),
548
+ onChange: (reason, detail) => this._persistLeases(reason, detail),
414
549
  });
550
+ this._restoreLeases();
415
551
  this.onCreated = null;
416
552
  this._lock = Promise.resolve();
417
553
  }
@@ -420,9 +556,159 @@ export class InstanceManager {
420
556
  if (this.logSink) this.logSink(line);
421
557
  }
422
558
 
559
+ /**
560
+ * Persist the lease book after every claim/release/touch/clear. Best effort:
561
+ * a read-only profile must not break VM control, so failures only log.
562
+ */
563
+ _persistLeases(reason) {
564
+ if (!this.leasesFile) return false;
565
+ try {
566
+ const saved = saveLeaseStore(this.leasesFile, this.leaseBook.snapshot());
567
+ if (!saved) this._log(`[instances] could not persist leases (${reason || 'change'}) to ${this.leasesFile}`);
568
+ return saved;
569
+ } catch (error) {
570
+ this._log(`[instances] failed to persist leases (${reason || 'change'}): ${error && error.message ? error.message : error}`);
571
+ return false;
572
+ }
573
+ }
574
+
575
+ /** Restore persisted leases (fresh DSH process / plugin reload). */
576
+ _restoreLeases() {
577
+ if (!this.leasesFile) return 0;
578
+ const entries = loadLeaseStore(this.leasesFile);
579
+ if (entries.length === 0) return 0;
580
+ const restored = this.leaseBook.restore(entries);
581
+ const defaultLease = this.leaseBook.get('default');
582
+ if (defaultLease) {
583
+ this.defaultClaimed = true;
584
+ this.defaultOwner = defaultLease.key;
585
+ }
586
+ if (restored > 0) this._log(`[instances] restored ${restored} lease(s) from ${this.leasesFile}`);
587
+ return restored;
588
+ }
589
+
590
+ /**
591
+ * Whether the AVD for an extra instance still exists on disk. A persisted
592
+ * lease for a deleted AVD is stale and must not recreate the instance
593
+ * (see forOwner): cleanup of an orphan AVD must stay cleaned up.
594
+ */
595
+ _extraAvdExists(instanceId) {
596
+ const avdName = `${this.baseAvdName}_${instanceId}`
597
+ .replace(/[^A-Za-z0-9._-]+/g, '_')
598
+ .slice(0, 60);
599
+ return existsSync(path.join(AVD_HOME, `${avdName}.ini`));
600
+ }
601
+
602
+ /**
603
+ * Resolve the VM hardware profile at construction time. An invalid
604
+ * config value must never take the whole plugin down: fall back to
605
+ * `standard` and record a warning in the log instead of throwing.
606
+ */
607
+ _resolveVmProfile(value) {
608
+ try {
609
+ return resolveVmPreset(value === undefined || value === null || value === '' ? 'standard' : value);
610
+ } catch (error) {
611
+ this._log(`[instances] invalid vmPreset (${error && error.message ? error.message : error}); falling back to "standard"`);
612
+ return resolveVmPreset('standard');
613
+ }
614
+ }
615
+
616
+ /** Local (non-remote) instances only: remotes never count against host memory. */
617
+ _localInstances() {
618
+ return [...this.instances.values()].filter((instance) => (instance.kind || 'extra') !== 'remote');
619
+ }
620
+
621
+ /**
622
+ * Host memory + effective instance cap + resolved profile. Shown by the panel
623
+ * state route and the emulator inventory; `ok:false` means the host memory
624
+ * could not be read (the rest of the shape is still populated).
625
+ */
626
+ memory() {
627
+ const hostInfo = this.memoryProvider.hostMemoryInfo();
628
+ const hostKnown = Boolean(hostInfo && hostInfo.ok === true);
629
+ const localInstances = this._localInstances();
630
+ const effective = this.memoryProvider.effectiveMaxInstances({
631
+ requested: this.maxInstances,
632
+ hostMemory: hostInfo,
633
+ reservedBytes: this.hostReserveBytes,
634
+ estimatedVmBytes: this.estimatedVmBytes,
635
+ });
636
+ const requestedMaxInstances = this.maxInstances;
637
+ const effectiveMax = effective && Number.isFinite(Number(effective.maxInstances))
638
+ ? Number(effective.maxInstances)
639
+ : requestedMaxInstances;
640
+ const profile = this.vmProfile || { name: 'standard', ...VM_PRESETS.standard };
641
+ const result = {
642
+ ok: hostKnown,
643
+ host: hostKnown
644
+ ? {
645
+ totalBytes: hostInfo.totalBytes,
646
+ totalMb: hostInfo.totalMb,
647
+ freeBytes: hostInfo.freeBytes,
648
+ freeMb: hostInfo.freeMb,
649
+ }
650
+ : null,
651
+ profile: {
652
+ name: profile.name || 'standard',
653
+ ramSizeMb: profile.ramSizeMb ?? null,
654
+ cores: profile.cores ?? null,
655
+ gpuMode: profile.gpuMode ?? null,
656
+ frameFps: profile.frameFps ?? null,
657
+ scrcpyMaxSize: profile.scrcpyMaxSize ?? null,
658
+ scrcpyMaxFps: profile.scrcpyMaxFps ?? null,
659
+ },
660
+ requestedMaxInstances,
661
+ effectiveMaxInstances: effectiveMax,
662
+ limited: Boolean(effective && effective.limited),
663
+ runningInstances: localInstances.length,
664
+ guard: this.memoryGuard,
665
+ pressureReap: this.memoryPressureReap,
666
+ };
667
+ if (!hostKnown) {
668
+ result.error = (hostInfo && hostInfo.error) || 'host memory unknown';
669
+ } else if (effective && effective.reason) {
670
+ result.reason = effective.reason;
671
+ }
672
+ return result;
673
+ }
674
+
675
+ /** Server-side memory guard for create(): returns an Error message or null. */
676
+ _memoryGuardError(memoryOverride) {
677
+ if (!this.memoryGuard || memoryOverride === true) return null;
678
+ const hostInfo = this.memoryProvider.hostMemoryInfo();
679
+ if (!hostInfo || hostInfo.ok !== true) return null;
680
+ const localCount = this._localInstances().length;
681
+ const effective = this.memoryProvider.effectiveMaxInstances({
682
+ requested: this.maxInstances,
683
+ hostMemory: hostInfo,
684
+ reservedBytes: this.hostReserveBytes,
685
+ estimatedVmBytes: this.estimatedVmBytes,
686
+ });
687
+ const effectiveMax = effective && Number(effective.maxInstances);
688
+ if (Number.isFinite(effectiveMax) && localCount >= effectiveMax) {
689
+ const budget = effective.reason
690
+ || `host total ${this.memoryProvider.formatMemory(hostInfo.totalBytes)}, reserved ${this.memoryProvider.formatMemory(this.hostReserveBytes)}, ${this.memoryProvider.formatMemory(this.estimatedVmBytes)} per VM`;
691
+ return `host memory guard: ${localCount} local instance(s) already exist and host memory allows at most ${effectiveMax} (${budget}); close idle instances, adjust hostReserveMb/estimatedVmMb, set memoryGuard:false, or pass memoryOverride:true to bypass this check`;
692
+ }
693
+ const canStart = this.memoryProvider.canStartInstance({
694
+ hostMemory: hostInfo,
695
+ runningCount: localCount,
696
+ reservedBytes: this.hostReserveBytes,
697
+ estimatedVmBytes: this.estimatedVmBytes,
698
+ });
699
+ if (canStart && canStart.ok === false) {
700
+ const budget = `host total ${this.memoryProvider.formatMemory(hostInfo.totalBytes)}, reserved ${this.memoryProvider.formatMemory(this.hostReserveBytes)}, ${this.memoryProvider.formatMemory(this.estimatedVmBytes)} per VM`;
701
+ return `host memory guard: not enough free host memory to start another VM (${canStart.reason || budget}); close idle instances, adjust hostReserveMb/estimatedVmMb, set memoryGuard:false, or pass memoryOverride:true to bypass this check`;
702
+ }
703
+ return null;
704
+ }
705
+
423
706
  list() {
424
707
  return [...this.instances.values()].map((instance) => {
425
708
  const lease = this.leaseBook.get(instance.id);
709
+ const profile = typeof instance._profileFields === 'function'
710
+ ? instance._profileFields()
711
+ : { ramSizeMb: null, cores: null, profileName: null };
426
712
  return {
427
713
  id: instance.id,
428
714
  avdName: instance.avdName,
@@ -441,6 +727,7 @@ export class InstanceManager {
441
727
  idleMs: Math.max(0, Date.now() - instance.lastUsedAt),
442
728
  idleTimeoutMs: this.idleTimeoutMs,
443
729
  videoClients: instance.stream ? instance.stream.clients.size : 0,
730
+ ...profile,
444
731
  };
445
732
  });
446
733
  }
@@ -528,6 +815,16 @@ export class InstanceManager {
528
815
  }
529
816
  }
530
817
  }
818
+ // Keep the agent mapping in sync with the lease: an explicit claim (tool,
819
+ // HTTP or panel) must redirect later implicit tool calls to the claimed VM,
820
+ // both for the owner key itself and for the other scope of the same
821
+ // session (a conversation/project claim is also that session's VM).
822
+ const mappedId = instanceId === 'default' ? 'default' : instanceId;
823
+ this.agentInstances.set(normalized.key, mappedId);
824
+ if (normalized.sessionId) {
825
+ this.agentInstances.set(`session:${normalized.sessionId}`, mappedId);
826
+ this.agentInstances.set(`shared:${normalized.sessionId}`, mappedId);
827
+ }
531
828
  return result;
532
829
  }
533
830
 
@@ -541,12 +838,13 @@ export class InstanceManager {
541
838
  this.defaultOwner = null;
542
839
  }
543
840
  } else {
544
- for (const [agent, mapped] of this.agentInstances) {
545
- if (mapped === instanceId) this.agentInstances.delete(agent);
546
- }
547
841
  const instance = this.instances.get(instanceId);
548
842
  if (instance) instance.owner = null;
549
843
  }
844
+ // A released lease must not keep routing implicit tool calls to the VM.
845
+ for (const [agent, mapped] of this.agentInstances) {
846
+ if (mapped === instanceId) this.agentInstances.delete(agent);
847
+ }
550
848
  return released;
551
849
  }
552
850
 
@@ -583,6 +881,28 @@ export class InstanceManager {
583
881
  if (instance) instance.touch();
584
882
  }
585
883
 
884
+ /**
885
+ * Lock a leased VM. While locked, every mutating request from another owner
886
+ * or agent is rejected with 409 `vm-locked` (even admin takeover).
887
+ */
888
+ lockOwner(id, ownerOrKey = null, { force = false } = {}) {
889
+ const instanceId = String(id || 'default');
890
+ const key = ownerOrKey && typeof ownerOrKey === 'object' ? ownerOrKey.key : ownerOrKey;
891
+ const locked = this.leaseBook.lock(instanceId, key || null, { force });
892
+ if (instanceId !== 'default') {
893
+ const instance = this.instances.get(instanceId);
894
+ if (instance) instance.touch();
895
+ }
896
+ return locked;
897
+ }
898
+
899
+ /** Remove a lock. `force` is reserved for the local admin/panel unlock path. */
900
+ unlockOwner(id, ownerOrKey = null, { force = false } = {}) {
901
+ const instanceId = String(id || 'default');
902
+ const key = ownerOrKey && typeof ownerOrKey === 'object' ? ownerOrKey.key : ownerOrKey;
903
+ return this.leaseBook.unlock(instanceId, key || null, { force });
904
+ }
905
+
586
906
  _mappedInstance(key) {
587
907
  const mapped = this.agentInstances.get(key);
588
908
  if (!mapped) return null;
@@ -608,16 +928,71 @@ export class InstanceManager {
608
928
  if (existing) {
609
929
  const id = existing.default ? 'default' : existing.id;
610
930
  const current = this.leaseBook.get(id);
611
- if (current && current.key !== key) {
931
+ // The same session may hold the lease under its other scope key
932
+ // (conversation/project vs shared). That is not a stale mapping.
933
+ const sameSession = Boolean(
934
+ current &&
935
+ normalized.sessionId &&
936
+ (current.sessionId === normalized.sessionId ||
937
+ current.key === `session:${normalized.sessionId}` ||
938
+ current.key === `shared:${normalized.sessionId}`)
939
+ );
940
+ if (current && current.key !== key && !sameSession) {
612
941
  // The mapping is stale (e.g. lease was force-released). Release it and
613
942
  // fall through to normal scheduling instead of silently reusing it.
614
943
  this.agentInstances.delete(key);
615
944
  } else {
616
- this.claimOwner(id, normalized, { force: false });
945
+ if (current && current.key !== key) {
946
+ // Keep the live lease under its original key; just refresh it.
947
+ this.leaseBook.touch(id, current.key);
948
+ } else {
949
+ this.claimOwner(id, normalized, { force: false });
950
+ }
617
951
  return existing;
618
952
  }
619
953
  }
620
954
 
955
+ // A dedicated (conversation/project) VM must survive restarts: if the
956
+ // persisted lease book still names this owner, reuse the reserved VM
957
+ // instead of handing it to the first session that asks.
958
+ const persisted = this.leaseBook.list().find((entry) => entry.key === key);
959
+ if (persisted) {
960
+ try {
961
+ if (persisted.id === 'default') {
962
+ this.defaultClaimed = true;
963
+ this.defaultOwner = key;
964
+ this.agentInstances.set(key, 'default');
965
+ return { id: 'default', default: true };
966
+ }
967
+ const local = this.instances.get(persisted.id);
968
+ if (local) {
969
+ this.agentInstances.set(key, local.id);
970
+ this.claimOwner(local.id, normalized, { force: true });
971
+ return local;
972
+ }
973
+ // Never resurrect an extra AVD that was deleted (for example by
974
+ // clean_storage --action orphan-avds) just because an old lease was
975
+ // persisted: the reservation is stale, so release it and let normal
976
+ // scheduling decide. Recreating the AVD here would silently consume
977
+ // gigabytes and break the user's cleanup.
978
+ if (!this._extraAvdExists(persisted.id)) {
979
+ throw new Error(`its AVD for ${persisted.id} no longer exists`);
980
+ }
981
+ const adopted = await this.create({ name: persisted.id });
982
+ this.agentInstances.set(key, adopted.id);
983
+ this.claimOwner(adopted.id, normalized, { force: true });
984
+ return adopted;
985
+ } catch (error) {
986
+ this.agentInstances.delete(key);
987
+ try {
988
+ this.releaseOwner(persisted.id, key, { force: true });
989
+ } catch {
990
+ /* a stale reservation must not block scheduling */
991
+ }
992
+ this._log(`[instances] could not restore persisted lease for ${key}: ${error && error.message ? error.message : error}`);
993
+ }
994
+ }
995
+
621
996
  // The first owner (any scope) may claim an unleased default VM; the lease
622
997
  // makes it exclusive, so another session/project gets an isolated extra VM.
623
998
  // Only the live lease matters: an expired lease must not keep the default
@@ -664,8 +1039,13 @@ export class InstanceManager {
664
1039
  }
665
1040
 
666
1041
 
667
- async create({ name } = {}) {
1042
+ async create({ name, memoryOverride = false } = {}) {
668
1043
  const run = async () => {
1044
+ // Host memory guard first: a hard cap from actual host RAM, then the
1045
+ // current free-memory check. memoryOverride:true is the explicit escape
1046
+ // hatch (e.g. the user knows another VM just exited).
1047
+ const guardError = this._memoryGuardError(memoryOverride);
1048
+ if (guardError) throw new Error(guardError);
669
1049
  if (this.instances.size >= this.maxInstances) {
670
1050
  throw new Error(`max instances reached (${this.maxInstances}); destroy an instance or raise maxInstances`);
671
1051
  }
@@ -687,7 +1067,7 @@ export class InstanceManager {
687
1067
  if (!created.ok) throw new Error(created.error || `failed to create AVD ${avdName}`);
688
1068
  avdPresent = true;
689
1069
  }
690
- await patchAvdConfig(avdName);
1070
+ await patchAvdConfig(avdName, this.vmProfile);
691
1071
  // Resolve the media (virtual camera/mic) flags at create time so the new
692
1072
  // AndroidVm can append them on every emulator spawn. A broken provider
693
1073
  // must never block VM creation.
@@ -706,6 +1086,7 @@ export class InstanceManager {
706
1086
  avdName,
707
1087
  port,
708
1088
  name: displayName,
1089
+ profile: this.vmProfile,
709
1090
  options: {
710
1091
  sdkRoot: this.sdkRoot || undefined,
711
1092
  adbPath: this.adbPath || undefined,
@@ -843,6 +1224,58 @@ export class InstanceManager {
843
1224
  if (instance) instance.touch();
844
1225
  }
845
1226
 
1227
+ /** Record shared default VM activity (tool/panel/stream) and reset its idle timer. */
1228
+ noteSharedActivity(now = Date.now()) {
1229
+ this._sharedLastActivityAt = now;
1230
+ }
1231
+
1232
+ /** Snapshot of the resident shared VM policy (used by GET /apk-vm/state). */
1233
+ sharedStatus(now = Date.now()) {
1234
+ const vm = this.defaultVm;
1235
+ if (!vm) return null;
1236
+ const idleMs = Math.max(0, now - this._sharedLastActivityAt);
1237
+ const state = vm._state;
1238
+ const nextAction =
1239
+ this.sharedResident && state === 'ready' && idleMs >= this.sharedSuspendAfterMs
1240
+ ? 'suspend'
1241
+ : this.sharedResident && state === 'suspended' && idleMs >= this.sharedStopAfterMs
1242
+ ? 'stop'
1243
+ : null;
1244
+ return {
1245
+ resident: this.sharedResident,
1246
+ state,
1247
+ idleMs,
1248
+ suspendAfterMs: this.sharedSuspendAfterMs,
1249
+ stopAfterMs: this.sharedStopAfterMs,
1250
+ nextAction,
1251
+ };
1252
+ }
1253
+
1254
+ /**
1255
+ * Apply the resident shared VM policy: suspend a ready default VM after
1256
+ * `sharedSuspendAfterMs` idle, fully stop a suspended one after
1257
+ * `sharedStopAfterMs`. Never deletes the AVD or the quick-boot snapshot.
1258
+ */
1259
+ async reconcileShared(now = Date.now()) {
1260
+ if (!this.sharedResident || !this.defaultVm) return null;
1261
+ const vm = this.defaultVm;
1262
+ const idleMs = now - this._sharedLastActivityAt;
1263
+ if (vm._state === 'ready' && idleMs >= this.sharedSuspendAfterMs) {
1264
+ this._log(`[instances] suspending resident shared VM after ${Math.round(idleMs / 1000)}s idle`);
1265
+ const suspended = await vm.suspend('shared-idle').catch(() => false);
1266
+ if (!suspended) return { action: 'suspend-failed' };
1267
+ this.noteSharedActivity(now);
1268
+ return { action: 'suspend' };
1269
+ }
1270
+ if (vm._state === 'suspended' && idleMs >= this.sharedStopAfterMs) {
1271
+ if (vm.markSuspendedStopped()) {
1272
+ this._log(`[instances] resident shared VM idle-stopped after ${Math.round(idleMs / 1000)}s suspended`);
1273
+ return { action: 'stop' };
1274
+ }
1275
+ }
1276
+ return null;
1277
+ }
1278
+
846
1279
  /** Stop extra VMs whose Agent/panel has not touched them for idleTimeoutMs. */
847
1280
  async reapIdle(now = Date.now()) {
848
1281
  const stopped = [];
@@ -865,6 +1298,46 @@ export class InstanceManager {
865
1298
  this._log(`[instances] idle stop failed for ${instance.id}: ${error && error.message ? error.message : error}`);
866
1299
  }
867
1300
  }
1301
+ // Memory-pressure reaping: when the idle-timeout loop above found nothing,
1302
+ // but the host cannot fit another VM (free < reserved + estimate), stop at
1303
+ // most one idle local VM per tick — the least recently used one — so the
1304
+ // next create()/boot has room. Remote sessions are never touched here.
1305
+ if (this.memoryPressureReap) {
1306
+ try {
1307
+ const hostInfo = this.memoryProvider.hostMemoryInfo();
1308
+ if (hostInfo && hostInfo.ok === true) {
1309
+ const local = this._localInstances();
1310
+ const check = this.memoryProvider.canStartInstance({
1311
+ hostMemory: hostInfo,
1312
+ runningCount: local.length,
1313
+ reservedBytes: this.hostReserveBytes,
1314
+ estimatedVmBytes: this.estimatedVmBytes,
1315
+ });
1316
+ if (check && check.ok === false) {
1317
+ // Instances with a live lease are excluded: stopping another
1318
+ // session's VM would look like a takeover.
1319
+ const candidates = new Map(
1320
+ [...this.instances].filter(([id]) => !this.leaseBook.get(id)),
1321
+ );
1322
+ const victim = pickMemoryPressureVictim(candidates);
1323
+ if (victim) {
1324
+ const idleMs = Math.max(0, now - Number(victim.lastUsedAt || now));
1325
+ try {
1326
+ await victim.stop();
1327
+ stopped.push({ id: victim.id, idleMs, reason: 'memory-pressure' });
1328
+ this._log(
1329
+ `[instances] memory-pressure stopped ${victim.id} (free ${this.memoryProvider.formatMemory(hostInfo.freeBytes)}, ${check.reason})`,
1330
+ );
1331
+ } catch (error) {
1332
+ this._log(`[instances] memory-pressure stop failed for ${victim.id}: ${error && error.message ? error.message : error}`);
1333
+ }
1334
+ }
1335
+ }
1336
+ }
1337
+ } catch (error) {
1338
+ this._log(`[instances] memory-pressure reap failed: ${error && error.message ? error.message : error}`);
1339
+ }
1340
+ }
868
1341
  return stopped;
869
1342
  }
870
1343