Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { invalidateModelObservation } from './modelObservation.js';
/**
* LM Studio Manager Service
*
* Manages local LM Studio models for free local thinking.
* Provides model discovery, loading, unloading, and downloading.
*/
import { homedir } from 'os'
import { join, basename, resolve, relative, isAbsolute, sep } from 'path'
import { existsSync } from 'fs'
import { readdir, stat, copyFile, link, rm, rmdir } from 'fs/promises'
import { dirSize, ensureDir } from '../lib/fileUtils.js'
import { cosEvents } from './cosEvents.js'
import { fetchWithTimeout } from '../lib/fetchWithTimeout.js'
import {
dirIsMlx, selectPrimaryGguf, selectProjectorGguf, isShardedGguf, lmStudioPublisherRepo
} from '../lib/localLlmDisk.js'
import { bufferedSpawn } from '../lib/bufferedSpawn.js'
import { findCommandOnPath } from '../lib/processEnv.js'
const AVAILABILITY_CACHE_TTL_MS = 30_000
const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
// Availability probe is short — if the local server is down we'd rather fail
// fast and degrade to "no LM Studio" than block 30s on every cold check.
const AVAILABILITY_PROBE_TIMEOUT_MS = 5_000
// `lms server start|stop` only asks the already-installed app to flip its
// listener — it never downloads anything, so a minute is generous.
const LMS_CONTROL_TIMEOUT_MS = 60_000
const LMS_UNLOAD_TIMEOUT_MS = 60_000
// `lms load` reads a multi-gigabyte GGUF off disk and allocates its KV cache;
// on a cold page cache that is minutes, not seconds.
const LMS_LOAD_TIMEOUT_MS = 300_000
// Default LM Studio configuration
const normalizeBaseUrl = (value) => String(value || '').trim().replace(/\/+$/, '').replace(/\/v1$/, '')
const DEFAULT_CONFIG = {
baseUrl: normalizeBaseUrl(process.env.LM_STUDIO_URL || 'http://localhost:1234'),
timeout: DEFAULT_REQUEST_TIMEOUT_MS,
defaultThinkingModel: 'gpt-oss-20b'
}
// Cached state
let config = { ...DEFAULT_CONFIG }
let isAvailable = null
// null = not yet fetched; any array (even empty) = a cached result — mirrors
// availableModels below so an idle LM Studio (server up, 0 models loaded)
// doesn't re-hit /api/v0/models on every status poll.
let loadedModels = null
let lastLoadedModelsError = null
// null = not yet fetched; any array (even empty) = a cached result. Lets the
// catalog-overlay path (queried per keystroke) reuse the list instead of
// re-hitting /api/v0/models each time. Busted to null by resetCache().
let availableModels = null
// Last error from the model-LIST call (/api/v0/models), distinct from the
// availability probe (/v1/models): LM Studio can answer the probe yet fail the
// list, so this lets callers tell "0 models" from "couldn't list models".
let lastListError = null
let lastCheckAt = null
// Model id → the `lms load` flags PortOS loaded it with. An entry means that
// model is resident under a PortOS tuning; its absence means it is not, which is
// what lets an UNTUNED assessment tell "already at defaults, relaunch nothing"
// from "still carrying the last sweep's flags, reload without them". Without it
// a baseline reading is filed as "Backend defaults" while the model is loaded at
// the previous run's context length.
//
// Deliberately NOT cleared by `resetCache` (`runLms` resets the model caches
// after every command, including the load that just set this) and not by a
// failed availability probe either. A stale entry costs one reload nobody needed
// and still leaves the model untuned; a wrongly-dropped one silently restores
// the mislabeling this record exists to prevent. Only an unload clears it.
const tunedLoads = new Map()
// Status tracking
const status = {
lastError: null,
lastSuccessAt: null,
consecutiveErrors: 0
}
/**
* Make a request to LM Studio API
* @param {string} endpoint - API endpoint
* @param {Object} options - Fetch options
* @returns {Promise<*>} - Response data
*/
async function lmStudioRequestAt(baseUrl, endpoint, options = {}) {
const url = `${normalizeBaseUrl(baseUrl)}${endpoint}`
const { timeout, headers, ...rest } = options
const response = await fetchWithTimeout(url, {
...rest,
headers: {
'Content-Type': 'application/json',
...headers
}
}, timeout || config.timeout)
if (!response.ok) {
throw new Error(`LM Studio API error: ${response.status} ${response.statusText}`)
}
return response.json()
}
async function lmStudioRequest(endpoint, options = {}) {
return lmStudioRequestAt(config.baseUrl, endpoint, options)
}
/**
* Check if LM Studio is available
* @returns {Promise<boolean>} - True if available
*/
async function checkLMStudioAvailable(forceRefresh = false) {
const now = Date.now()
// Use cached result if recent (within AVAILABILITY_CACHE_TTL_MS).
if (!forceRefresh && lastCheckAt && now - lastCheckAt < AVAILABILITY_CACHE_TTL_MS && isAvailable !== null) {
return isAvailable
}
try {
await lmStudioRequest('/v1/models', { timeout: AVAILABILITY_PROBE_TIMEOUT_MS })
isAvailable = true
status.lastSuccessAt = now
status.consecutiveErrors = 0
status.lastError = null
lastCheckAt = now
return true
} catch (err) {
isAvailable = false
status.lastError = err.message
status.consecutiveErrors++
lastCheckAt = now
return false
}
}
/**
* Read residency from a specific provider endpoint without touching the global
* manager's availability cache or error state.
* @returns {Promise<{models:Array,error:string|null}>}
*/
async function getLoadedModelsAt(baseUrl) {
// Use native REST API for richer model info (type, state, architecture)
const nativeModels = await lmStudioRequestAt(baseUrl, '/api/v0/models').catch((err) => ({ _err: err.message }))
if (Array.isArray(nativeModels?.data)) {
return {
models: nativeModels.data
.filter(model => model.state === 'loaded')
.map(model => ({
id: model.id,
object: model.object || 'model',
type: model.type,
arch: model.arch,
quantization: model.quantization,
state: model.state,
maxContextLength: model.max_context_length,
ownedBy: model.publisher
})),
error: null
}
}
// Fallback to OpenAI-compat endpoint
const response = await lmStudioRequestAt(baseUrl, '/v1/models').catch((err) => ({ _err: err.message }))
if (Array.isArray(response?.data)) {
return {
models: response.data.map(model => ({
id: model.id,
object: model.object,
created: model.created,
ownedBy: model.owned_by
})),
error: null
}
}
return {
models: [],
error: nativeModels?._err || response?._err || 'LM Studio loaded-model endpoints returned no data'
}
}
/**
* Get currently loaded models from the configured LM Studio server.
* @param {boolean} forceRefresh - Force refresh from API
* @returns {Promise<Array>} - Loaded models
*/
async function getLoadedModels(forceRefresh = false) {
if (!forceRefresh && loadedModels !== null) {
return loadedModels
}
const available = await checkLMStudioAvailable(forceRefresh)
if (!available) {
// Don't cache — unavailable is transient, so the next call re-probes.
lastLoadedModelsError = status.lastError || 'LM Studio is unavailable'
return []
}
const result = await getLoadedModelsAt(config.baseUrl)
lastLoadedModelsError = result.error
if (result.error) return []
loadedModels = result.models
return loadedModels
}
/** Last loaded-model probe error (null only after a trustworthy list). */
function getLastLoadedModelsError() {
return lastLoadedModelsError
}
/**
* Get all downloaded models (loaded and not-loaded).
* @param {boolean} [forceRefresh] - bypass the cache (callers that read live
* per-model `state`, e.g. embedding-model discovery, should force).
* @returns {Promise<Array>} - All downloaded models with state info
*/
async function getAvailableModels(forceRefresh = false) {
if (!forceRefresh && availableModels !== null) return availableModels
const available = await checkLMStudioAvailable(forceRefresh)
if (!available) {
// Unreachable is surfaced by the availability probe (`available`), not here.
lastListError = null
return []
}
const response = await lmStudioRequest('/api/v0/models').catch((err) => ({ _err: err.message }))
if (response?.data) {
lastListError = null
availableModels = response.data.map(model => ({
id: model.id,
type: model.type,
arch: model.arch,
publisher: model.publisher,
quantization: model.quantization,
state: model.state,
maxContextLength: model.max_context_length
}))
return availableModels
}
// Reachable (the /v1/models probe passed) but the native model-list call
// failed or returned no data — record it so callers can distinguish this from
// a genuinely empty list. Fall back to loaded models for a best-effort list.
lastListError = response?._err || 'LM Studio model list (/api/v0/models) returned no data'
return getLoadedModels(true)
}
/** Last `/api/v0/models` list error (null if the most recent list succeeded). */
function getLastListError() {
return lastListError
}
/**
* Download a model from LM Studio catalog
* @param {string} modelId - Model identifier to download
* @returns {Promise<Object>} - Download result
*/
async function downloadModel(modelId) {
const available = await checkLMStudioAvailable()
if (!available) {
return { success: false, error: 'LM Studio not available' }
}
console.log(`📥 Downloading model: ${modelId}`)
cosEvents.emit('lmstudio:downloadRequested', { modelId })
const response = await lmStudioRequest('/api/v1/models/download', {
method: 'POST',
body: JSON.stringify({ model: modelId }),
timeout: 10000
}).catch(err => ({ _err: err.message }))
if (response._err) {
console.error(`⚠️ Failed to start download for ${modelId}: ${response._err}`)
return { success: false, error: response._err, modelId }
}
return { success: true, modelId, ...response }
}
/**
* Load a model into LM Studio memory
* @param {string} modelId - Model identifier (publisher/model-name format)
* @returns {Promise<Object>} - Load result
*/
async function loadModel(modelId) {
const available = await checkLMStudioAvailable()
if (!available) {
return { success: false, error: 'LM Studio not available' }
}
// Use the native REST API load endpoint
const response = await lmStudioRequest('/api/v1/models/load', {
method: 'POST',
body: JSON.stringify({ model: modelId }),
timeout: 60000 // Loading can take a while
}).catch(err => ({ _err: err.message }))
if (response._err) {
console.error(`⚠️ Failed to load model ${modelId}: ${response._err}`)
return { success: false, error: response._err, modelId }
}
// Refresh loaded models
await getLoadedModels(true)
console.log(`📦 Model loaded: ${modelId}`)
cosEvents.emit('lmstudio:modelLoaded', { modelId })
invalidateModelObservation('loaded-models')
invalidateModelObservation('provider-readiness')
return { success: true, modelId, ...response }
}
/**
* Reload a model through the `lms` CLI with explicit load-time settings.
*
* LM Studio's context length, GPU offload, and parallelism are chosen when a
* model is LOADED — no request field changes them, and the REST load endpoint
* takes only a model id. `lms load` is the one path that carries them, so a
* tuned measurement of an LM Studio model goes through here or it is measuring
* whatever the app happened to be holding.
*
* The model is unloaded first: `lms load` on an already-resident model returns
* the existing instance rather than re-loading it at the new settings, which
* would report success for a tuning that never applied.
*
* An EMPTY `args` is the opposite request: reload the model with no tuning flags
* at all, so an untuned assessment measures a model that is actually untuned
* rather than whatever the previous sweep loaded. It is a no-op when PortOS did
* not load this model with flags — reloading anyway would cold-load the weights
* and the first sample would time the page-in.
*
* Resolves rather than throws (mirrors `controlServer`) so a caller can record
* the refusal alongside the reading it describes.
*
* @param {string} modelId
* @param {string[]} args - rendered flags, e.g. `['--context-length', '8192']`
* @returns {Promise<{ success: boolean, unchanged?: boolean, error?: string }>}
* `unchanged: true` means nothing needed reloading — not a refusal.
*/
async function loadModelWithArgs(modelId, args = []) {
if (!modelId) return { success: false, error: 'No model was named to load.' }
const signature = args.join(' ')
const carried = tunedLoads.get(modelId) || null
if (!signature && !carried) return { success: true, unchanged: true }
// `lms load` on an already-RESIDENT model returns the existing instance rather
// than re-loading it at the new settings, so the model has to be out of memory
// before the load or the call reports success for a configuration that never
// applied. That makes a refused unload fatal in both directions: a tuned load
// would file the previous configuration's throughput under the requested
// tuning, and a clear would file it as backend defaults.
//
// Gated on residency, not merely on availability. `unloadModel` also resolves
// `{ success: false }` for a model that simply is not loaded — the ordinary
// state before a first assessment — and reading that as a refusal would fail
// every first run and never record its tuning. Both probes are FORCED: a
// cached `false` availability, or a stale loaded-models list, would skip the
// unload and hand back exactly the stale instance this guards against.
if (await checkLMStudioAvailable(true)) {
const resident = await getLoadedModels(true).catch(() => [])
// `[]` from `getLoadedModels` means "nothing is loaded" OR "both list
// endpoints failed" — the null-vs-empty sentinel trap in root AGENTS.md, and
// `getLastLoadedModelsError` is the module's own way out of it. An
// untrustworthy list must not read as "not resident": that skips the unload,
// `lms load` hands back the existing instance, and the previous
// configuration's throughput is filed under this call's. Assume resident and
// try — a wasted unload attempt is recoverable, a stale instance is not.
const listTrusted = getLastLoadedModelsError() === null
const loaded = !listTrusted
|| resident.some((m) => m?.id === modelId || modelIdsReferToSameRepo(m?.id, modelId))
const unloaded = loaded
? await unloadModel(modelId).catch((err) => ({ success: false, error: err?.message }))
: { success: true }
// Checked BEFORE the load: once `lms load` has run, a refusal is no longer
// the whole story — the flags may genuinely be in effect.
if (!unloaded.success) {
return {
success: false,
error: unloaded.error
|| `LM Studio would not unload ${modelId}, so it is still loaded with ${carried || 'its previous settings'}`,
}
}
}
// `-y` because there is no one at a terminal to answer the model-picker prompt
// `lms load` opens when a key matches more than one download.
//
// `runLms` resets the model caches, so the next reader refetches lazily —
// forcing a refresh here would pay two loopback round trips for a value
// nothing reads between the load and the first sample.
const result = await runLms(['load', modelId, '-y', ...args], { timeoutMs: LMS_LOAD_TIMEOUT_MS })
if (!result.success) return result
if (signature) tunedLoads.set(modelId, signature)
else tunedLoads.delete(modelId)
console.log(`📦 LM Studio loaded ${modelId}${signature ? ` (${signature})` : ` without ${carried}`}`)
cosEvents.emit('lmstudio:modelLoaded', { modelId })
invalidateModelObservation('loaded-models')
invalidateModelObservation('provider-readiness')
return { success: true }
}
/**
* Unload a model from LM Studio memory
* @param {string} modelId - Model identifier to unload
* @returns {Promise<Object>} - Unload result
*/
async function unloadModel(modelId) {
const available = await checkLMStudioAvailable()
if (!available) {
return { success: false, error: 'LM Studio not available' }
}
let response = await lmStudioRequest('/api/v1/models/unload', {
method: 'POST',
body: JSON.stringify({ model: modelId }),
timeout: 15000
}).catch(err => ({ _err: err.message }))
// LM Studio releases have changed the native unload payload contract. A
// 400/404/405 means the server is reachable but this endpoint shape is not;
// fall back to the app's own non-interactive CLI, which accepts the stable
// model identifier returned by /api/v0/models. Do not bypass a 5xx "busy"
// response: that is a real runtime refusal, not API drift.
if (response._err && /\b(?:400|404|405)\b/.test(response._err)) {
const cli = await runLms(['unload', modelId], { timeoutMs: LMS_UNLOAD_TIMEOUT_MS })
response = cli.success ? {} : { _err: `${response._err}; ${cli.error}` }
}
if (response._err) {
console.error(`⚠️ Failed to unload model ${modelId}: ${response._err}`)
return { success: false, error: response._err, modelId }
}
// Refresh loaded models
await getLoadedModels(true)
// Whatever flags it was loaded with left with it.
tunedLoads.delete(modelId)
console.log(`📤 Model unloaded: ${modelId}`)
cosEvents.emit('lmstudio:modelUnloaded', { modelId })
invalidateModelObservation('loaded-models')
invalidateModelObservation('provider-readiness')
return { success: true, modelId }
}
/**
* Get the recommended thinking model
* @returns {Promise<string|null>} - Model ID or null if none available
*/
async function getRecommendedThinkingModel() {
const models = await getLoadedModels()
if (models.length === 0) {
return null
}
// Prefer specific thinking-optimized models
const preferredModels = [
'gpt-oss-20b',
'deepseek-r1',
'qwen2.5-coder',
'codellama',
'mistral',
'llama'
]
for (const preferred of preferredModels) {
const match = models.find(m =>
m.id.toLowerCase().includes(preferred.toLowerCase())
)
if (match) return match.id
}
// Return first available model
return models[0]?.id || null
}
/**
* Make a quick completion request for local thinking
* @param {string} prompt - Prompt text
* @param {Object} options - Completion options
* @returns {Promise<Object>} - Completion result
*/
async function quickCompletion(prompt, options = {}) {
const available = await checkLMStudioAvailable()
if (!available) {
return { success: false, error: 'LM Studio not available' }
}
const model = options.model || await getRecommendedThinkingModel()
if (!model) {
return { success: false, error: 'No model available' }
}
try {
const response = await lmStudioRequest('/v1/chat/completions', {
method: 'POST',
body: JSON.stringify({
model,
messages: [
...(options.systemPrompt ? [{ role: 'system', content: options.systemPrompt }] : []),
{ role: 'user', content: prompt }
],
max_tokens: options.maxTokens || 512,
temperature: options.temperature ?? 0.7,
stream: false
}),
timeout: options.timeout || 30000
})
const content = response.choices?.[0]?.message?.content || ''
return {
success: true,
content,
model,
usage: response.usage
}
} catch (err) {
return { success: false, error: err.message, model }
}
}
/**
* Get embeddings from local model
* @param {string} text - Text to embed
* @param {Object} options - Embedding options
* @returns {Promise<Object>} - Embedding result
*/
async function getEmbeddings(text, options = {}) {
const available = await checkLMStudioAvailable()
if (!available) {
return { success: false, error: 'LM Studio not available' }
}
// Auto-discover an embedding model if none specified
let model = options.model
if (!model) {
const models = await getAvailableModels(true) // need live per-model state
const embeddingModel = models.find(m => m.type === 'embeddings' && m.state === 'loaded')
|| models.find(m => m.type === 'embeddings')
if (embeddingModel) {
// Load it if not already loaded
if (embeddingModel.state !== 'loaded') {
await loadModel(embeddingModel.id)
}
model = embeddingModel.id
} else {
return { success: false, error: 'No embedding model available in LM Studio' }
}
}
const response = await lmStudioRequest('/v1/embeddings', {
method: 'POST',
body: JSON.stringify({ model, input: text }),
timeout: options.timeout || 10000
}).catch(err => ({ _err: err.message }))
if (response._err) {
return { success: false, error: response._err, model }
}
const embedding = response.data?.[0]?.embedding || []
return {
success: true,
embedding,
model,
dimensions: embedding.length
}
}
/**
* Get LM Studio status
* @returns {Promise<Object>} - Status information
*/
async function getStatus() {
const available = await checkLMStudioAvailable()
const models = available ? await getLoadedModels() : []
return {
available,
baseUrl: config.baseUrl,
loadedModels: models.length,
models: models.map(m => m.id),
recommendedThinkingModel: available ? await getRecommendedThinkingModel() : null,
lastCheckAt: lastCheckAt ? new Date(lastCheckAt).toISOString() : null,
lastSuccessAt: status.lastSuccessAt ? new Date(status.lastSuccessAt).toISOString() : null,
lastError: status.lastError,
consecutiveErrors: status.consecutiveErrors
}
}
/**
* Live base URL — reflects runtime `updateConfig()` patches, not just startup
* env. Used by sibling services (e.g. the local code-review endpoint) so a
* relocated LM Studio install doesn't desync between the catalog UI and the
* code path that actually talks to the server.
*/
function getBaseUrl() {
return config.baseUrl
}
/**
* Update configuration
* @param {Object} newConfig - New configuration
* @returns {Object} - Updated configuration
*/
function updateConfig(newConfig) {
if (newConfig.baseUrl) {
config.baseUrl = newConfig.baseUrl
isAvailable = null // Force recheck
lastCheckAt = null
}
if (newConfig.timeout) {
config.timeout = newConfig.timeout
}
if (newConfig.defaultThinkingModel) {
config.defaultThinkingModel = newConfig.defaultThinkingModel
}
return { ...config }
}
/**
* Reset cached state
*/
function resetCache() {
isAvailable = null
loadedModels = null
lastLoadedModelsError = null
availableModels = null
lastListError = null
lastCheckAt = null
}
// LM Studio can be installed as a desktop app without the `lms` CLI on PATH and
// without the local server running — mirror scripts/setup-llm.js so status
// doesn't report "Not installed" (and offer a redundant install) in that case.
//
// macOS has one fixed bundle path, so it is checked directly. Windows and Linux
// do NOT: the installer lets the user place the app anywhere, including a
// non-system drive, so there is no fixed path to probe.
// What every platform DOES have is the app's own home directory — LM Studio
// creates `~/.lmstudio` (or the older `~/.cache/lm-studio`) on first launch, and
// `getModelsDir()` above already treats those two as its authoritative roots.
// Keying off them makes a Windows install with the server stopped and `lms`
// unbootstrapped read as installed instead of prompting to install it again.
const LM_STUDIO_HOME_DIRS = ['.lmstudio', '.cache/lm-studio']
function isAppInstalled() {
if (process.platform === 'darwin' && existsSync('/Applications/LM Studio.app')) return true
return LM_STUDIO_HOME_DIRS.some((dir) => existsSync(join(homedir(), ...dir.split('/'))))
}
/**
* Run one `lms` subcommand, resolving to `{ success }` or `{ success: false, error }`.
*
* Every `lms` call shares the same three failure shapes — the CLI is not on
* PATH, the process timed out, or it exited non-zero — and the same rule for
* pulling a human line out of the result (last line of stderr, else stdout).
* They live here once so the "run \`lms bootstrap\`" instruction and the
* error-line rule cannot be fixed for one caller and not the other.
*
* Resolves rather than throws (mirrors `controlOllamaServer`) so a route can
* turn a refusal into a 502, and a measurement can record it, with the reason
* intact.
*
* @param {string[]} args
* @param {{ timeoutMs: number }} options
*/
async function runLms(args, { timeoutMs }) {
const binary = findCommandOnPath('lms')
if (!binary) {
return {
success: false,
error: "LM Studio's `lms` CLI is not on PortOS's PATH. Open LM Studio once and run `lms bootstrap`, or use the app's Developer tab."
}
}
// Name the SUBCOMMAND in the error, not the whole argv — a flag's value
// ("8192") is not a flag and would otherwise land in the message as if it were
// part of the command the user should run.
const flagAt = args.findIndex((a) => a.startsWith('-'))
const label = `\`lms ${args.slice(0, flagAt === -1 ? args.length : flagAt).join(' ')}\``
const result = await bufferedSpawn(binary, args, { timeoutMs, shell: false })
resetCache()
if (result.timedOut) return { success: false, error: `${label} timed out after ${Math.round(timeoutMs / 1000)}s` }
if (!result.success) {
const detail = result.error?.message || String(result.stderr || result.stdout || '').trim().split(/\r?\n/).pop()
return { success: false, error: detail || `${label} exited with code ${result.code}` }
}
return { success: true }
}
/**
* Start or stop LM Studio's local OpenAI-compatible server via its own `lms` CLI.
*
* `lms` is LM Studio's CLI shim, installed by `lms bootstrap` from the app.
* Without it there is no headless way to drive the server, and pretending
* otherwise would report a success the user cannot see — so that case is a
* refusal naming the one command that fixes it.
*
* Resolves rather than throws (mirrors `controlOllamaServer`) so the route can
* turn a refusal into a 502 with the reason intact.
*
* @param {'start'|'stop'} action
*/
async function controlServer(action) {
if (action !== 'start' && action !== 'stop') {
return { success: false, error: `Unknown LM Studio action: ${action}` }
}
const result = await runLms(['server', action], { timeoutMs: LMS_CONTROL_TIMEOUT_MS })
if (!result.success) return result
console.log(`📦 LM Studio server ${action === 'start' ? 'started' : 'stopped'}`)
return { success: true }
}
// ---- local-disk introspection / import (migrate fast-path) ------------------
const dirExists = (p) => stat(p).then((s) => s.isDirectory()).catch(() => false)
/** LM Studio's models root — first of the two known locations that exists. */
async function getModelsDir() {
const candidates = [
process.env.LM_STUDIO_MODELS_DIR,
join(homedir(), '.lmstudio', 'models'),
join(homedir(), '.cache', 'lm-studio', 'models')
].filter(Boolean)
for (const dir of candidates) {
if (await dirExists(dir)) return dir
}
return candidates[1] // sensible default even if it doesn't exist yet
}
/**
* Enumerate the exact `<publisher>/<repo>` folders LM Studio can delete.
* This is disk-native so a stopped daemon does not erase downloaded inventory,
* and one row always represents the whole repo folder (including every quant).
*/
async function listStoredModels() {
const modelsDir = await getModelsDir()
const root = await stat(modelsDir).then((entry) => entry.isDirectory(), (err) => {
if (err?.code === 'ENOENT') return false
throw err
})
if (!root) return []
const publishers = (await readdir(modelsDir, { withFileTypes: true }))
.filter((entry) => entry.isDirectory())
const nested = await Promise.all(publishers.map(async (publisher) => {
const publisherDir = join(modelsDir, publisher.name)
const repos = (await readdir(publisherDir, { withFileTypes: true }))
.filter((entry) => entry.isDirectory())
return Promise.all(repos.map(async (repo) => {
const id = `${publisher.name}/${repo.name}`
return {
id,
publisher: publisher.name,
name: repo.name,
size: await dirSize(join(publisherDir, repo.name), { strict: true }),
}
}))
}))
return nested.flat().sort((a, b) => b.size - a.size)
}
const normalizeRepoKey = (s) => String(s || '')
.split('/').pop()
.trim()
.toLowerCase()
.replace(/[-.]gguf$/i, '')
.replace(/[-.]mlx[-.].*$/i, '')
function modelIdsReferToSameRepo(left, right) {
const leftKey = normalizeRepoKey(left)
const rightKey = normalizeRepoKey(right)
return Boolean(leftKey && rightKey && leftKey === rightKey)
}
// `lms get` skips files that already exist, so a publisher replacing a GGUF in
// place (Unsloth Dynamic 3.0, etc.) never lands unless we evict first. Strip the
// backend-specific install wrapper down to the on-disk `<publisher>/<repo>` id.
function repoIdFromInstallId(modelId) {
return String(modelId || '')
.trim()
.replace(/^https?:\/\/huggingface\.co\//i, '')
.replace(/^hf\.co\//i, '')
.replace(/@[^/@]+$/, '')
.replace(/:([^:/]+)$/, '')
}
function quantFromInstallId(modelId) {
const s = String(modelId || '').trim()
const at = s.match(/@([^/@]+)$/)
if (at) return at[1]
const colon = s.match(/:([^:/]+)$/)
return colon ? colon[1] : null
}
function trailingGgufQuant(filename) {
const stem = String(filename || '').split('/').pop()
.replace(/\.gguf$/i, '')
.replace(/-\d{5}-of-\d{5}$/i, '')
// Same trailing-token rule as huggingFaceCatalog.quantFromFilename: UD-Q4_K_M
// and Q4_K_M are distinct, so a suffix match would evict the wrong file.
const match = stem.match(/(?:^|[-_.])((?:UD-)?(?:IQ\d(?:_[A-Z0-9]+)*|Q\d(?:_[A-Z0-9]+)*|BF16|F16))$/i)
return match?.[1] || null
}
function ggufMatchesQuant(filename, quant) {
const parsed = trailingGgufQuant(filename)
return parsed != null && parsed.toLowerCase() === String(quant).toLowerCase()
}
/**
* Remove on-disk LM Studio files so a subsequent `lms get` actually re-fetches
* them. A quant-tagged id (`repo@UD-Q4_K_M` / `hf.co/repo:UD-Q4_K_M`) evicts
* only matching GGUFs and leaves sibling quants alone. A bare repo id fails —
* we cannot name the file to replace, and wiping the folder would drop sibling
* quants. Missing files are success (`missing: true`) so a first-time install
* can share this path. Ambiguous ids refuse, same as deleteModel.
* @returns {Promise<{ success: boolean, modelId: string, missing?: boolean, error?: string }>}
*/
async function evictDownloadedQuant(modelId) {
const repoId = repoIdFromInstallId(modelId)
const quant = quantFromInstallId(modelId)
// A bare `publisher/repo` cannot name the GGUF to replace. Evicting the whole
// folder would drop sibling quants; leaving files in place makes `lms get`
// skip them and report a fake success. Callers must pass `repo@QUANT`.
if (!quant) {
return {
success: false,
error: 'Redownload needs a quantization tag (e.g. repo@UD-Q4_K_M). A bare repo id would skip existing GGUFs without replacing them.',
modelId
}
}
const modelsDir = await getModelsDir()
const matches = await findDeletableModelDirs(modelsDir, repoId)
if (matches === null) return { success: false, error: `Invalid model id "${modelId}".`, modelId }
if (matches.length === 0) return { success: true, missing: true, modelId }
if (matches.length > 1) {
return { success: false, error: `Ambiguous model id "${modelId}" matches ${matches.length} folders — redownload by exact "publisher/repo".`, modelId }
}
const dir = matches[0]
if (!isModelLeafDir(modelsDir, dir)) {
return { success: false, error: `Refusing to evict "${dir}" — not a model folder under ${modelsDir}.`, modelId }
}
if (await checkLMStudioAvailable()) await unloadModel(modelId).catch(() => {})
const files = await readdir(dir)
const targets = files.filter((name) => /\.gguf$/i.test(name) && !/mmproj/i.test(name) && ggufMatchesQuant(name, quant))
if (targets.length === 0) return { success: true, missing: true, modelId }
for (const name of targets) {
await rm(join(dir, name), { force: true })
}
resetCache()
console.log(`🗑️ LM Studio evicted ${targets.length} ${quant} file(s) for redownload: ${modelId}`)
return { success: true, modelId }
}
async function findModelDir(modelsDir, modelId) {
// Reject `.`/`..` traversal segments before joining — mirrors the stricter
// findDeletableModelDirs guard so the read path can't resolve outside the
// models tree either (trusted ids today, but defense-in-depth parity).
const segments = String(modelId || '').split('/').map((s) => s.trim()).filter(Boolean)
if (segments.some((s) => s === '.' || s === '..')) return null
const direct = join(modelsDir, ...segments)
if (await dirExists(direct)) return direct
const wanted = normalizeRepoKey(modelId)
if (!wanted) return null
const publishers = await readdir(modelsDir).catch(() => [])
for (const publisher of publishers) {
const publisherDir = join(modelsDir, publisher)
if (!(await dirExists(publisherDir))) continue
const repos = await readdir(publisherDir).catch(() => [])
const repo = repos.find((name) => normalizeRepoKey(name) === wanted)
if (repo) return join(publisherDir, repo)
}
return null
}
/**
* Locate an installed LM Studio model's files on disk (no network). The model
* id usually maps directly onto the `<publisher>/<repo>` folder, but LM Studio
* can report an API id that differs from the downloaded repo. Fall back to a
* normalized repo-name scan so `openai/gpt-oss-20b` can still resolve the local
* `lmstudio-community/gpt-oss-20b-GGUF` folder. MLX models (safetensors, no
* GGUF) return `{ isMlx: true, ggufPath: null }` so the caller routes them to
* re-pull instead of a (impossible) file copy.
* @returns {Promise<{ ggufPath: string|null, projectorPath: string|null, isMlx: boolean, isSharded: boolean }|null>}
*/
async function resolveLocalModel(modelId) {
const modelsDir = await getModelsDir()
const dir = await findModelDir(modelsDir, modelId)
if (!dir) return null
const files = await readdir(dir).catch(() => [])
if (dirIsMlx(files)) return { ggufPath: null, projectorPath: null, isMlx: true, isSharded: false }
const primary = selectPrimaryGguf(files)
if (!primary) return null
const projector = selectProjectorGguf(files)
return {
ggufPath: join(dir, primary),
projectorPath: projector ? join(dir, projector) : null,
isMlx: false,
isSharded: isShardedGguf(primary)
}
}
/**
* Resolve which on-disk folder(s) a delete request maps to. Unlike
* resolveLocalModel (a best-effort fuzzy first-match for READS), deletion is
* destructive (`rm -rf`), so this is deliberately stricter: it only ever returns
* concrete `<publisher>/<repo>` folders (LM Studio's invariant layout), rejects
* `.`/`..` traversal segments, and returns ALL normalized-scan matches so an
* ambiguous id (e.g. a `-GGUF` and a `-MLX-*` variant that normalize to the same
* key) can refuse instead of guessing the wrong one.
* @returns {Promise<string[]|null>} matched dirs, or null for an invalid id
*/
async function findDeletableModelDirs(modelsDir, modelId) {
const segments = String(modelId || '').split('/').map((s) => s.trim()).filter(Boolean)
if (segments.some((s) => s === '.' || s === '..')) return null
// Exact `<publisher>/<repo>` match takes precedence over the fuzzy scan.
if (segments.length === 2) {
const direct = join(modelsDir, segments[0], segments[1])
if (await dirExists(direct)) return [direct]
}
const wanted = normalizeRepoKey(modelId)
if (!wanted) return []
const matches = []
const publishers = await readdir(modelsDir).catch(() => [])
for (const publisher of publishers) {
const publisherDir = join(modelsDir, publisher)
if (!(await dirExists(publisherDir))) continue
const repos = await readdir(publisherDir).catch(() => [])
for (const name of repos) {
const repoDir = join(publisherDir, name)
if (normalizeRepoKey(name) === wanted && await dirExists(repoDir)) matches.push(repoDir)
}
}
return matches
}
/** True only when `dir` is a `<publisher>/<repo>` folder strictly under modelsDir. */
function isModelLeafDir(modelsDir, dir) {
const rel = relative(resolve(modelsDir), resolve(dir))
if (!rel || rel.startsWith('..') || isAbsolute(rel)) return false
return rel.split(sep).length === 2
}
/**
* Delete an installed LM Studio model. The `lms` CLI has no remove command, and
* LM Studio's REST API exposes no delete — so we remove the model's on-disk
* `<publisher>/<repo>/` folder directly and prune the publisher dir if empty.
* Best-effort unloads the model first so the running app isn't left serving
* files that no longer exist.
* @returns {Promise<{ success: boolean, modelId: string, error?: string }>}
*/
async function deleteModel(modelId) {
const modelsDir = await getModelsDir()
const matches = await findDeletableModelDirs(modelsDir, modelId)
if (matches === null) return { success: false, error: `Invalid model id "${modelId}".`, modelId }
if (matches.length === 0) {
return { success: false, error: `Model files not found on disk for "${modelId}".`, modelId }
}
if (matches.length > 1) {
return { success: false, error: `Ambiguous model id "${modelId}" matches ${matches.length} folders — delete by exact "publisher/repo".`, modelId }
}
const dir = matches[0]
// Defense-in-depth: never rm the models root, a publisher dir, or anything
// outside modelsDir — only a concrete `<publisher>/<repo>` leaf.
if (!isModelLeafDir(modelsDir, dir)) {
return { success: false, error: `Refusing to delete "${dir}" — not a model folder under ${modelsDir}.`, modelId }
}
// Unload first if the app is up and holding it (no-op/harmless otherwise).
if (await checkLMStudioAvailable()) await unloadModel(modelId).catch(() => {})
const removed = await rm(dir, { recursive: true, force: true })
.then(() => ({ ok: true })).catch((err) => ({ _err: err.message }))
resetCache() // disk may have changed even on a partial failure — re-list fresh
if (removed._err) return { success: false, error: removed._err, modelId }
// Prune the now-empty publisher dir (rmdir fails harmlessly if not empty).
await rmdir(join(dir, '..')).catch(() => {})
console.log(`🗑️ LM Studio deleted: ${modelId} (${dir})`)
cosEvents.emit('lmstudio:modelDeleted', { modelId })
invalidateModelObservation('loaded-models')
invalidateModelObservation('provider-readiness')
return { success: true, modelId }
}
/**
* Place a local GGUF into LM Studio's model tree (no download). LM Studio indexes
* loose GGUF files dropped under `<publisher>/<repo>/` on its next scan. In `link`
* mode the file is hardlinked (shared on disk with the source backend's copy);
* `copy` mode duplicates it. Link falls back to copy on any error (notably EXDEV
* across filesystems).
* @param {{ lmstudioId: string, ggufPath: string, projectorPath?: string|null, mode?: 'link'|'copy' }} args
* @returns {Promise<{ success: boolean, modelId?: string, linked?: boolean, error?: string }>}
*/
async function importModelFromGguf({ lmstudioId, ggufPath, projectorPath, mode = 'copy' }) {
const modelsDir = await getModelsDir()
const { publisher, repo } = lmStudioPublisherRepo(lmstudioId)
const destDir = join(modelsDir, publisher, repo)
// Report the actual on-disk id (sanitized) rather than the raw input, so
// migrate results / follow-up ops match where the file really landed.
const resolvedId = `${publisher}/${repo}`
// Hardlink when asked; fall back to copy on any link error. Returns whether
// the file ended up hardlinked (so the caller can report disk-sharing).
const place = async (src, dest) => {
if (mode === 'link' && await link(src, dest).then(() => true).catch(() => false)) return true
await copyFile(src, dest)
return false
}
let linked = false
const r = await ensureDir(destDir)
.then(async () => {
const base = basename(ggufPath)
const destName = /\.gguf$/i.test(base) ? base : `${repo}.gguf`
linked = await place(ggufPath, join(destDir, destName))
if (projectorPath) {
const projBase = basename(projectorPath)
await place(projectorPath, join(destDir, /\.gguf$/i.test(projBase) ? projBase : `${repo}-mmproj.gguf`))
}
})
.then(() => ({ ok: true }))
.catch((err) => ({ _err: err.message }))
if (r._err) return { success: false, error: r._err, modelId: resolvedId }
resetCache()
console.log(`📦 LM Studio import (${linked ? 'hardlink' : 'copy'}): ${resolvedId} ← ${ggufPath}`)
return { success: true, modelId: resolvedId, linked }
}
export {
checkLMStudioAvailable,
controlServer as controlLmStudioServer,
getLoadedModels,
getLoadedModelsAt,
getLastLoadedModelsError,
getAvailableModels,
downloadModel,
loadModel,
loadModelWithArgs,
unloadModel,
getRecommendedThinkingModel,
quickCompletion,
getEmbeddings,
getStatus,
getBaseUrl,
updateConfig,
resetCache,
isAppInstalled,
getLastListError,
getModelsDir,
listStoredModels,
modelIdsReferToSameRepo,
resolveLocalModel,
importModelFromGguf,
deleteModel,
evictDownloadedQuant,
DEFAULT_CONFIG
}