kiku-agent 1.3.1 → 1.3.3

package/server/agent/lmStudioWakeup.js

@@ -2,12 +2,119 @@ import { spawn } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
 import fs from 'node:fs';
+import { resolveDynamicWindowsAppPaths } from './appPaths.js';
+import { registerBackgroundProcess } from './processManager.js';
+
+const LMSTUDIO_PROBE_TTL_MS = 15_000;
+const lmStudioProbeCache = new Map();
+
+
+export function clearLmStudioProbeCache() {
+  lmStudioProbeCache.clear();
+}
+
+
+export async function probeLmStudioRuntime(baseUrl = 'http://127.0.0.1:1234/v1', options = {}) {
+  const { timeoutMs = 2500, bypassCache = false } = options;
+  const key = String(baseUrl || 'http://127.0.0.1:1234/v1');
+
+  if (!bypassCache) {
+    const cached = lmStudioProbeCache.get(key);
+    if (cached) {
+      if (cached.inFlight) return cached.inFlight;
+      if (Date.now() - cached.fetchedAt < LMSTUDIO_PROBE_TTL_MS) return cached.data;
+    }
+  }
+
+  const inFlightPromise = probeLmStudioRuntimeUncached(baseUrl, timeoutMs);
+  const entry = { fetchedAt: Date.now(), data: null, inFlight: inFlightPromise };
+  lmStudioProbeCache.set(key, entry);
 
-export async function isLmStudioResponding(baseUrl = 'http://127.0.0.1:1234/v1', timeoutMs = 2500) {
   try {
-    const root = baseUrl.replace(/\/v1\/?$/, '').replace(/\/+$/, '');
+    const result = await inFlightPromise;
+    entry.data = result;
+    entry.fetchedAt = Date.now();
+    return result;
+  } catch (err) {
+    lmStudioProbeCache.delete(key);
+    throw err;
+  } finally {
+    entry.inFlight = null;
+  }
+}
+
+async function probeLmStudioRuntimeUncached(baseUrl = 'http://127.0.0.1:1234/v1', timeoutMs = 2500) {
+  const result = {
+    reachable: false,
+    loadedModel: null,
+    loadedModels: [],
+    loadedModelType: null,
+    loadedContextLength: null,
+    modelMaxContextLength: null,
+    quantization: null,
+    pendingModel: null,
+    models: []
+  };
+
+  const root = String(baseUrl || 'http://127.0.0.1:1234/v1').replace(/\/v1\/?$/, '').replace(/\/+$/, '');
+
+
+  try {
+    const res = await fetch(`${root}/api/v0/models`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (res.ok) {
+      const data = await res.json();
+      const models = Array.isArray(data?.data) ? data.data : [];
+      if (models.length > 0) {
+        result.reachable = true;
+        result.models = models.map(m => m.id).filter(Boolean);
+
+        const loadedList = models.filter(m => m.state === 'loaded');
+        result.loadedModels = loadedList.map(m => m.id).filter(Boolean);
+
+        const activeLoaded = loadedList.find(m => m.type === 'llm' || m.type === 'vlm') || loadedList[0];
+        if (activeLoaded) {
+          result.loadedModel = activeLoaded.id || null;
+          result.loadedModelType = activeLoaded.type || null;
+          result.loadedContextLength = activeLoaded.loaded_context_length ?? activeLoaded.max_context_length ?? null;
+          result.modelMaxContextLength = activeLoaded.max_context_length ?? activeLoaded.loaded_context_length ?? null;
+          result.quantization = activeLoaded.quantization || null;
+          return result;
+        }
+
+        const pending = models.find(m => (m.state === 'loading') && (m.type === 'llm' || m.type === 'vlm'))
+          || models.find(m => m.state === 'loading');
+        if (pending) result.pendingModel = pending.id || null;
+        return result;
+      }
+    }
+  } catch {
+    
+  }
+
+  
+  try {
     const res = await fetch(`${root}/v1/models`, { signal: AbortSignal.timeout(timeoutMs) });
-    return res.ok;
+    if (res.ok) {
+      const data = await res.json();
+      const models = Array.isArray(data?.data) ? data.data : (Array.isArray(data) ? data : []);
+      result.reachable = true;
+      result.models = models.map(m => typeof m === 'string' ? m : (m.id || m.name)).filter(Boolean);
+      result.loadedModels = [...result.models];
+      result.loadedModel = result.models[0] || null;
+      result.loadedModelType = 'llm';
+      return result;
+    }
+  } catch {
+   
+  }
+
+  return result;
+}
+
+export async function isLmStudioResponding(baseUrl = 'http://127.0.0.1:1234/v1', timeoutMs = 2500) {
+  try {
+    const probe = await probeLmStudioRuntime(baseUrl, { timeoutMs, bypassCache: true });
+    return Boolean(probe?.reachable);
   } catch {
     return false;
   }
@@ -15,11 +122,8 @@ export async function isLmStudioResponding(baseUrl = 'http://127.0.0.1:1234/v1',
 
 export async function getLoadedModels(baseUrl = 'http://127.0.0.1:1234/v1', timeoutMs = 2500) {
   try {
-    const root = baseUrl.replace(/\/v1\/?$/, '').replace(/\/+$/, '');
-    const res = await fetch(`${root}/v1/models`, { signal: AbortSignal.timeout(timeoutMs) });
-    if (!res.ok) return [];
-    const data = await res.json();
-    return Array.isArray(data.data) ? data.data.map(m => m.id) : [];
+    const probe = await probeLmStudioRuntime(baseUrl, { timeoutMs, bypassCache: true });
+    return probe?.loadedModels || [];
   } catch {
     return [];
   }
@@ -30,6 +134,7 @@ export function resolveLmsCli() {
   const isWin = process.platform === 'win32';
   const candidates = [
     path.join(userHome, '.lmstudio', 'bin', isWin ? 'lms.exe' : 'lms'),
+    path.join(process.env.LOCALAPPDATA || '', 'Programs', 'LM Studio', 'resources', 'app', 'bin', isWin ? 'lms.exe' : 'lms'),
     isWin ? 'lms.exe' : 'lms'
   ];
   return candidates.find(c => {
@@ -37,76 +142,260 @@ export function resolveLmsCli() {
   }) || (isWin ? 'lms.exe' : 'lms');
 }
 
+export function normalizeLmStudioModelKey(modelInput) {
+  if (!modelInput || typeof modelInput !== 'string') return 'google/gemma-4-e4b';
+  const trimmed = modelInput.trim();
+  if (!trimmed) return 'google/gemma-4-e4b';
+
+  if (trimmed === 'google/gemma-4-e4b' || trimmed.startsWith('google/gemma-4-e4b@')) {
+    return trimmed;
+  }
+
+  const clean = trimmed.toLowerCase().replace(/\\/g, '/');
+  const baseName = clean.split('/').pop() || clean;
+
+  if (/(?=.*gemma)(?=.*e4b)/i.test(baseName)) {
+    if (/(?:q6|6bit)/i.test(baseName)) return 'google/gemma-4-e4b@q6_k';
+    if (/(?:q8|8bit)/i.test(baseName)) return 'google/gemma-4-e4b@q8_0';
+    return 'google/gemma-4-e4b';
+  }
+
+  if (baseName.endsWith('.gguf')) {
+    return baseName.slice(0, -5);
+  }
+
+  return trimmed;
+}
+
+export function resolveParallelSlotBudget(requested, availableCpus = os.cpus()?.length, options = {}) {
+  const detected = Number(availableCpus);
+  const logicalCpus = Number.isFinite(detected) && detected > 0 ? Math.floor(detected) : 4;
+  const physicalCores = Number(options?.physicalCores) || (options?.hyperThreading ? Math.max(1, Math.floor(logicalCpus / 2)) : logicalCpus);
+  const htMode = String(options?.htMode || 'auto').toLowerCase();
+
+  let effectiveMax = logicalCpus;
+  if (htMode === 'physical' || options?.hyperThreading === false) {
+    effectiveMax = physicalCores;
+  }
+
+  const ceiling = Math.max(1, Math.min(256, effectiveMax));
+  const num = Number(requested);
+  if (!Number.isFinite(num) || num < 1 || num > 256) {
+    return { value: undefined, requested: num, ceiling, capped: false, htMode, physicalCores, logicalCpus };
+  }
+  const floored = Math.floor(num);
+  const value = Math.min(floored, ceiling);
+  return { value, requested: floored, ceiling, capped: value < floored, htMode, physicalCores, logicalCpus };
+}
+
+export function buildLmsLoadArgs(model, options = {}) {
+  const args = ['load', model, '-y', '--identifier', model];
+  const isGemma4E4b = /(?:^|[\\/])gemma[-_. ]?4[-_. ]?e4b(?:@|$)|^google\/gemma-4-e4b/i.test(String(model || ''));
+  const gpu = options.gpuOffload ?? options.nGpuLayers ?? options.gpu;
+  if (gpu !== undefined && gpu !== null && gpu !== 'auto' && gpu !== '') {
+    const gpuStr = String(gpu).toLowerCase().trim();
+    if (gpuStr === 'off' || gpuStr === '0') {
+      args.push('--gpu', 'off');
+    } else if (gpuStr === 'max' || gpuStr === 'all') {
+      args.push('--gpu', 'max');
+    } else {
+      const num = Number(gpuStr);
+      if (Number.isFinite(num)) {
+        if (num >= 0 && num <= 1) {
+          args.push('--gpu', String(num));
+        } else if (num >= 90) {
+          args.push('--gpu', 'max');
+        } else if (num > 1) {
+          const ratio = Math.min(1, Math.round((num / 33) * 100) / 100);
+          args.push('--gpu', String(ratio));
+        }
+      }
+    }
+  }
+  const ctx = Number(options.contextLength ?? (isGemma4E4b ? 32768 : undefined));
+  if (Number.isFinite(ctx) && ctx >= 512 && ctx <= 131072) {
+    args.push('--context-length', String(Math.floor(ctx)));
+  }
+  const parallel = options.parallel !== undefined
+    ? Number(options.parallel)
+    : (options.parallelSlots !== undefined
+      ? Number(options.parallelSlots)
+      : (options.cpuThreads !== undefined ? Number(options.cpuThreads) : (options.threads !== undefined ? Number(options.threads) : (isGemma4E4b ? 1 : undefined))));
+  const budget = resolveParallelSlotBudget(parallel, options.availableCpus, {
+    htMode: options.htMode || options.hyperThreadingMode,
+    physicalCores: options.physicalCores,
+    hyperThreading: options.hyperThreading,
+  });
+  if (budget.value !== undefined) {
+    args.push('--parallel', String(budget.value));
+  }
+
+  if (options.ttl && Number.isFinite(Number(options.ttl)) && Number(options.ttl) > 0) {
+    args.push('--ttl', String(Math.floor(Number(options.ttl))));
+  }
+  return args;
+}
+
 export async function loadLmStudioModel(model, options = {}) {
   const lmsCmd = resolveLmsCli();
-  return new Promise((resolve) => {
-    const args = ['load', model, '-y', '--identifier', model];
-    const child = spawn(lmsCmd, args, {
-      windowsHide: true,
-      stdio: 'pipe',
-      shell: process.platform === 'win32'
-    });
+  const normalized = normalizeLmStudioModelKey(model);
+
+  const executeLoad = (targetModel) => new Promise((resolve) => {
+    const args = buildLmsLoadArgs(targetModel, options);
+    const isCmdOrBat = process.platform === 'win32' && (lmsCmd.toLowerCase().endsWith('.cmd') || lmsCmd.toLowerCase().endsWith('.bat'));
+    let child;
+    if (isCmdOrBat) {
+      const cmdString = `"${lmsCmd}" ${args.map(a => `"${a}"`).join(' ')}`;
+      child = spawn(cmdString, {
+        windowsHide: true,
+        stdio: 'pipe',
+        shell: true
+      });
+    } else {
+      child = spawn(lmsCmd, args, {
+        windowsHide: true,
+        stdio: 'pipe',
+        shell: false
+      });
+    }
     let output = '';
     child.stdout?.on('data', d => { output += d.toString(); });
     child.stderr?.on('data', d => { output += d.toString(); });
     child.on('close', code => {
-      resolve({ ok: code === 0, output });
+      resolve({ ok: code === 0, output, args, exitCode: code });
     });
     child.on('error', err => {
-      resolve({ ok: false, error: err.message });
+      resolve({ ok: false, error: err.message, args });
     });
   });
+
+  const primaryResult = await executeLoad(normalized);
+  if (primaryResult.ok || primaryResult.exitCode === 0) {
+    return primaryResult;
+  }
+
+  if (primaryResult.output && /Model not found|No model found/i.test(primaryResult.output)) {
+    try {
+      const isCmdOrBat = process.platform === 'win32' && (lmsCmd.toLowerCase().endsWith('.cmd') || lmsCmd.toLowerCase().endsWith('.bat'));
+      const lsOutput = await new Promise((res) => {
+        const lsChild = isCmdOrBat
+          ? spawn(`"${lmsCmd}" ls --json`, { windowsHide: true, stdio: 'pipe', shell: true })
+          : spawn(lmsCmd, ['ls', '--json'], { windowsHide: true, stdio: 'pipe', shell: false });
+        let out = '';
+        lsChild.stdout?.on('data', d => { out += d.toString(); });
+        lsChild.stderr?.on('data', d => { out += d.toString(); });
+        lsChild.on('close', () => res(out));
+        lsChild.on('error', () => res(''));
+      });
+
+      if (lsOutput.trim()) {
+        const models = JSON.parse(lsOutput.trim());
+        if (Array.isArray(models) && models.length > 0) {
+          const rawSearch = String(model || '').toLowerCase();
+          const cleanSearch = rawSearch.replace(/\\/g, '/').split('/').pop().replace(/\.gguf$/i, '');
+          const match = models.find(m => {
+            const key = String(m.modelKey || '').toLowerCase();
+            const pathStr = String(m.path || '').toLowerCase();
+            const name = String(m.displayName || '').toLowerCase();
+            return key === cleanSearch || pathStr.includes(cleanSearch) || name.includes(cleanSearch) ||
+                   (cleanSearch.includes('gemma') && (key.includes('gemma') || name.includes('gemma')));
+          });
+          if (match?.modelKey && match.modelKey !== normalized) {
+            const retryRes = await executeLoad(match.modelKey);
+            if (retryRes.ok || retryRes.exitCode === 0) {
+              return retryRes;
+            }
+          }
+        }
+      }
+    } catch {}
+  }
+
+  return primaryResult;
 }
 
 export async function wakeUpLmStudio(options = {}) {
   const {
     baseUrl = 'http://127.0.0.1:1234/v1',
-    model = 'google/gemma-4-e4b',
-    maxWaitMs = 35000
+    model: rawModel = 'google/gemma-4-e4b',
+    maxWaitMs = 60000,
+    quiet = false,
+    gpuOffload,
+    cpuThreads,
+    contextLength,
+    parallel,
+    splitMode,
+    tensorSplit,
+    mainGpu,
+    flashAttn,
+    batchSize,
+    ubatchSize,
+    htMode,
+    hyperThreadingMode,
+    physicalCores,
+    hyperThreading,
   } = options;
 
-  const isLocal = baseUrl.includes('127.0.0.1') || baseUrl.includes('localhost');
+  const model = normalizeLmStudioModelKey(rawModel);
+
+  const isLocal = baseUrl.includes('127.0.0.1:1234') || baseUrl.includes('localhost:1234') || baseUrl.includes(':1234');
   if (!isLocal) {
-    return { ok: false, reason: 'Non-local endpoint, automatic wakeup skipped' };
+    return { ok: false, reason: 'Non-local or non-standard LM Studio endpoint, automatic wakeup skipped' };
   }
 
+  let probe = await probeLmStudioRuntime(baseUrl, { timeoutMs: 2000, bypassCache: true }).catch(() => null);
+  let serverUp = Boolean(probe?.reachable);
 
-  let serverUp = await isLmStudioResponding(baseUrl, 2000);
   if (!serverUp) {
-    const userHome = os.homedir();
-    const possiblePaths = [
-      path.join(userHome, 'AppData', 'Local', 'Programs', 'LM Studio', 'LM Studio.exe'),
-      path.join(process.env.LOCALAPPDATA || '', 'Programs', 'LM Studio', 'LM Studio.exe'),
-      'C:\\Program Files\\LM Studio\\LM Studio.exe'
-    ];
-
-    const appExe = possiblePaths.find(p => p && fs.existsSync(p));
-    if (appExe) {
-      try {
-        const child = spawn(appExe, [], {
+    
+    try {
+      const lmsCmd = resolveLmsCli();
+      const portMatch = String(baseUrl).match(/:([0-9]+)/);
+      const targetPort = portMatch ? portMatch[1] : '1234';
+      const isCmdOrBat = process.platform === 'win32' && (lmsCmd.toLowerCase().endsWith('.cmd') || lmsCmd.toLowerCase().endsWith('.bat'));
+      let lmsChild;
+      if (isCmdOrBat) {
+        const cmdString = `"${lmsCmd}" server start --port ${targetPort} --cors`;
+        lmsChild = spawn(cmdString, {
           detached: true,
           stdio: 'ignore',
-          windowsHide: false
+          windowsHide: true,
+          shell: true
         });
-        child.unref();
-      } catch {}
-    }
-
-    try {
-      const lmsCmd = resolveLmsCli();
-      const lmsChild = spawn(lmsCmd, ['server', 'start'], {
-        detached: true,
-        stdio: 'ignore',
-        windowsHide: true,
-        shell: process.platform === 'win32'
-      });
+      } else {
+        lmsChild = spawn(lmsCmd, ['server', 'start', '--port', targetPort, '--cors'], {
+          detached: true,
+          stdio: 'ignore',
+          windowsHide: true,
+          shell: false
+        });
+      }
+      if (lmsChild.pid) {
+        registerBackgroundProcess('lmstudio-server', lmsChild, {
+          command: lmsCmd,
+          args: ['server', 'start', '--port', targetPort, '--cors'],
+          metadata: { type: 'headless-task', port: targetPort, baseUrl, persistOnExit: true },
+          persistOnExit: true,
+        });
+        registerBackgroundProcess('lmstudio', lmsChild, {
+          command: lmsCmd,
+          args: ['server', 'start', '--port', targetPort, '--cors'],
+          metadata: { type: 'headless-task', port: targetPort, baseUrl, persistOnExit: true },
+          persistOnExit: true,
+        });
+      }
       lmsChild.unref();
-    } catch {}
+    } catch (err) {
+      if (!quiet) {
+        try { process.stderr.write(`[Kiku Auto-Wakeup] Failed to launch headless LM Studio server: ${err.message}\n`); } catch {}
+      }
+    }
 
     const start = Date.now();
     while (Date.now() - start < maxWaitMs) {
-      await new Promise(r => setTimeout(r, 1500));
-      if (await isLmStudioResponding(baseUrl, 2000)) {
+      await new Promise(r => setTimeout(r, 1200));
+      probe = await probeLmStudioRuntime(baseUrl, { timeoutMs: 2000, bypassCache: true }).catch(() => null);
+      if (probe?.reachable) {
         serverUp = true;
         break;
       }
@@ -114,31 +403,194 @@ export async function wakeUpLmStudio(options = {}) {
   }
 
   if (!serverUp) {
-    return { ok: false, reason: 'Timed out waiting for LM Studio server' };
+    return { ok: false, reason: 'Timed out waiting for LM Studio server on port 1234' };
   }
 
-
   if (model) {
-    const loaded = await getLoadedModels(baseUrl);
-    if (!loaded.includes(model)) {
-      try {
-        process.stdout.write(`\n🌸 [Kiku Auto-Wakeup] LM Studio server active. Auto-loading model "${model}" into VRAM...\n`);
-      } catch {}
-      await loadLmStudioModel(model);
+    const isModelLoaded = (probe?.loadedModels && probe.loadedModels.includes(model)) ||
+                          (probe?.loadedModel && (probe.loadedModel === model || probe.loadedModel.includes(model)));
+    if (!isModelLoaded) {
+      if (!quiet) {
+        try {
+          process.stdout.write(`\n🌸 [Kiku Auto-Wakeup] LM Studio server active. Auto-loading model "${model}" into VRAM...\n`);
+        } catch {}
+      }
+      const loadRes = await loadLmStudioModel(model, {
+        gpuOffload,
+        cpuThreads,
+        contextLength,
+        parallel,
+        splitMode,
+        tensorSplit,
+        mainGpu,
+        flashAttn,
+        batchSize,
+        ubatchSize,
+        htMode: htMode || hyperThreadingMode,
+        physicalCores,
+        hyperThreading,
+      });
+      if (!loadRes.ok && loadRes.exitCode !== 0) {
+        const immediateProbe = await probeLmStudioRuntime(baseUrl, { timeoutMs: 2000, bypassCache: true }).catch(() => null);
+        const loaded = (immediateProbe?.loadedModels && immediateProbe.loadedModels.includes(model)) ||
+                       (immediateProbe?.loadedModel && (immediateProbe.loadedModel === model || immediateProbe.loadedModel.includes(model)));
+        if (!loaded) {
+          return {
+            ok: false,
+            modelLoaded: false,
+            reason: `LM Studio CLI failed to load model "${model}" (exit code ${loadRes.exitCode ?? 'error'}). ${loadRes.output || loadRes.error || ''}`.trim()
+          };
+        }
+      }
 
       const start = Date.now();
+      let ready = false;
       while (Date.now() - start < maxWaitMs) {
-        await new Promise(r => setTimeout(r, 1500));
-        const currentModels = await getLoadedModels(baseUrl);
-        if (currentModels.includes(model)) {
-          try {
-            process.stdout.write(`🌸 [Kiku Auto-Wakeup] Model "${model}" loaded and ready!\n\n`);
-          } catch {}
-          return { ok: true, awakened: true, modelLoaded: true };
+        await new Promise(r => setTimeout(r, 1200));
+        probe = await probeLmStudioRuntime(baseUrl, { timeoutMs: 2000, bypassCache: true }).catch(() => null);
+        ready = (probe?.loadedModels && probe.loadedModels.includes(model)) ||
+                (probe?.loadedModel && (probe.loadedModel === model || probe.loadedModel.includes(model)));
+        if (ready) {
+          if (!quiet) {
+            try {
+              process.stdout.write(`🌸 [Kiku Auto-Wakeup] Model "${model}" loaded and ready!\n\n`);
+            } catch {}
+          }
+          return { ok: true, awakened: true, modelLoaded: true, loadedModel: model };
         }
       }
+
+      if (!ready) {
+        return {
+          ok: false,
+          modelLoaded: false,
+          reason: `Timed out waiting for model "${model}" to load into VRAM (${Math.round(maxWaitMs / 1000)}s)`
+        };
+      }
+    }
+  }
+
+  return { ok: true, alreadyRunning: true, modelLoaded: true, loadedModel: probe?.loadedModel || model };
+}
+
+export async function unloadLmStudioModel(model = null, options = {}) {
+  const baseUrl = options.baseUrl || 'http://127.0.0.1:1234/v1';
+  const root = baseUrl.replace(/\/v1\/?$/, '').replace(/\/+$/, '');
+  const timeoutMs = Number(options.timeoutMs) > 0 ? Number(options.timeoutMs) : 2500;
+  const isDefaultPort = !options.baseUrl || options.baseUrl.includes(':1234');
+  let restSuccess = false;
+  let restMessage = '';
+
+  let loadedModels = [];
+  try {
+    const probeRes = await fetch(`${root}/api/v0/models`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (probeRes.ok) {
+      const probeData = await probeRes.json().catch(() => null);
+      const items = Array.isArray(probeData?.data) ? probeData.data : [];
+      loadedModels = items.filter(m => m.state === 'loaded').map(m => m.id).filter(Boolean);
+    }
+  } catch {}
+
+  if (loadedModels.length === 0) {
+    try {
+      const probeRes = await fetch(`${root}/v1/models`, { signal: AbortSignal.timeout(timeoutMs) });
+      if (probeRes.ok) {
+        const probeData = await probeRes.json().catch(() => null);
+        const items = Array.isArray(probeData?.data) ? probeData.data : (Array.isArray(probeData) ? probeData : []);
+        loadedModels = items.map(m => typeof m === 'string' ? m : (m.id || m.name)).filter(Boolean);
+      }
+    } catch {}
+  }
+
+  const rawModel = model ? String(model).trim() : '';
+  const normalizedKey = rawModel ? normalizeLmStudioModelKey(rawModel) : '';
+
+  let targetIds = [];
+  if (rawModel && rawModel !== 'all') {
+    const exact = loadedModels.find(id => id.toLowerCase() === rawModel.toLowerCase());
+    const norm = loadedModels.find(id => id.toLowerCase() === normalizedKey.toLowerCase());
+    const partial = loadedModels.find(id => {
+      const lid = id.toLowerCase();
+      const lraw = rawModel.toLowerCase();
+      const lnorm = normalizedKey.toLowerCase();
+      return lid.includes(lraw) || lraw.includes(lid) || (lnorm && (lid.includes(lnorm) || lnorm.includes(lid)));
+    });
+
+    if (exact) targetIds = [exact];
+    else if (norm) targetIds = [norm];
+    else if (partial) targetIds = [partial];
+    else if (loadedModels.length === 1) targetIds = [loadedModels[0]];
+    else targetIds = [normalizedKey || rawModel];
+  } else {
+    targetIds = loadedModels.length > 0 ? [...loadedModels] : [];
+  }
+
+  let unloadedCount = 0;
+  if (targetIds.length > 0) {
+    for (const tid of targetIds) {
+      try {
+        const res = await fetch(`${root}/api/v1/models/unload`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ instance_id: tid }),
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+        if (res.ok) {
+          const data = await res.json().catch(() => null);
+          if (data && (data.instance_id || !data.error)) {
+            unloadedCount++;
+          }
+        }
+      } catch {}
     }
   }
 
-  return { ok: true, alreadyRunning: true };
+  if (unloadedCount > 0) {
+    restSuccess = true;
+    restMessage = 'Model successfully unloaded from LM Studio and GPU VRAM released';
+  }
+
+  let cliSuccess = false;
+  let cliOutput = '';
+  if (!restSuccess && isDefaultPort) {
+    try {
+      const lmsCmd = resolveLmsCli();
+      const runCli = (args) => {
+        const isCmdOrBat = process.platform === 'win32' && (lmsCmd.toLowerCase().endsWith('.cmd') || lmsCmd.toLowerCase().endsWith('.bat'));
+        return new Promise((resolve) => {
+          const child = isCmdOrBat
+            ? spawn(`"${lmsCmd}" ${args.join(' ')}`, { windowsHide: true, stdio: 'pipe', shell: true })
+            : spawn(lmsCmd, args, { windowsHide: true, stdio: 'pipe', shell: false });
+          let out = '';
+          child.stdout?.on('data', d => { out += d.toString(); });
+          child.stderr?.on('data', d => { out += d.toString(); });
+          child.on('close', code => {
+            const combined = out.trim();
+            const hasError = !combined || /(?:model not found|cannot find a model|error|failed)/i.test(combined);
+            resolve({ ok: code === 0 && !hasError, code, out: combined });
+          });
+          child.on('error', err => resolve({ ok: false, code: -1, out: err.message }));
+        });
+      };
+
+      const primaryTarget = targetIds[0] || (rawModel !== 'all' ? (normalizedKey || rawModel) : null);
+      let cliResult = await runCli(primaryTarget ? ['unload', primaryTarget] : ['unload', '--all']);
+      if (!cliResult.ok) {
+        cliResult = await runCli(['unload', '--all']);
+      }
+      cliSuccess = cliResult.ok || /(?:unloaded|released|success|no models to unload)/i.test(cliResult.out);
+      cliOutput = cliResult.out;
+    } catch {}
+  }
+
+  clearLmStudioProbeCache();
+
+  const success = restSuccess || cliSuccess || (loadedModels.length === 0 && Boolean(cliOutput && /no models to unload/i.test(cliOutput)));
+  return {
+    ok: success,
+    unloaded: success,
+    engine: 'lms',
+    model: targetIds[0] || model || 'all',
+    message: success ? (restMessage || cliOutput || 'Model successfully unloaded from VRAM') : (cliOutput || 'Failed to unload model from LM Studio')
+  };
 }