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 { localModelSafety } from '../lib/localModelSafety.js';
/**
* Local LLM orchestration — unifies the Ollama and LM Studio backends behind
* one shape so the UI can list / search / install / delete models, move models
* between backends, and pick the default backend. Both can be installed and
* running at the same time; the "default" is just which one PortOS routes local
* runs to.
*
* These two are the backends PortOS keeps a MODEL CATALOG for. They are not the
* only local servers it runs: `llamaServerManager.js` and `mtplxServerManager.js`
* own the two PM2-managed daemons (llama.cpp, MTPLX), and the LLMs page's
* "Local Runtime Servers" card starts and stops all four through one surface.
*
* The default backend is recorded in `.env` as `LLM_BACKEND` (parallel to
* `PGMODE`), so it survives restarts and is readable by the setup script. The
* matching aiToolkit provider (`ollama` / `lmstudio`) is enabled whenever a
* backend becomes the default (each provider stays independently enabled — we
* never disable the other, so both remain usable concurrently).
*
* The GGUF weights ARE portable between the two backends — only the on-disk
* layout differs (Ollama's content-addressed blob store vs LM Studio's plain
* file tree). So `migrateBackend` (bidirectional, independent of the default
* marker) hardlinks each model's GGUF across — sharing it on disk with zero
* extra space — or copies it, and re-pulls the cross-backend catalog equivalent
* only for models it can't share/copy (LM Studio MLX-format, sharded, or
* multimodal). See `server/lib/localLlmDisk.js` for the disk logic.
*/
import { execFile } from '../lib/childProcess.js';import { promisify } from 'util'
import { createWriteStream } from 'fs'
import { rename, rm, stat } from 'fs/promises'
import { join } from 'path'
import { tmpdir } from 'os'
import { fileURLToPath } from 'url'
import { pipeline } from 'stream/promises'
import { Readable, Transform } from 'stream'
import { ensureDir, pathExists, sleep } from '../lib/fileUtils.js'
import { readPortosEnvValue, upsertPortosEnvLine } from '../lib/portosEnv.js'
import { ServerError } from '../lib/errorHandler.js'
import { assessDownloadPreflight, diskInsufficientError, DOWNLOAD_VERDICTS } from '../lib/downloadPreflight.js'
import { compareSemver } from '../lib/versionUtils.js'
import { getCatalog, isBackend, mapModelToBackend, getOllamaImportSpec, catalogSizeBytes } from '../lib/localLlmCatalog.js'
import { sanitizeOllamaName } from '../lib/localLlmDisk.js'
import { recommendEditorialModel, isVisionModel, isVisionCapableCliProvider, isToolUseModel } from '../lib/localModelHeuristics.js'
import { captureSystemCapabilities, withHardwareCompatibility } from '../lib/systemCapabilities.js'
// Disk-only read of the measured assessments (`localModelAssessmentStore.js` has no
// path to a provider, so this cannot turn a status poll into an LLM call), and
// no import cycle: the store deliberately does not import this module.
import { getMeasuredFits } from './localModelAssessmentStore.js'
import { commandExists } from '../lib/commandExists.js'
import { runStreamingCommand } from '../lib/streamingSpawn.js'
import * as ollamaManager from './ollamaManager.js'
import * as lmStudioManager from './lmStudioManager.js'
import { localModelInventoryRow } from '../lib/modelInventory.js'
import { recordModelInstall, recordModelUninstall } from './modelManifest.js'
import { getProviderById, getAllProviders, updateProvider, refreshProviderModelsBatch, isOllamaBackedProvider } from './providers.js'
import { getSettings } from './settings.js'
const execFileAsync = promisify(execFile)
const DEFAULT_BACKEND = 'ollama'
// `lms get` blocks until the download finishes — generous but finite so a
// stalled connection (or an unexpected interactive prompt) can't hang the
// request forever. Large models on a slow link still fit comfortably.
const LMS_INSTALL_TIMEOUT_MS = 60 * 60 * 1000
// Backend (app/binary) installs go through a package manager and can pull a
// large cask; bound them so a wedged installer can't hang the request forever.
const BACKEND_INSTALL_TIMEOUT_MS = 30 * 60 * 1000
const DOWNLOAD_URL = { ollama: 'https://ollama.com/download', lmstudio: 'https://lmstudio.ai/download' }
// Which (platform, backend) pairs PortOS can install automatically. macOS uses
// Homebrew for both; Linux has an official Ollama script but no clean LM Studio
// CLI install; Windows is download-only.
function canAutoInstall(backend) {
if (process.platform === 'darwin') return true
if (process.platform === 'linux') return backend === 'ollama'
return false
}
// Which (platform, backend) pairs PortOS can UPGRADE in place. This is NOT the
// same as canAutoInstall: LM Studio installs via the Homebrew cask on macOS but
// self-updates through Sparkle, which PortOS can't drive (upgradeBackend returns
// manualUpdateRequired for it). Only Ollama has a PortOS-driven upgrade path
// (direct .app download on macOS, brew formula / official script otherwise).
function canAutoUpgrade(backend) {
if (backend !== 'ollama') return false
return process.platform === 'darwin' || process.platform === 'linux'
}
// aiToolkit provider id that pairs with each backend.
const PROVIDER_ID = { ollama: 'ollama', lmstudio: 'lmstudio' }
// Possible places `brew` registers each backend. Ollama has both a CLI-only
// formula and a separate macOS .app cask (`ollama-app`); LM Studio is cask-only.
const BREW_LOCATIONS = {
ollama: [
{ kind: 'formula', name: 'ollama', listArgs: ['list', '--formula', 'ollama'], upgradeArgs: ['upgrade', 'ollama'] },
{ kind: 'cask', name: 'ollama-app', listArgs: ['list', '--cask', 'ollama-app'], upgradeArgs: ['upgrade', '--cask', 'ollama-app'] }
],
lmstudio: [
{ kind: 'cask', name: 'lm-studio', listArgs: ['list', '--cask', 'lm-studio'], upgradeArgs: ['upgrade', '--cask', 'lm-studio'] }
]
}
// Macs that installed Ollama via the official .app downloader (not Homebrew)
// have /usr/local/bin/ollama (or /opt/homebrew/bin/ollama) as a symlink into
// the bundle, and the app's built-in updater handles upgrades. The .app for
// LM Studio works the same way. Detecting this lets us tell the user "open
// the app and use its own updater" instead of blindly running brew.
function macAppPath(backend) {
if (process.platform !== 'darwin') return null
return backend === 'ollama' ? '/Applications/Ollama.app' : '/Applications/LM Studio.app'
}
/**
* Where did this install of `backend` come from? Decides which upgrade path is
* actually safe to run — `brew upgrade ollama` against a `.app`-installed
* Ollama fails with "Error: ollama not installed" and surfaces as a useless
* "exited with code 1". Probes Homebrew first (formula then cask) and falls
* back to a macOS .app presence check.
*
* @returns {Promise<{ source: 'brew-formula'|'brew-cask'|'mac-app'|'unknown', upgradeArgs?: string[], packageName?: string }>}
*/
async function detectInstallSource(backend) {
if (process.platform === 'darwin' && await commandExists('brew', ['--version'])) {
for (const loc of BREW_LOCATIONS[backend] || []) {
if (await commandExists('brew', loc.listArgs)) {
return { source: loc.kind === 'cask' ? 'brew-cask' : 'brew-formula', upgradeArgs: loc.upgradeArgs, packageName: loc.name }
}
}
}
if (process.platform === 'darwin' && await pathExists(macAppPath(backend))) {
return { source: 'mac-app' }
}
return { source: 'unknown' }
}
// ---- active-backend marker (.env LLM_BACKEND) --------------------------------
/**
* The active local-LLM backend, read fresh from `.env` each call.
*
* **Precedence (settled in `server/lib/portosEnv.js`):** an exported
* `process.env` value is this run's decision and wins; the `.env` record is
* durable memory and loses. Validate each source before falling through.
*/
export function getBackend() {
const fromEnv = process.env.LLM_BACKEND
if (isBackend(fromEnv)) return fromEnv
const fromFile = readPortosEnvValue('LLM_BACKEND')
if (isBackend(fromFile)) return fromFile
return DEFAULT_BACKEND
}
async function writeBackend(backend) {
await upsertPortosEnvLine('LLM_BACKEND', backend)
}
/**
* Enable the aiToolkit provider that pairs with `backend`, so the active local
* backend is actually usable for runs. Best-effort: a misconfigured provider
* store must not crash a boot-time or migrate call.
*/
export async function ensureBackendProvider(backend) {
const id = PROVIDER_ID[backend]
if (!id) return
const provider = await getProviderById(id).catch(() => null)
if (!provider) return
const patch = {}
if (!provider.enabled) patch.enabled = true
// Ollama's OpenAI-compatible endpoint silently truncates to a ~4K context
// window unless a per-request num_ctx is sent. Editorial passes feed the
// whole manuscript (tens of thousands of tokens), so default a generous
// window (override with OLLAMA_NUM_CTX). LM Studio sets context at model
// load, so this only applies to Ollama.
if (backend === 'ollama' && !(Number(provider.numCtx) > 0)) {
patch.numCtx = Number(process.env.OLLAMA_NUM_CTX) || 32768
}
if (Object.keys(patch).length === 0) return
const ok = await updateProvider(id, patch)
.then(() => true)
.catch((err) => {
console.error(`⚠️ Failed to configure ${id} provider: ${err.message}`)
return false
})
if (ok) console.log(`🔌 Configured ${id} provider for local LLM backend (${Object.keys(patch).join(', ')})`)
}
// ---- backend capability probes ----------------------------------------------
// Whether Homebrew already has the backend's formula/cask installed. Used to
// recover from a non-zero `brew install` exit that nonetheless left the package
// on disk (post-install cleanup/hint failures exit 1 after a successful pour).
// `brew list` exits 0 only when the package is present, so its success IS the
// presence check — no output parsing needed.
async function brewPackageInstalled(backend) {
const args = backend === 'ollama'
? ['list', '--versions', 'ollama']
: ['list', '--cask', '--versions', 'lm-studio']
return commandExists('brew', args)
}
const manager = (backend) => (backend === 'ollama' ? ollamaManager : lmStudioManager)
// `runStreaming` moved to lib/streamingSpawn.js — the one-click local-runtime
// setup flow needs the same line-streamed spawn (see localRuntimeSetup.js).
const runStreaming = (cmd, args, onLine, timeoutMs = 0) => runStreamingCommand(cmd, args, onLine, { timeoutMs })
/**
* Install a backend's app/binary via the platform package manager (Homebrew on
* macOS for both; the official script for Ollama on Linux). Streams installer
* output via `onProgress`. Returns `{ success, note? }` — `note` tells the user
* how to start it (installing the binary doesn't start the server/app).
*
* @param {string} backend - 'ollama' | 'lmstudio'
* @param {(p: { event: string, message: string }) => void} [onProgress]
*/
export async function installBackend(backend, onProgress = () => {}) {
if (!isBackend(backend)) return { success: false, error: `Unknown backend: ${backend}` }
const emit = (message) => onProgress({ event: 'start', message })
const downloadHint = `Download it from ${DOWNLOAD_URL[backend]}.`
if (!canAutoInstall(backend)) {
return { success: false, error: `Automatic install isn't supported on this platform. ${downloadHint}` }
}
// Linux Ollama: official install script.
if (process.platform === 'linux') {
emit('Installing Ollama via the official install script…')
const r = await runStreaming('bash', [fileURLToPath(new URL('../../scripts/install-ollama.sh', import.meta.url))], emit, BACKEND_INSTALL_TIMEOUT_MS)
if (!r.success) return { success: false, error: `Ollama install failed: ${r.error}. ${downloadHint}` }
console.log('⬇️ Installed Ollama (linux script)')
return { success: true, backend }
}
// macOS: Homebrew (formula for Ollama, cask for LM Studio).
if (!(await commandExists('brew', ['--version']))) {
return { success: false, error: `Homebrew not found — install it from https://brew.sh first, or download the app: ${DOWNLOAD_URL[backend]}` }
}
const label = backend === 'ollama' ? 'Ollama' : 'LM Studio'
const args = backend === 'ollama' ? ['install', 'ollama'] : ['install', '--cask', 'lm-studio']
emit(`Installing ${label} via Homebrew (this can take a few minutes)…`)
const r = await runStreaming('brew', args, emit, BACKEND_INSTALL_TIMEOUT_MS)
if (!r.success) {
// `brew install` routinely exits non-zero AFTER a successful pour — a
// failed `brew cleanup`, a dependency's post-install hint, or env-hint
// noise (e.g. Ollama's new mlx/mlx-c deps) all bubble up as exit 1 even
// though the formula/cask is fully installed. Treat presence-on-disk as
// the source of truth: if `brew list` now sees it, the install worked.
if (await brewPackageInstalled(backend)) {
console.log(`🍺 ${label} already present after non-zero brew exit — treating as installed (${r.error})`)
emit(`${label} is installed (Homebrew reported a non-fatal warning).`)
} else {
return { success: false, error: `Homebrew install failed: ${r.error}` }
}
} else {
console.log(`🍺 Installed ${label} via Homebrew`)
}
if (backend === 'ollama') {
emit('Starting Ollama as a Homebrew service…')
const service = await ollamaManager.startPersistentService().catch((err) => ({ success: false, error: err.message }))
if (service.success) {
return {
success: true,
backend,
service: service.service,
note: 'Started as a Homebrew service; it will run in the background at login.'
}
}
const fallback = await ollamaManager.startServer().catch((err) => ({ success: false, error: err.message }))
return {
success: true,
backend,
service: service.service,
note: fallback.success
? `Installed, but Homebrew services could not register Ollama (${service.error}). Started it for this session.`
: `Installed, but PortOS could not start Ollama automatically (${service.error || fallback.error}). Use Run at Startup from this screen.`
}
}
return {
success: true,
backend,
note: 'Launch LM Studio, enable the local server (Developer tab), then run `lms bootstrap`.'
}
}
/**
* Fetch the latest Ollama GitHub release object (or null on any failure). The
* full object carries both the tag and the downloadable assets — getStatus's
* cached version lookup reads `tag_name`, the macOS upgrader reads `assets`.
*/
async function fetchLatestOllamaRelease(timeoutMs = 8000) {
return fetch('https://api.github.com/repos/ollama/ollama/releases/latest', {
headers: { 'User-Agent': 'PortOS', Accept: 'application/vnd.github+json' },
signal: AbortSignal.timeout(timeoutMs),
}).then((r) => (r.ok ? r.json() : null)).catch(() => null)
}
// Cache the latest Ollama release tag. GitHub's release API is slow and
// unauthenticated-rate-limited, and getStatus() runs on every Local LLMs tab
// load / refresh / action — so a steady-state UI must not hit GitHub each time.
// `version: null` is the not-fetched sentinel (distinct from a cached value); a
// successful fetch holds for LATEST_VERSION_TTL_MS, a failed one backs off for
// the shorter error TTL instead of poisoning the cache forever or hammering.
let latestOllamaCache = { version: null, fetchedAt: 0 }
const LATEST_VERSION_TTL_MS = 6 * 60 * 60 * 1000
const LATEST_VERSION_ERROR_TTL_MS = 10 * 60 * 1000
/**
* Latest published Ollama version (no leading `v`), or null if it can't be
* determined. Cached — see the TTL notes above. Used by getStatus to surface an
* "update available" affordance in the UI without a per-call network round-trip.
*/
export async function getLatestOllamaVersion() {
const age = Date.now() - latestOllamaCache.fetchedAt
if (latestOllamaCache.version && age < LATEST_VERSION_TTL_MS) return latestOllamaCache.version
// Recent failed lookup — back off rather than refetch on every status call.
if (!latestOllamaCache.version && latestOllamaCache.fetchedAt && age < LATEST_VERSION_ERROR_TTL_MS) return null
const release = await fetchLatestOllamaRelease(8000)
const version = release?.tag_name ? String(release.tag_name).replace(/^v/, '') : null
latestOllamaCache = { version, fetchedAt: Date.now() }
return version
}
/**
* Pre-upgrade Ollama version (best-effort — returns null if Ollama isn't running
* or isn't responding). Used to verify an upgrade actually moved the version.
*/
async function readOllamaVersion() {
const status = await ollamaManager.getStatus(true).catch(() => null)
return status?.version || null
}
/**
* Poll Ollama's /api/version until it responds (after a (re)start). Returns the
* version string when reachable, null on timeout.
*/
async function waitForOllamaVersion(timeoutMs = 30_000) {
const deadline = Date.now() + timeoutMs
while (Date.now() < deadline) {
const v = await readOllamaVersion()
if (v) return v
await sleep(500)
}
return null
}
/**
* Download + install the latest Ollama macOS .app in place. This is the only
* reliable path on macOS — `brew upgrade ollama` either has a behind-by-weeks
* formula, OR the running server is the .app binary (because `/usr/local/bin/
* ollama` symlinks into the bundle) so even a successful brew upgrade leaves
* the wrong binary serving. Pulls the latest `Ollama-darwin.zip` from the
* official GitHub releases, replaces `/Applications/Ollama.app` on disk, strips
* quarantine, and relaunches.
*
* The .app keeps its own user prefs / model store (`~/.ollama`) so this is
* non-destructive; only the bundle itself gets swapped.
*
* The swap is STAGED: the existing bundle is renamed to `<app>.portos-old-<ts>`
* and only removed once the replacement is verifiably a directory at the real
* path, so any failure downstream rolls back to the working install instead of
* leaving the machine with no Ollama at all. It then verifies the RUNNING
* version advanced, because a second install ahead of the bundle on PATH can
* keep serving the old binary past a perfectly successful swap.
*/
const DOWNLOAD_HEADER_TIMEOUT_MS = 30_000
const DOWNLOAD_IDLE_TIMEOUT_MS = 60_000
/**
* Download `url` to `destPath` with stall detection instead of a total
* deadline (which would abort slow-but-progressing links): the response headers
* must arrive within `headerMs`, then every body chunk resets an idle timer that
* aborts after `idleMs` without bytes. `signal` aborts early (client gone).
* Resolves `{ error }` on any failure, `{}` on success — never throws.
*/
async function downloadWithStallGuard(url, destPath, signal, { headerMs = DOWNLOAD_HEADER_TIMEOUT_MS, idleMs = DOWNLOAD_IDLE_TIMEOUT_MS } = {}) {
const ac = new AbortController()
let stall = null
let timer = null
const arm = (ms, message) => {
clearTimeout(timer)
timer = setTimeout(() => { stall = message; ac.abort() }, ms)
}
const onExternalAbort = () => ac.abort()
if (signal?.aborted) return { error: 'Download cancelled.' }
signal?.addEventListener('abort', onExternalAbort, { once: true })
try {
arm(headerMs, `Download stalled — no response from the server within ${Math.round(headerMs / 1000)} s. Check the connection and retry.`)
const dl = await fetch(url, { signal: ac.signal })
if (!dl?.ok || !dl.body) return { error: `Download failed: ${dl?.statusText || 'no response body'}` }
const idleMessage = `Download stalled — no data for ${Math.round(idleMs / 1000)} s. Check the connection and retry.`
arm(idleMs, idleMessage)
const touch = new Transform({ transform(chunk, _enc, cb) { arm(idleMs, idleMessage); cb(null, chunk) } })
await pipeline(Readable.fromWeb(dl.body), touch, createWriteStream(destPath), { signal: ac.signal })
return {}
} catch (err) {
if (stall) return { error: stall }
if (signal?.aborted) return { error: 'Download cancelled.' }
return { error: `Download failed: ${err.message}` }
} finally {
clearTimeout(timer)
signal?.removeEventListener('abort', onExternalAbort)
}
}
async function upgradeOllamaMacApp(emit, signal) {
const appPath = '/Applications/Ollama.app'
emit('Looking up the latest Ollama release on GitHub…')
// Uncached on purpose — an explicit upgrade needs the live release (and its
// download assets), not the status-path's 6h-cached tag.
const release = await fetchLatestOllamaRelease(15000)
if (!release) return { success: false, error: 'Could not reach GitHub to look up the latest Ollama release.' }
const asset = (release.assets || []).find((a) => a.name === 'Ollama-darwin.zip')
if (!asset?.browser_download_url) {
return { success: false, error: `Latest Ollama release ${release.tag_name} has no Ollama-darwin.zip asset — try downloading from ${DOWNLOAD_URL.ollama}.` }
}
const before = await readOllamaVersion()
const tagClean = String(release.tag_name || '').replace(/^v/, '')
if (before && tagClean && before === tagClean) {
return { success: true, backend: 'ollama', note: `Ollama is already at ${before} (latest).`, alreadyLatest: true }
}
const tmpDir = join(tmpdir(), `portos-ollama-upgrade-${Date.now()}`)
const zipPath = join(tmpDir, 'Ollama-darwin.zip')
await ensureDir(tmpDir)
emit(`Downloading Ollama ${release.tag_name} (${Math.round(asset.size / 1024 / 1024)} MB)…`)
const dl = await downloadWithStallGuard(asset.browser_download_url, zipPath, signal)
if (dl.error) {
await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
return { success: false, error: dl.error }
}
emit('Stopping running Ollama…')
await ollamaManager.stopServer().catch(() => null)
// Force-kill stragglers — the menu-bar .app launches `ollama serve` as a child
// that doesn't always exit cleanly via the service stop above.
await runStreaming('pkill', ['-x', 'Ollama'], () => {}, 10_000).catch(() => null)
await runStreaming('pkill', ['-x', 'ollama'], () => {}, 10_000).catch(() => null)
// Brief settle so the OS releases the bundle before we replace it.
await sleep(1500)
emit('Extracting…')
const unzip = await runStreaming('unzip', ['-q', '-o', zipPath, '-d', tmpDir], emit, 5 * 60 * 1000)
if (!unzip.success) {
await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
return { success: false, error: `Extract failed: ${unzip.error}` }
}
const extractedApp = join(tmpDir, 'Ollama.app')
if (!(await pathExists(extractedApp))) {
await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
return { success: false, error: 'Extracted archive did not contain Ollama.app — release layout may have changed.' }
}
emit('Installing /Applications/Ollama.app…')
// Stage-and-swap: move the existing bundle ASIDE rather than deleting it. `mv`
// still can't merge with an existing directory on macOS, so the destination has
// to be cleared first — but an `rm` there means a failed `mv` (timeout, ENOSPC,
// an MDM/SIP policy on /Applications) leaves the user with no Ollama at all.
// The aside copy is the rollback. Its failure is NOT swallowed either: a
// straggler holding the bundle open makes `rename` fail, and continuing would
// let `mv` nest the new bundle INSIDE the surviving old one and exit 0.
const asidePath = `${appPath}.portos-old-${Date.now()}`
const asideErr = await rename(appPath, asidePath).then(() => null, (err) => err)
if (asideErr && asideErr.code !== 'ENOENT') {
await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
return { success: false, error: `Could not move the existing ${appPath} aside (${asideErr.message}), so the upgrade was not attempted and your current Ollama install is untouched. Quit Ollama completely and retry, or install the official app from ${DOWNLOAD_URL.ollama}.` }
}
// ENOENT above just means nothing was installed here — there is no rollback copy.
const movedAside = !asideErr
const move = await runStreaming('mv', [extractedApp, appPath], emit, 60_000)
// The destination was verifiably absent, so a nested Ollama.app/Ollama.app is
// impossible — assert the installed path really is a bundle directory anyway,
// since everything downstream (quarantine strip, launch) trusts it.
const installed = move.success && await stat(appPath).then((s) => s.isDirectory(), () => false)
if (!installed) {
// Whatever is at appPath now (nothing, a half-copied cross-device `mv`, or a
// non-directory) is not a usable bundle, and it is never the user's working
// install — that was renamed aside. Clear it unconditionally so the restore
// can't fail on a non-empty destination, which is the exact data loss this
// staging exists to prevent.
await rm(appPath, { recursive: true, force: true }).catch(() => {})
const restoreErr = movedAside ? await rename(asidePath, appPath).then(() => null, (err) => err) : null
const restored = !movedAside
? ''
: restoreErr
? ` Your previous Ollama install could NOT be restored (${restoreErr.message}) — it is at ${asidePath}, move it back to ${appPath} by hand.`
: ' Your previous Ollama install has been restored.'
// Keep tmpDir: the downloaded bundle is the user's only way to finish by hand.
const leftover = (await pathExists(extractedApp)) ? ` The downloaded bundle is still at ${extractedApp} if you want to move it into place yourself.` : ''
const why = move.success ? `${appPath} is not a directory after the move` : move.error
return { success: false, error: `Could not install ${appPath}: ${why}.${restored}${leftover} PortOS may not have permission to write to /Applications — try running the official installer manually.` }
}
if (movedAside) await rm(asidePath, { recursive: true, force: true }).catch(() => {})
// Strip quarantine so Gatekeeper doesn't refuse to launch the freshly-downloaded bundle.
await runStreaming('xattr', ['-dr', 'com.apple.quarantine', appPath], () => {}, 30_000).catch(() => null)
await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
emit('Starting Ollama…')
const launch = await runStreaming('open', ['-g', '-a', appPath], () => {}, 30_000)
if (!launch.success) {
return {
success: true,
backend: 'ollama',
note: `Upgraded to ${release.tag_name}, but couldn't auto-launch Ollama (${launch.error}). Open Ollama.app manually.`
}
}
const after = await waitForOllamaVersion(30_000)
if (!after) {
return {
success: true,
backend: 'ollama',
note: `Upgraded to ${release.tag_name}, but Ollama did not come back online within 30s. Open Ollama.app if it isn't already running.`
}
}
// Verify the version actually moved — same check the Homebrew path below runs,
// and for the same reason: a second Ollama install ahead of the bundle on PATH
// can keep serving the old binary, so a swapped .app is not proof of upgrade.
if ((tagClean && compareSemver(tagClean, after) > 0) || (!tagClean && (!before || compareSemver(after, before) <= 0))) {
return {
success: false,
backend: 'ollama',
error: `Installed ${appPath} (${release.tag_name}), but the Ollama serving requests is still ${after}${before ? ` (was ${before})` : ''}. Another Ollama installation may be ahead of the app bundle on your PATH. Quit Ollama completely, relaunch it from ${appPath}, or install the official app from ${DOWNLOAD_URL.ollama}.`
}
}
console.log(`⬆️ Upgraded Ollama: ${before || 'unknown'} → ${after} (${release.tag_name})`)
return { success: true, backend: 'ollama', note: `Ollama ${before ? `${before} → ` : ''}${after}. The new binary is now serving requests.` }
}
/**
* Upgrade an already-installed backend in place. Used when a model pull returns
* Ollama's 412 "requires a newer version of Ollama" error.
*
* macOS Ollama is special: even when Homebrew has a recent enough formula, the
* .app binary is what `ollama serve` actually runs (via the symlink at
* `/usr/local/bin/ollama` → `/Applications/Ollama.app/Contents/Resources/ollama`),
* so a brew-only upgrade leaves the OLD binary serving. So we prefer a direct
* download + .app replacement on macOS whenever the .app is present. Other paths:
*
* • macOS LM Studio cask → `brew upgrade --cask lm-studio`
* • macOS Ollama brew formula (no .app) → `brew upgrade ollama`
* • Linux Ollama → re-run the official install script (idempotent upgrade)
*
* @param {string} backend - 'ollama' | 'lmstudio'
* @param {(p: { event: string, message: string }) => void} [onProgress]
* @param {AbortSignal} [signal] - aborts an in-flight Ollama.app download (client disconnect)
*/
export async function upgradeBackend(backend, onProgress = () => {}, signal) {
if (!isBackend(backend)) return { success: false, error: `Unknown backend: ${backend}` }
const emit = (message) => onProgress({ event: 'start', message })
const label = backend === 'ollama' ? 'Ollama' : 'LM Studio'
const downloadHint = `Download the latest version from ${DOWNLOAD_URL[backend]}.`
// Linux Ollama: the official install script is also the upgrade path.
if (process.platform === 'linux' && backend === 'ollama') {
emit('Upgrading Ollama via the official install script…')
const r = await runStreaming('bash', [fileURLToPath(new URL('../../scripts/install-ollama.sh', import.meta.url))], emit, BACKEND_INSTALL_TIMEOUT_MS)
if (!r.success) {
console.error(`⚠️ Ollama upgrade (linux script) failed: ${r.error}`)
return { success: false, error: `Ollama upgrade failed: ${r.error}. ${downloadHint}` }
}
console.log('⬆️ Upgraded Ollama (linux script)')
return { success: true, backend }
}
if (process.platform !== 'darwin') {
return { success: false, error: `Automatic upgrade isn't supported on this platform. ${downloadHint}` }
}
// macOS Ollama with a .app present — direct download is the only path that
// actually replaces the binary that's serving requests.
if (backend === 'ollama' && await pathExists(macAppPath('ollama'))) {
return upgradeOllamaMacApp(emit, signal)
}
// Everything else: route through Homebrew.
const source = await detectInstallSource(backend)
if (source.source === 'mac-app') {
// LM Studio .app — Sparkle handles updates; brew doesn't know about it.
return {
success: false,
manualUpdateRequired: true,
error: `LM Studio was installed from the official .app, which has its own updater — PortOS can't drive it from here. Open LM Studio → Settings → "Check for updates", or ${downloadHint.toLowerCase()}`
}
}
if (source.source === 'unknown') {
return { success: false, error: `Couldn't identify how ${label} was installed. ${downloadHint}` }
}
if (!(await commandExists('brew', ['--version']))) {
return { success: false, error: `Homebrew not found — install it from https://brew.sh first, or ${downloadHint.toLowerCase()}` }
}
const before = backend === 'ollama' ? await readOllamaVersion() : null
const target = backend === 'ollama' ? await getLatestOllamaVersion() : null
emit('Refreshing Homebrew package metadata…')
const refresh = await runStreaming('brew', ['update'], emit, BACKEND_INSTALL_TIMEOUT_MS)
if (!refresh.success) return { success: false, error: `Homebrew refresh failed: ${refresh.error}` }
emit(`Upgrading ${label} via Homebrew (${source.packageName}) — this can take a few minutes…`)
const r = await runStreaming('brew', source.upgradeArgs, emit, BACKEND_INSTALL_TIMEOUT_MS)
if (!r.success) {
console.error(`⚠️ ${label} upgrade via brew ${source.upgradeArgs.join(' ')} failed: ${r.error}`)
return { success: false, error: `Homebrew upgrade failed: ${r.error}` }
}
console.log(`🍺 Homebrew upgrade command completed for ${label} (${source.source})`)
if (backend === 'ollama') {
const stop = await ollamaManager.stopPersistentService().catch((err) => ({ success: false, error: err.message }))
const restart = await ollamaManager.startPersistentService().catch((err) => ({ success: false, error: err.message }))
if (!restart.success) {
return { success: false, backend, error: `Could not verify the Ollama upgrade because its service could not restart (${restart.error || stop.error}). Restart it from the Local LLMs tab.` }
}
const after = await waitForOllamaVersion()
if (!after) return { success: false, backend, error: 'Could not verify the Ollama upgrade: the service did not come back online within 30s.' }
if ((target && compareSemver(target, after) > 0) || (!target && (!before || compareSemver(after, before) <= 0))) {
return {
success: false,
backend,
error: `Ollama is still running ${after}${target ? `; the available release is ${target}` : '; no newer running version was verified'}. Homebrew may not have packaged the latest release yet, or another Ollama installation may be serving requests. Retry when Homebrew catches up, or install the official app from ${DOWNLOAD_URL.ollama}.`
}
}
return { success: true, backend, note: `Ollama ${before ? `${before} → ` : ''}${after}. The verified binary is now serving requests.` }
}
return { success: true, backend, note: 'Restart LM Studio so the new binary is loaded.' }
}
/**
* Start/stop the Ollama HTTP server from the UI. LM Studio is app-controlled,
* so keep this intentionally narrow instead of inventing unreliable app-launch
* behavior for every platform.
*/
export async function controlOllamaServer(action) {
if (action === 'start') return ollamaManager.startServer()
if (action === 'stop') return ollamaManager.stopServer()
if (action === 'enable') return ollamaManager.startPersistentService()
if (action === 'disable') return ollamaManager.stopPersistentService()
return { success: false, error: `Unknown Ollama action: ${action}` }
}
// Ollama's /api/show reports capabilities in its own vocabulary
// (completion/tools/vision/embedding/thinking/insert). Map the ones that have
// a home onto the badge vocabulary the Models catalog cards already render
// (CAPABILITY_META in LocalLlmTab.jsx: chat/code/reasoning/vision/embeddings/
// tools/audio) so installed models can show the same icons. Only capabilities
// the daemon actually reported are surfaced — nothing is guessed here.
const OLLAMA_CAPABILITY_BADGES = {
completion: 'chat',
tools: 'tools',
vision: 'vision',
embedding: 'embeddings',
thinking: 'reasoning'
}
/**
* Ollama's reported capabilities → the badge vocabulary.
*
* `null` for a NON-ARRAY input, which is what `/api/tags` gives: that listing
* carries no capability flags at all, so nothing was reported and nothing is
* known. Returning `[]` there would collapse "not probed" into "claims
* nothing" — the sentinel mistake root AGENTS.md forbids — which rendered an
* empty badge row on the install catalog and made every capability test look
* inapplicable. `/api/show` is what actually knows; an EMPTY array from it is a
* real answer and stays `[]`.
*/
export function ollamaBadgeCapabilities(rawCapabilities) {
if (!Array.isArray(rawCapabilities)) return null
return rawCapabilities
.map((c) => OLLAMA_CAPABILITY_BADGES[String(c).toLowerCase()])
.filter(Boolean)
}
// LM Studio's native model list tags each model's `type` (`llm` / `vlm` /
// `embeddings`) — authoritative for chat/vision/embeddings. It reports no
// tool-calling flag, so fall back to the shared id heuristic for `tools`.
function lmStudioBadgeCapabilities(m) {
const type = m?.type ? String(m.type).toLowerCase() : null
const caps = type === 'embeddings' ? ['embeddings'] : ['chat']
if (type === 'vlm') caps.push('vision')
if (type !== 'embeddings' && isToolUseModel(m?.id)) caps.push('tools')
return caps
}
/**
* Add catalog-derived hardware metadata to a live model when PortOS knows its
* identity. Unknown/custom models stay fail-open with an empty requirement set.
*/
function annotateInstalledModel(backend, rawModel, normalizedModel, capabilities) {
const catalogEntry = getCatalog(backend, [rawModel.id]).find((entry) => entry.installed)
return withHardwareCompatibility(
{ ...normalizedModel, ...localModelSafety(catalogEntry?.repository || rawModel.id) },
capabilities,
catalogEntry?.hardwareRequirements || rawModel.hardwareRequirements,
)
}
/** Normalize each backend's installed-model shape into one card shape. */
function normalizeModels(backend, models, capabilities = captureSystemCapabilities()) {
if (backend === 'ollama') {
return models.map((m) => annotateInstalledModel(backend, m, {
id: m.id, name: m.name, size: m.size ?? null,
params: m.params || null, quantization: m.quantization || null, family: m.family || null,
contextLength: m.contextLength ?? null,
// Ollama's /api/tags doesn't tag vision capability, but /api/show does —
// when the model has been enriched with a `capabilities` array (status
// path, or the listVisionModels enrichment below) prefer it; otherwise
// fall back to the id heuristic. Passing the object lets a vision-capable
// MoE like `qwen3.6:35b` (no `vl`/`vision` token in its id) resolve true.
vision: isVisionModel(Array.isArray(m.capabilities) ? { id: m.id, capabilities: m.capabilities } : m.id),
capabilities: ollamaBadgeCapabilities(m.capabilities)
}, capabilities))
}
return models.map((m) => annotateInstalledModel(backend, m, {
id: m.id, name: m.id, size: null,
params: null, quantization: m.quantization || null, family: m.arch || null,
contextLength: m.maxContextLength ?? null,
// LM Studio's native model list tags vision models `type: 'vlm'` — prefer
// that over the id regex.
vision: isVisionModel(m),
capabilities: lmStudioBadgeCapabilities(m)
}, capabilities))
}
/**
* Installed models for a backend, normalized.
* @param {boolean} [forceRefresh] - bypass the Ollama installed-models cache.
* Default false so the catalog-overlay path (hit on every debounced keystroke)
* reuses the cache instead of spamming `/api/tags`. The cache is busted on
* pull/delete, so it stays accurate; force only for explicit refresh/migrate.
*/
export async function listModels(backend, forceRefresh = false) {
if (!isBackend(backend)) return []
const raw = backend === 'ollama'
? await ollamaManager.getInstalledModels(forceRefresh)
: await lmStudioManager.getAvailableModels(forceRefresh)
return normalizeModels(backend, raw)
}
/**
* `listModels` plus the sentinel that tells "no models installed" apart from
* "the list could not be read".
*
* Both managers cache an EMPTY array on a failed read rather than throwing, so
* `[]` alone is ambiguous — and collapsing an unreadable list into "this
* backend has no models" is exactly the failure the sentinel rule in AGENTS.md
* forbids. **`error` is the authoritative signal, not `models`**: a failed read
* comes back as `{ models: [], error: '<why>' }`, because that empty array is
* genuinely what the manager is holding. A caller that must not treat a
* transient daemon outage as an empty catalog checks `error` first and falls
* back to whatever it had before.
*
* @param {string} backend - 'ollama' | 'lmstudio'
* @returns {Promise<{ models: Array|null, error: string|null }>} A non-null
* `error` means the listing was not readable, whatever `models` holds;
* `models: null` additionally means there was no list to hold at all (the
* call threw, or the backend name is unknown).
*/
export async function listManagedBackendModels(backend, forceRefresh = false) {
if (!isBackend(backend)) return { models: null, error: `unknown backend '${backend}'` }
const models = await listModels(backend, forceRefresh).catch((err) => ({ error: err?.message || 'model list failed' }))
if (!Array.isArray(models)) return { models: null, error: models.error }
let error = backend === 'ollama'
? ollamaManager.getLastInstalledModelsError()
: lmStudioManager.getLastListError()
if (backend === 'lmstudio' && !error) {
const status = await lmStudioManager.getStatus().catch(() => null)
if (!status?.available) {
error = 'LM Studio is unavailable'
}
}
return { models, error: error || null }
}
/**
* Combined status for both backends plus the active marker.
*/
export async function getStatus() {
const [ollamaStatus, ollamaCli, lmStudioStatus, lmsCli, lmStudioModels, latestOllamaVersion, settings, measuredOllama, measuredLmStudio] = await Promise.all([
ollamaManager.getStatus(true),
commandExists('ollama', ['--version']),
lmStudioManager.getStatus(),
commandExists('lms', ['version']),
// forceRefresh: status/refresh path bypasses the list cache.
listModels('lmstudio', true).catch(() => []),
// Cached (6h) — never blocks the steady-state UI on a GitHub round-trip.
getLatestOllamaVersion().catch(() => null),
getSettings(),
// Measured evidence, so the editorial pick can prefer a model that PROVABLY
// runs here over one whose name merely looks right. Disk-only; a status poll
// must never trigger a measurement.
getMeasuredFits('ollama').catch(() => ({})),
getMeasuredFits('lmstudio').catch(() => ({}))
])
const ollamaModels = normalizeModels('ollama', ollamaStatus.models)
const lmStudioRecommendation = recommendEditorialModel(lmStudioModels, { measured: measuredLmStudio })
// An update is "available" only when we know BOTH the installed version (Ollama
// must be running for /api/version to answer) and the latest, and latest is
// newer. canUpgrade (canAutoUpgrade) gates the in-app updater to the platforms
// where upgradeBackend can actually drive an Ollama upgrade.
const ollamaUpdateAvailable = Boolean(
ollamaStatus.version && latestOllamaVersion && compareSemver(latestOllamaVersion, ollamaStatus.version) > 0
)
return {
backend: getBackend(),
ollama: {
disabled: Boolean(settings.localLlm?.ollama?.disabled),
installed: ollamaCli || ollamaStatus.available,
available: ollamaStatus.available,
version: ollamaStatus.version,
latestVersion: latestOllamaVersion,
updateAvailable: ollamaUpdateAvailable,
canUpgrade: canAutoUpgrade('ollama'),
baseUrl: ollamaStatus.baseUrl,
modelCount: ollamaStatus.modelCount,
models: ollamaModels,
contextLength: ollamaStatus.contextLength,
modelsError: ollamaManager.getLastInstalledModelsError(),
// Best installed model for editorial review/editing, surfaced so the
// manuscript editor can suggest it (and warn against the embedding model).
recommendations: { editorial: recommendEditorialModel(ollamaModels, { measured: measuredOllama }) },
canControl: ollamaCli || ollamaStatus.available,
service: ollamaStatus.service,
canAutoInstall: canAutoInstall('ollama'),
downloadUrl: DOWNLOAD_URL.ollama
},
lmstudio: {
disabled: Boolean(settings.localLlm?.lmstudio?.disabled),
// macOS app bundle counts as installed even with no CLI / server stopped.
installed: lmsCli || lmStudioStatus.available || lmStudioManager.isAppInstalled(),
available: lmStudioStatus.available,
hasCli: lmsCli,
baseUrl: lmStudioStatus.baseUrl,
modelCount: lmStudioModels.length,
models: lmStudioModels,
recommendations: { editorial: lmStudioRecommendation },
// Non-null when LM Studio answered the availability probe but the model
// list call failed — lets the UI tell "0 models" from "couldn't list".
modelsError: lmStudioManager.getLastListError(),
canAutoInstall: canAutoInstall('lmstudio'),
downloadUrl: DOWNLOAD_URL.lmstudio
}
}
}
/**
* Vision-capable installed models across both local backends, tagged with the
* aiToolkit provider id (`ollama` / `lmstudio`) that serves them, PLUS
* vision-capable CLI providers (codex / claude-code) whose model reads images
* via a file. Powers the caption-model picker and the captioner's
* auto-resolution of a default vision model. Each entry:
* `{ providerId, backend, id, name, vision: true }`.
*/
export async function listVisionModels() {
// Cache-first for both backends (the model-list caches are busted on
// install/delete, so they stay accurate) — the picker doesn't need a forced
// round-trip on every dataset-page load.
const [ollama, lmstudio] = await Promise.all([
listModels('ollama').catch(() => []),
listModels('lmstudio').catch(() => [])
])
// Ollama's /api/tags carries no vision flag, so the normalized `vision` above
// is id-regex only — it misses vision-capable models whose id has no
// `vl`/`vision` token (e.g. the `qwen3.6:35b` MoE). For each not already
// matched, consult /api/show capabilities (cached per model) so they surface
// in the picker. Models the id heuristic already caught skip the round-trip.
const ollamaVision = await Promise.all(ollama.map(async (m) => {
if (m.vision) return m
const capabilities = await ollamaManager.getModelCapabilities(m.id).catch(() => null)
return { ...m, vision: isVisionModel({ id: m.id, capabilities }) }
}))
const tag = (backend, models) => models
.filter((m) => m.vision)
.map((m) => ({ providerId: PROVIDER_ID[backend], backend, id: m.id, name: m.name || m.id, vision: true }))
return [
...tag('ollama', ollamaVision),
...tag('lmstudio', lmstudio),
...await listVisionCliModels(),
]
}
/**
* Tool-use (function-calling) capable installed models across both local
* backends, tagged with the aiToolkit provider id (`ollama` / `lmstudio`) that
* serves them. Each entry: `{ providerId, backend, id, name, toolUse: true }`.
*
* Powers the AGENT model pickers' tool-use annotation, whose client-side
* `isToolUseModel` id regex is a positive allowlist that goes stale every time a
* new function-calling family ships — so a genuinely tool-capable model whose id
* the regex doesn't know (`phi4-mini`, a newer function-calling Gemma build) got
* flagged "⚠ no known tool use" while the Local LLMs tab's "Agents" badge, which
* reads these same authoritative capabilities, said otherwise.
*
* Deliberately NOT a mirror of `listVisionModels`' CLI expansion: a CLI provider
* has no enumerable per-model capability, and its tool-calling comes from the CLI
* harness rather than the model, so there is nothing authoritative to report.
* Callers union this with the id regex, so an unlisted model still falls back to
* the regex rather than being asserted incapable.
*/
export async function listToolUseModels() {
// Cache-first for both backends — same rationale as listVisionModels: the
// model-list caches are busted on install/delete, so they stay accurate.
const [ollama, lmstudio] = await Promise.all([
listModels('ollama').catch(() => []),
listModels('lmstudio').catch(() => [])
])
// Ollama's /api/tags carries no capability flags at all, so `normalizeModels`
// could only regex-guess. /api/show reports an authoritative `tools`
// capability (cached per model), which is what makes this endpoint worth more
// than the client's own regex — consult it for every model. Unlike the vision
// path there is no id short-circuit: an id-regex hit is exactly the case the
// client can already decide for itself, so skipping the round-trip would leave
// this list adding nothing beyond what the caller already knows.
const ollamaToolUse = await Promise.all(ollama.map(async (m) => {
const capabilities = await ollamaManager.getModelCapabilities(m.id).catch(() => null)
// `isToolUseModel` treats a NON-EMPTY capabilities array as authoritative in
// both directions; null/empty (probe failed or daemon didn't report) falls
// back to the id regex.
return { ...m, toolUse: isToolUseModel({ id: m.id, capabilities }) }
}))
// LM Studio reports no tool-calling flag, so `lmStudioBadgeCapabilities`
// already resolved `tools` from the shared id heuristic — read that rather
// than re-deriving it, so this endpoint and the Local LLMs tab's badges can
// never disagree about the same model.
const lmStudioToolUse = lmstudio.map((m) => ({
...m,
toolUse: (m.capabilities || []).includes('tools')
}))
const tag = (backend, models) => models
.filter((m) => m.toolUse)
.map((m) => ({ providerId: PROVIDER_ID[backend], backend, id: m.id, name: m.name || m.id, toolUse: true }))
return [
...tag('ollama', ollamaToolUse),
...tag('lmstudio', lmStudioToolUse),
]
}
/**
* Vision-capable CLI providers (codex / claude-code), expanded to one entry per
* configured model so the caption picker can offer e.g. "codex / gpt-5" or
* "claude-code / claude-opus-5". A disabled provider is skipped. Each entry
* mirrors the local-backend shape with `backend: 'cli'`. Best-effort: a load
* failure yields no CLI entries rather than breaking the whole picker.
*/
async function listVisionCliModels() {
const { providers } = await getAllProviders().catch(() => ({ providers: [] }))
const entries = []
for (const p of providers || []) {
if (p.enabled === false) continue
if (!isVisionCapableCliProvider(p)) continue
const models = Array.isArray(p.models) && p.models.length ? p.models : [p.defaultModel].filter(Boolean)
for (const id of models) {
entries.push({ providerId: p.id, backend: 'cli', id, name: `${p.name || p.id} / ${id}`, vision: true })
}
}
return entries
}
// ---- install / delete --------------------------------------------------------
/**
* Push a live model-list refresh to every provider backed by the Ollama daemon,
* so an install/delete on the Local LLMs tab is immediately reflected in every
* provider/model picker (task scheduler, pipeline stages, etc.) without the user
* having to find and click "Refresh Models" on the AI Providers page. Fire-and-
* forget from the caller's perspective — the install/delete response shouldn't
* wait on an extra round-trip to Ollama per matching provider. Best-effort per
* provider — one failing refresh (e.g. Ollama briefly unreachable mid-pull)
* must not block the others.
*
* The grouping, probing and persistence all live in the toolkit's
* `refreshProviderModelsBatch`: it dedupes providers that share a daemon AND a
* probe shape so `/api/tags` + the per-model `/api/show` capability sweep runs
* once rather than once per provider, and it collapses the whole fan-out into a
* SINGLE `providers.json` write instead of one full-file save per provider.
* All this function adds is the host-side log line — one per group, because
* every member of a group failed identically against the same daemon and N
* copies of one error is noise, not information.
*/
function refreshOllamaBackedProviders() {
getAllProviders().then(({ providers }) => {
const targets = (providers || []).filter(isOllamaBackedProvider)
if (targets.length === 0) return null
return refreshProviderModelsBatch(targets.map((p) => p.id)).then((groups) => {
for (const group of groups) {
if (group.status === 'failed') {
console.error(`⚠️ Failed to refresh models for ${group.ids.length} Ollama-backed provider(s) via ${group.leadId}: ${group.error?.message}`)
} else if (group.status === 'missing') {
// The lead was deleted between listing the providers and probing it.
// Say so — silently dropping the group would leave its siblings stale
// with no trace of why.
console.error(`⚠️ Skipped refreshing ${group.ids.length} Ollama-backed provider(s): lead provider ${group.leadId} no longer exists`)
}
}
})
}).catch((err) => {
console.error(`⚠️ Failed to list providers for post-install Ollama refresh: ${err.message}`)
})
}
/**
* One-line label for an install progress frame, or null for a frame with nothing
* to say. Shared by every consumer of `installModel`'s `onProgress` (the install
* route and `migrateBackend`) so a new frame kind — `retrying`, `finalizing`, or
* whatever comes next — reaches all of them without another per-call-site edit.
* @param {{ status?: string, percent?: number|null }} [p]
* @returns {string|null}
*/
export function describeInstallProgress(p) {
if (p?.percent != null) return `${p.status || 'downloading'} ${p.percent}%`
return p?.status || null
}
/**
* Install (pull/download) a model on a backend.
* @param {(p) => void} [onProgress] - streaming progress (Ollama only)
* @param {{ force?: boolean }} [opts] - when true, evict existing LM Studio
* files first so `lms get` actually re-fetches in-place GGUF replacements.
* Ollama's pull already re-checks the registry digest, so force is a no-op there.
*/
async function localInstallDest(backend) {
return backend === 'ollama' ? ollamaManager.getModelsDir() : lmStudioManager.getModelsDir()
}
// A "Redownload" of a model already on disk transfers little to nothing in
// practice — Ollama's pull re-checks the registry digest and dedupes
// unchanged layers, and LM Studio's own `lms get` skips files already
// present — so sizing it against the FULL catalog size (like a genuine
// net-new install) can refuse a redownload the real transfer would have
// completed in seconds. `expectedBytes: 0` matches this feature's existing
// "can't size it, don't block it" convention for that case.
async function expectedInstallBytes(backend, modelId) {
const installed = await listModels(backend).catch(() => [])
if (installed.some((m) => m.id === modelId)) return 0
return catalogSizeBytes(backend, modelId)
}
export async function previewInstallModel(backend, modelId) {
if (!isBackend(backend)) {
throw new ServerError(`Unknown backend: ${backend}`, { status: 400 })
}
const destPath = await localInstallDest(backend)
const installed = await listModels(backend).catch(() => [])
const alreadyDownloaded = installed.some((m) => m.id === modelId)
// 0 for a free-text/uncurated model id (e.g. a bare Ollama tag the user
// typed) — the preflight already treats that as "unknown, never refuse."
const preflight = await assessDownloadPreflight({
destPath,
expectedBytes: alreadyDownloaded ? 0 : catalogSizeBytes(backend, modelId),
})
return {
kind: 'install',
backend,
modelId,
...preflight,
destPath,
alreadyDownloaded,
}
}
async function performInstallModel(backend, modelId, onProgress, { force = false } = {}) {
if (!isBackend(backend)) return { success: false, error: `Unknown backend: ${backend}` }
// Resolve-not-throw: every other failure this function can hit (unknown
// backend, OLLAMA_OUTDATED, ...) resolves `{ success: false, error }` —
// migrateBackend's per-model loop is written against that contract with no
// try/catch of its own, so a throw here would abort the whole migration on
// model N instead of recording one more `status: 'failed'` row and moving on.
const preflight = await assessDownloadPreflight({
destPath: await localInstallDest(backend),
expectedBytes: await expectedInstallBytes(backend, modelId),
})
if (preflight.verdict === DOWNLOAD_VERDICTS.INSUFFICIENT) {
return { success: false, error: diskInsufficientError(preflight).message, code: 'DISK_INSUFFICIENT' }
}
if (backend === 'ollama') {
const importSpec = getOllamaImportSpec(modelId)
const result = importSpec
? await ollamaManager.importModelFromHfSafetensors(importSpec, onProgress)
: await ollamaManager.pullModel(modelId, onProgress)
if (result.success) refreshOllamaBackedProviders()
return result
}
// `lms get` skips files already on disk. A force redownload has to evict the
// matching GGUF (or the whole repo folder) first, or the "new" weights never land.
if (force) {
const evicted = await lmStudioManager.evictDownloadedQuant(modelId)
if (!evicted.success) return { success: false, error: evicted.error, modelId }
}
// LM Studio: prefer the `lms` CLI (real, blocking download), fall back to the
// REST hook.
if (await commandExists('lms', ['version'])) {
// `lms get` streams substantial progress to stdout; the default 1MB
// maxBuffer overflows and surfaces as a false install failure (see
// voice/bootstrap.js which uses the same 64MB ceiling for `lms get`).
const r = await execFileAsync('lms', ['get', '-y', modelId], { timeout: LMS_INSTALL_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 })
.then(() => ({ ok: true })).catch((err) => ({ _err: err.stderr || err.message }))
if (r._err) return { success: false, error: r._err, modelId }
lmStudioManager.resetCache()
return { success: true, modelId }
}
// REST fallback only *queues* the download — LM Studio pulls it in the
// background and the call returns immediately. Flag it `pending` so callers
// don't claim the model is installed before it actually is.
const r = await lmStudioManager.downloadModel(modelId)
return r.success ? { ...r, pending: true } : r
}
/**
* Delete an installed model from a backend.
*/
async function performDeleteModel(backend, modelId) {
if (!isBackend(backend)) return { success: false, error: `Unknown backend: ${backend}` }
if (backend === 'ollama') {
const loaded = await ollamaManager.getLoadedModels()
if (ollamaManager.getLastLoadedModelsError()) {
return { success: false, error: 'Could not verify Ollama model residency; refresh the backend before deleting.', modelId }
}
if (loaded.some((model) => model.id === modelId || model.name === modelId)) {
return { success: false, error: 'Model is loaded; unload it before deleting.', modelId }
}
const result = await ollamaManager.deleteModel(modelId)
if (result.success) refreshOllamaBackedProviders()
return result
}
const loaded = await lmStudioManager.getLoadedModels(true)
if (lmStudioManager.getLastLoadedModelsError()) {
return { success: false, error: 'Could not verify LM Studio model residency; refresh the backend before deleting.', modelId }
}
if (loaded.some((model) => lmStudioManager.modelIdsReferToSameRepo(model.id, modelId))) {
return { success: false, error: 'Model is loaded; unload it before deleting.', modelId }
}
// LM Studio has no delete in its REST API and the `lms` CLI has no `rm`
// command — deleteModel removes the model's on-disk folder directly.
return lmStudioManager.deleteModel(modelId)
}
// Both backends' installs and deletes have several success and failure exits
// each (preflight refusal, a forced evict that failed, the `lms` CLI vs the REST
// fallback, a residency check that could not be verified). Recording the manifest
// at every one of those is how a later exit gets added without one — so the two
// public entry points wrap a single internal function and record once, off its
// one contractual `{ success }` result.
//
// A `pending` LM Studio install is deliberately NOT recorded: the REST fallback
// only QUEUES the download, so the weights are not on disk yet and the next
// reconcile is what adopts them.
/**
* Install a model into a backend, recording it in the model manifest on success.
*
* @param {string} backend
* @param {string} modelId
* @param {Function} [onProgress]
* @param {Object} [options]
* @param {boolean} [options.force] Re-download even when the weights are present
* @returns {Promise<Object>} `{ success, ... }` — never throws (see performInstallModel)
*/
export async function installModel(backend, modelId, onProgress, options = {}) {
const result = await performInstallModel(backend, modelId, onProgress, options)
if (result?.success && !result.pending) {
// The row comes from the shared builder the SCAN uses, so a tracked model and
// a scanned one carry the same size semantics, cleanup warning and delete
// action. Size is left unset: neither backend reports the installed bytes, and
// the next reconcile measures it off disk.
await recordModelInstall({
...localModelInventoryRow({ backend, modelId }),
source: 'download',
})
}
return result
}
/**
* Delete an installed model from a backend, clearing it from the model manifest.
*
* @param {string} backend
* @param {string} modelId
* @returns {Promise<Object>} `{ success, ... }`
*/
export async function deleteModel(backend, modelId) {
const result = await performDeleteModel(backend, modelId)
if (result?.success) await recordModelUninstall({ backend, key: modelId })
return result
}
// ---- switch / migrate --------------------------------------------------------
/**
* Flip the active backend without moving any models.
*/
export async function switchBackend(to) {
if (!isBackend(to)) return { success: false, error: `Unknown backend: ${to}` }
await writeBackend(to)
await ensureBackendProvider(to)
console.log(`🔀 Active local LLM backend → ${to}`)
return { success: true, backend: to }
}
/**
* Try to provision a single source model on the target WITHOUT downloading, by
* copying its GGUF weights across the two on-disk layouts (the underlying GGUF
* is the same; only Ollama's content-addressed blob store vs LM Studio's plain
* file tree differ). Returns a per-model result on success, or `null` to tell
* the caller to fall back to a re-pull (no local file, MLX-only, multi-file
* sharded, a multimodal projector we can't carry into Ollama, or a copy error).
*/
async function tryLocalImport(to, model, targetId, resolved, mode, onProgress) {
// Fast path requires a single-file GGUF on disk. MLX (no GGUF) and sharded
// models fall through; a separate projector can be copied to LM Studio but
// not cleanly imported into Ollama, so that case re-pulls too.
if (!resolved?.ggufPath || resolved.isSharded) return null
if (to === 'ollama' && resolved.projectorPath) return null
const name = to === 'ollama'
? sanitizeOllamaName(targetId || model.id)
: (targetId || `imported/${model.id.split('/').pop()}`)
const verb = mode === 'link' ? 'Linking' : 'Copying'
onProgress({ event: 'start', message: `${verb} ${name} onto ${to} (no download)…` })
const r = to === 'ollama'
? await ollamaManager.importModelFromGguf({ name, ggufPath: resolved.ggufPath, mode })
: await lmStudioManager.importModelFromGguf({ lmstudioId: name, ggufPath: resolved.ggufPath, projectorPath: resolved.projectorPath, mode })
if (!r.success) {
onProgress({ event: 'start', message: `Local import of ${model.id} failed (${r.error}); re-pulling…` })
return null
}
// `linked` reflects what actually happened on disk — link mode falls back to a
// copy across filesystems, so report the real outcome, not the requested mode.
onProgress({ event: 'start', message: `${r.linked ? 'Linked' : 'Copied'} ${r.modelId} onto ${to} (no download)` })
// A migration's fast path never goes through `installModel` — it moves the GGUF
// itself — so it records its own arrival, or the target backend's newest models
// would be the ones the manifest does not know about.
await recordModelInstall({
...localModelInventoryRow({ backend: to, modelId: r.modelId }),
source: 'import',
})
return { source: model.id, target: r.modelId, status: 'imported', linked: !!r.linked, reason: null }
}
/** The other of the two backends (migration source for a given target). */
const otherBackend = (backend) => (backend === 'ollama' ? 'lmstudio' : 'ollama')
/**
* Provision the OTHER backend's installed models onto `to`. This is bidirectional
* (source is simply the opposite backend, NOT the active one) and decoupled from
* the default-backend marker — it never flips it. Use `switchBackend` ("Set as
* Default") for routing. The underlying GGUF weights ARE portable across backends:
*
* • `mode: 'link'` (default) — hardlink the GGUF so both backends share one file
* on disk (zero extra space), falling back to a copy where a hardlink isn't
* possible (different filesystem).
* • `mode: 'copy'` — make an independent duplicate.
*
* Either way there's no re-download for portable single-file GGUFs; models that
* can't be shared/copied (LM Studio MLX-format, sharded, or with a separate
* projector when targeting Ollama) fall back to re-pulling the catalog
* equivalent. Per-model results are reported; an individual failure doesn't abort.
*
* @param {string} to - target backend
* @param {{ mode?: 'link'|'copy', onProgress?: (p: { event: string, message: string }) => void }} [opts]
*/
export async function migrateBackend(to, { mode = 'link', onProgress = () => {} } = {}) {
if (!isBackend(to)) return { success: false, error: `Unknown backend: ${to}` }
if (mode !== 'link' && mode !== 'copy') mode = 'link'
const from = otherBackend(to)
onProgress({ event: 'start', message: `Reading models installed on ${from}…` })
const { models: sourceModels, error } = await listManagedBackendModels(from, true)
if (error) {
onProgress({ event: 'error', message: error })
return { success: false, error }
}
if (!sourceModels || sourceModels.length === 0) {
const message = `No models installed on ${from} to move.`
onProgress({ event: 'complete', message })
return { success: true, from, to, mode, results: [] }
}
const results = []
for (const model of sourceModels) {
const { targetId, exact } = mapModelToBackend(from, model.id, to)
const resolved = await manager(from).resolveLocalModel(model.id).catch(() => null)
// 1) Fast path — link/copy the GGUF locally (no download) when we can.
const imported = await tryLocalImport(to, model, targetId, resolved, mode, onProgress)
if (imported) { results.push(imported); continue }
// 2) Fallback — re-pull the catalog equivalent.
if (!targetId) {
const reason = resolved?.isMlx ? 'MLX format — no GGUF equivalent to re-pull' : 'no known equivalent'
results.push({ source: model.id, target: null, status: 'skipped', reason })
onProgress({ event: 'start', message: `Skipped ${model.id} — ${reason}` })
continue
}
onProgress({ event: 'start', message: `Downloading ${targetId} on ${to}${exact ? '' : ' (best-effort)'}…` })
const r = await installModel(to, targetId, (p) => {
const label = describeInstallProgress(p)
if (label) onProgress({ event: 'start', message: `Pulling ${targetId}: ${label}` })
})
// `pending` (LM Studio REST fallback) means the download was queued, not
// finished — don't report it as a completed install.
const status = r.success ? (r.pending ? 'started' : 'installed') : 'failed'
results.push({ source: model.id, target: targetId, status, reason: r.error })
}
const linked = results.filter((r) => r.status === 'imported' && r.linked).length
const copied = results.filter((r) => r.status === 'imported' && !r.linked).length
const installed = results.filter((r) => r.status === 'installed').length
const started = results.filter((r) => r.status === 'started').length
const failed = results.filter((r) => r.status === 'failed').length
const skipped = results.filter((r) => r.status === 'skipped').length
const succeeded = linked + copied + installed + started
// Surface a hard failure when nothing could be provisioned (e.g. target not
// installed/running). All-skipped is fine — the target works, we just had no
// equivalent to move.
if (failed > 0 && succeeded === 0) {
const error = `Migration ${from} → ${to} failed — no models could be provisioned (is ${to} installed and running?).`
onProgress({ event: 'error', message: error })
console.error(`⚠️ Migration ${from} → ${to} aborted: ${failed} failed, 0 succeeded`)
return { success: false, from, to, mode, error, results }
}
const parts = [
linked ? `${linked} linked (shared on disk)` : null,
copied ? `${copied} copied` : null,
installed ? `${installed} downloaded` : null,
started ? `${started} downloading` : null,
failed ? `${failed} failed` : null,
skipped ? `${skipped} skipped` : null
].filter(Boolean)
onProgress({ event: 'complete', message: `Moved ${from} → ${to} — ${parts.join(', ') || 'no models to move'}` })
console.log(`🔀 Moved models ${from} → ${to} (${linked} linked, ${copied} copied, ${installed} downloaded, ${failed} failed)`)
return { success: true, from, to, mode, results }
}