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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { pinPlatform } from '../lib/testHelper.js';
const probe = vi.hoisted(() => ({ probeOpenAiModels: vi.fn() }));
vi.mock('../lib/openAiModelsProbe.js', () => probe);
const pathLookup = vi.hoisted(() => ({
findCommandOnPath: vi.fn(() => null),
safeChildProcessEnv: (extra = {}) => ({ ...extra }),
safeChildProcessOptions: (opts = {}) => opts,
}));
vi.mock('../lib/processEnv.js', () => pathLookup);
const streaming = vi.hoisted(() => ({ runStreamingCommand: vi.fn(async () => ({ success: true })) }));
vi.mock('../lib/streamingSpawn.js', () => streaming);
const commands = vi.hoisted(() => ({ commandExists: vi.fn(async () => true) }));
vi.mock('../lib/commandExists.js', () => commands);
// The three managers this module delegates to for the runtimes PortOS already
// knew how to install. Mocked so the suite never touches Homebrew or a daemon.
const llama = vi.hoisted(() => ({ installLlamaServer: vi.fn(async () => ({ success: true })) }));
vi.mock('./llamaServerManager.js', () => llama);
const localLlm = vi.hoisted(() => ({
installBackend: vi.fn(async () => ({ success: true })),
controlOllamaServer: vi.fn(async () => ({ success: true })),
}));
vi.mock('./localLlm.js', () => localLlm);
vi.mock('./lmStudioManager.js', () => ({ isAppInstalled: () => false }));
// MTPLX's model cache — this module reads it directly (the checklist's refusals
// and its `pull-start` download button are phrased for THIS surface, so the
// reading happens here rather than inside the manager).
const mtplxCache = vi.hoisted(() => ({ listMtplxCachedModels: vi.fn() }));
// PARTIAL mock: only the subprocess call is faked. `describeMtplxCache` and
// `pickMtplxCachedModel` are pure classifiers of that output, and stubbing them
// would let a wrong reading of a real cache listing pass here.
vi.mock('../lib/mtplxModels.js', async (importOriginal) => ({ ...(await importOriginal()), ...mtplxCache }));
// The install and the launch itself are delegated to the PM2-backed manager
// (`portos-mtplx`) — its Homebrew/pip install and `mtplx serve` launch line are
// covered in `mtplxServerManager.test.js`. This suite asserts the delegation.
const mtplx = vi.hoisted(() => ({
installMtplx: vi.fn(async () => ({ success: true })),
startMtplxServer: vi.fn(async () => ({ success: true, endpoint: 'http://127.0.0.1:8000/v1' })),
MTPLX_UNSUPPORTED_REASON: 'MTPLX runs only on macOS with Apple Silicon.',
}));
vi.mock('./mtplxServerManager.js', () => mtplx);
// The vLLM compose project's clone / build / prepare / start. Mocked so this
// suite asserts what the REGISTRY does — offers the action, refuses the wrong
// one, delegates — while the manager's own suite covers what it does on disk.
const vllmManager = vi.hoisted(() => ({
readVllmQwenSetupState: vi.fn(async () => 'ready'),
provisionVllmQwenProject: vi.fn(async () => ({ success: true })),
startVllmQwenProject: vi.fn(async () => ({ success: true })),
}));
vi.mock('./vllmQwenManager.js', () => vllmManager);
// The SGLang project on disk, and the CUDA probe its start row consults BEFORE
// docker — mocked so no assertion depends on the developer's actual GPU.
// PARTIAL: the env-var name and directory leaf the placement loop is keyed on
// are constants this row imports, and the two `.env` helpers must be stubbed so
// no assertion here can be answered by (or write into) the developer's install.
const sglangProject = vi.hoisted(() => ({
inspectSglangQwenProject: vi.fn(),
sglangStartBlockedReason: vi.fn(() => null),
sglangProjectDirIsSettled: vi.fn(() => false),
recordSglangProjectDir: vi.fn(async () => {}),
}));
vi.mock('../lib/sglangQwenProject.js', async (importOriginal) => ({ ...(await importOriginal()), ...sglangProject }));
// `wsl.exe`. Mocked because the real one answers on a developer's Windows box —
// the placement tests would then assert against THAT machine's distro.
const wsl = vi.hoisted(() => ({ detectWslProjectDir: vi.fn() }));
vi.mock('../lib/wslDistro.js', async (importOriginal) => ({ ...(await importOriginal()), ...wsl }));
const cuda = vi.hoisted(() => ({ getCudaCapability: vi.fn() }));
vi.mock('../lib/cudaCapability.js', () => cuda);
import { describeRuntimeSetup, readRuntimeWeights, runLocalRuntimeSetup, SETUP_ACTIONS, SETUP_RUNTIME_KINDS } from './localRuntimeSetup.js';
const unreachable = { reachable: false, models: null, error: 'ECONNREFUSED' };
const reachable = (models = ['mtplx']) => ({ reachable: true, models, error: null });
const cachedModels = (models) => ({ models, error: null });
const preparedSglangProject = { dir: '/home/example/sglang-qwen38', hasProject: true, composeFile: 'docker-compose.yml', hasWeights: true, weightsRoot: '/home/example/sglang-qwen38/hf-cache/hub' };
/** What `wsl.exe` says on a Windows host with an ordinary distro. */
const SGLANG_WSL_DIR = '\\\\wsl.localhost\\Ubuntu\\home\\example\\sglang-qwen38';
beforeEach(() => {
sglangProject.inspectSglangQwenProject.mockResolvedValue(preparedSglangProject);
sglangProject.sglangStartBlockedReason.mockReturnValue(null);
sglangProject.sglangProjectDirIsSettled.mockImplementation(() => Boolean(process.env.SGLANG_QWEN_PROJECT_DIR));
wsl.detectWslProjectDir.mockResolvedValue({ dir: SGLANG_WSL_DIR, distro: 'Ubuntu', home: '\\\\wsl.localhost\\Ubuntu\\home\\example' });
// Default to the verified Hopper cell; the hardware cases override it.
cuda.getCudaCapability.mockResolvedValue({ status: 'available', gpus: [{ name: 'NVIDIA H200', computeCap: '9.0', vramGb: 141 }] });
// Implementations AND return values (not just call records) survive
// `clearAllMocks`, so a probe implementation left over from an earlier test
// would drive this module's poll loop for its full timeout.
probe.probeOpenAiModels.mockReset();
vllmManager.readVllmQwenSetupState.mockResolvedValue('ready');
vllmManager.provisionVllmQwenProject.mockResolvedValue({ success: true });
vllmManager.startVllmQwenProject.mockResolvedValue({ success: true });
mtplxCache.listMtplxCachedModels.mockResolvedValue(cachedModels([{ repo_id: 'Example/MTP-Model', validation: { ok: true } }]));
mtplx.installMtplx.mockResolvedValue({ success: true });
mtplx.startMtplxServer.mockResolvedValue({ success: true, endpoint: 'http://127.0.0.1:8000/v1' });
});
afterEach(() => {
vi.clearAllMocks();
pathLookup.findCommandOnPath.mockReturnValue(null);
commands.commandExists.mockResolvedValue(true);
streaming.runStreamingCommand.mockResolvedValue({ success: true });
// The placement loop writes this on a Windows host so the rest of the run
// resolves the detected directory; it must not leak into the next test.
delete process.env.SGLANG_QWEN_PROJECT_DIR;
});
describe('describeRuntimeSetup', () => {
it('covers every runtime the readiness checklist can report', () => {
expect([...SETUP_RUNTIME_KINDS].sort()).toEqual(['llama', 'lmstudio', 'mtplx', 'ollama', 'sglang', 'slotstream', 'vllm']);
});
it('offers install AND start when nothing is there yet', () => {
const restore = pinPlatform('darwin');
expect(describeRuntimeSetup('mtplx', { installed: false, running: false })).toEqual({
runtime: 'mtplx',
label: 'MTPLX',
action: 'install-start',
actionLabel: 'Install & start MTPLX',
provisions: false,
blockedReason: null,
});
restore();
});
it('offers only a start once the runtime is installed', () => {
const restore = pinPlatform('darwin');
expect(describeRuntimeSetup('mtplx', { installed: true, running: false })).toMatchObject({
action: 'start',
actionLabel: 'Start MTPLX',
});
restore();
});
it('offers the DOWNLOAD, not a start, when the installed runtime has no weights', () => {
// The catch-22 this exists to end: "installed ✓ / not responding — press
// Start", where Start could only ever answer "no model weights are cached".
const restore = pinPlatform('darwin');
for (const weights of ['empty', 'partial']) {
expect(describeRuntimeSetup('mtplx', { installed: true, running: false, weights })).toMatchObject({
action: 'pull-start',
actionLabel: 'Download the default model & start MTPLX',
});
}
restore();
});
it('keeps a plain start when the cache is READY or unreadable', () => {
const restore = pinPlatform('darwin');
// Weights are already there — nothing to download.
expect(describeRuntimeSetup('mtplx', { installed: true, running: false, weights: 'ready' })).toMatchObject({ action: 'start' });
// Unreadable is not empty: a start that would have worked must not be
// turned into a multi-gigabyte download.
expect(describeRuntimeSetup('mtplx', { installed: true, running: false, weights: 'unknown' })).toMatchObject({ action: 'start' });
restore();
});
it('never offers a download for a runtime with no pull step', () => {
// Ollama's weights come from the Models → LLMs page, so an empty cache
// there must not conjure a button this module cannot honour.
expect(describeRuntimeSetup('ollama', { installed: true, running: false, weights: 'empty' }))
.toMatchObject({ action: 'start' });
});
it('offers nothing once the daemon is installed and up — the model is the user\'s choice', () => {
const restore = pinPlatform('darwin');
// A running daemon serving the wrong alias is the remaining unmet check,
// and PortOS will not pick (or download) a checkpoint for the user.
expect(describeRuntimeSetup('mtplx', { installed: true, running: true })).toBeNull();
restore();
});
it('names the reason instead of a button on an unsupported host', () => {
const restore = pinPlatform('linux');
expect(describeRuntimeSetup('mtplx', { installed: false, running: false })).toMatchObject({
action: null,
blockedReason: expect.stringMatching(/only on macOS/),
});
restore();
});
it('stops at the install for llama.cpp, which cannot start without weights', () => {
// `start: null` — llama-server takes a required model path, so an installed
// but stopped llama.cpp gets no button at all.
expect(describeRuntimeSetup('llama', { installed: false, running: false })).toMatchObject({ action: 'install' });
expect(describeRuntimeSetup('llama', { installed: true, running: false })).toBeNull();
});
it('returns null for a runtime it has no row for', () => {
expect(describeRuntimeSetup('orcarouter', { installed: false, running: false })).toBeNull();
expect(describeRuntimeSetup(undefined, { installed: false, running: false })).toBeNull();
});
});
describe('runLocalRuntimeSetup', () => {
it('does nothing when the endpoint already answers — on ANY platform', async () => {
// Pinned to a platform this runtime cannot be installed on: a daemon that
// answers is running, and the macOS-only gate must not turn that into
// "MTPLX runs only on macOS". (Left unpinned this passed on a macOS dev box
// and failed on the Linux CI runner, which is how the ordering bug surfaced.)
const restore = pinPlatform('linux');
probe.probeOpenAiModels.mockResolvedValueOnce(reachable());
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1' });
restore();
expect(result).toMatchObject({ success: true, message: expect.stringMatching(/already running/) });
expect(streaming.runStreamingCommand).not.toHaveBeenCalled();
});
it('delegates the MTPLX install to its PM2-backed manager', async () => {
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const restore = pinPlatform('darwin');
await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1' });
restore();
expect(mtplx.installMtplx).toHaveBeenCalled();
// Nothing about MTPLX is installed by a command this module composes — which
// is what keeps upstream's privileged `mtplx max --install` fan-control
// helper out of every PortOS path.
expect(streaming.runStreamingCommand).not.toHaveBeenCalled();
});
it('stops at the install failure rather than starting a daemon that is not there', async () => {
probe.probeOpenAiModels.mockResolvedValue(unreachable);
mtplx.installMtplx.mockResolvedValue({ success: false, error: 'exit 1: no such formula' });
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1' });
restore();
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/no such formula/) });
expect(mtplx.startMtplxServer).not.toHaveBeenCalled();
});
it('refuses a host that cannot run the runtime at all', async () => {
probe.probeOpenAiModels.mockResolvedValueOnce(unreachable);
const restore = pinPlatform('win32');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1' });
restore();
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/only on macOS/) });
});
it('skips the start step when the install already brought the daemon up', async () => {
// Ollama's Homebrew service starts on install. Launching a second copy onto
// the same port is the failure this re-probe exists to prevent.
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable) // pre-flight
.mockResolvedValueOnce(reachable([])) // after install
.mockResolvedValueOnce(reachable(['qwen3']));
const result = await runLocalRuntimeSetup('ollama', { endpoint: 'http://localhost:11434/v1' });
expect(localLlm.installBackend).toHaveBeenCalledWith('ollama', expect.any(Function));
expect(localLlm.controlOllamaServer).not.toHaveBeenCalled();
expect(result).toMatchObject({ success: true, message: expect.stringContaining('qwen3') });
});
it('starts an installed-but-stopped Ollama', async () => {
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/ollama');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(reachable(['qwen3']));
const result = await runLocalRuntimeSetup('ollama', { endpoint: 'http://localhost:11434/v1' });
expect(localLlm.installBackend).not.toHaveBeenCalled();
expect(localLlm.controlOllamaServer).toHaveBeenCalledWith('start');
expect(result.success).toBe(true);
});
it('reports the install as done for llama.cpp and hands the model choice back', async () => {
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const result = await runLocalRuntimeSetup('llama', { endpoint: 'http://127.0.0.1:8080/v1' });
expect(llama.installLlamaServer).toHaveBeenCalled();
expect(result).toMatchObject({ success: true, message: expect.stringMatching(/Models → Runtimes/) });
});
it('stops after the install when the modal was closed', async () => {
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', {
endpoint: 'http://127.0.0.1:8000/v1',
isCancelled: () => true,
});
restore();
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/Cancelled/) });
});
it('starts MTPLX on the port the PROVIDER points at, not a hard-coded 8000', async () => {
// A user who moved MTPLX to 8010 would otherwise get a second server on
// 8000 that nothing talks to.
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable) // pre-flight
.mockResolvedValueOnce(unreachable) // after install
.mockResolvedValueOnce(reachable(['mtplx'])); // final confirmation
mtplx.startMtplxServer.mockResolvedValue({ success: true, endpoint: 'http://127.0.0.1:8010/v1' });
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8010/v1' });
restore();
expect(mtplx.startMtplxServer).toHaveBeenCalledWith(expect.objectContaining({ port: 8010 }));
expect(result).toMatchObject({ success: true, message: expect.stringContaining('http://127.0.0.1:8010/v1') });
});
it('waits out a cold model load rather than the launcher\'s short beat', async () => {
// This flow's contract is "the endpoint answers when the button finishes",
// so it must not inherit the LLMs-page budget that hands back a still-loading
// server and lets a status poll finish the story.
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(reachable(['mtplx']));
const restore = pinPlatform('darwin');
await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1' });
restore();
const [{ waitMs }] = mtplx.startMtplxServer.mock.calls[0];
expect(waitMs).toBeGreaterThanOrEqual(60_000);
});
it('surfaces the manager\'s refusal instead of a bare failure', async () => {
// e.g. an empty MTPLX cache, which names the download button that fixes it.
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels.mockResolvedValue(unreachable);
mtplx.startMtplxServer.mockRejectedValue(new Error('MTPLX has no model weights cached — use "Download default checkpoint"'));
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1' });
restore();
expect(result).toMatchObject({ success: false, error: expect.stringContaining('Download default checkpoint') });
});
it('downloads the default checkpoint and then starts, but ONLY for `pull-start`', async () => {
// The other half of the fix: the button the checklist now offers actually
// fetches the weights, so the user is not sent to a terminal.
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
// The cache is read by the START step, which runs AFTER the pull — so what
// it reports here is what the download just landed.
mtplxCache.listMtplxCachedModels
.mockResolvedValueOnce(cachedModels([{ repo_id: 'Example/Fresh', validation: { ok: true } }]));
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(reachable(['mtplx']));
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1', action: 'pull-start' });
restore();
expect(streaming.runStreamingCommand).toHaveBeenCalledWith(
'/opt/homebrew/bin/mtplx', ['pull'], expect.any(Function), expect.objectContaining({ splitRe: expect.any(RegExp) }),
);
// The checkpoint the pull just landed is handed to the manager, so it does
// not walk the same cache a second time for one start.
expect(mtplx.startMtplxServer).toHaveBeenCalledWith(expect.objectContaining({ port: 8000, model: 'Example/Fresh' }));
expect(result.success).toBe(true);
});
it('never downloads weights behind an explicit plain start', async () => {
// A multi-gigabyte download is a decision; only the action that says so may
// spend it. A `start` names the download BUTTON in prose and spends nothing.
mtplxCache.listMtplxCachedModels.mockResolvedValue(cachedModels([]));
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1', action: 'start' });
restore();
expect(streaming.runStreamingCommand).not.toHaveBeenCalled();
expect(mtplx.startMtplxServer).not.toHaveBeenCalled();
expect(result).toMatchObject({ success: false, error: expect.stringContaining('Download the default model') });
// Never a terminal command as the remedy (PRD NR-9).
expect(result.error).not.toMatch(/terminal/);
});
it('resolves an ABSENT action to whatever the checklist is currently offering', async () => {
// A client built before `pull-start` existed sends no action — but it still
// renders THIS server's button label, so on an empty cache the user clicked
// “Download the default model & start MTPLX”. Defaulting to a start would
// answer that click with the exact no-weights dead end the action removes.
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
mtplxCache.listMtplxCachedModels
.mockResolvedValueOnce(cachedModels([]))
.mockResolvedValueOnce(cachedModels([{ repo_id: 'Example/Fresh', validation: { ok: true } }]));
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(reachable(['mtplx']));
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1' });
restore();
expect(streaming.runStreamingCommand.mock.calls[0][1]).toEqual(['pull']);
expect(result.success).toBe(true);
});
it('resolves an ABSENT action to a plain start when the cache can serve', async () => {
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(reachable(['mtplx']));
const restore = pinPlatform('darwin');
await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1' });
restore();
expect(streaming.runStreamingCommand).not.toHaveBeenCalled();
expect(mtplx.startMtplxServer).toHaveBeenCalled();
});
it('refuses `pull-start` for a runtime with no pull step BEFORE installing anything', async () => {
// Reached after the route validated only membership in the global action
// list. Refusing late would run Ollama's install on the way to the refusal,
// and llama.cpp (`start: null`) would return its install-succeeded message
// without ever refusing at all.
pathLookup.findCommandOnPath.mockReturnValue(null);
probe.probeOpenAiModels.mockResolvedValue(unreachable);
for (const kind of ['ollama', 'llama']) {
const result = await runLocalRuntimeSetup(kind, { endpoint: 'http://127.0.0.1:11434/v1', action: 'pull-start' });
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/cannot download model weights/) });
}
expect(localLlm.installBackend).not.toHaveBeenCalled();
expect(llama.installLlamaServer).not.toHaveBeenCalled();
});
it('hands the download a cancellation hook — the setup lock is held until it settles', async () => {
// The route holds its single-setup lock until this promise resolves, and a
// weights pull can run for hours. Without a hook the child ignores a closed
// modal, so the download keeps going AND every other runtime's setup button
// is refused for the rest of it.
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(reachable(['mtplx']));
const isCancelled = () => false;
const restore = pinPlatform('darwin');
await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1', action: 'pull-start', isCancelled });
restore();
expect(streaming.runStreamingCommand.mock.calls[0][3]).toMatchObject({ isCancelled });
});
it('reads no model cache for a runtime that has none', async () => {
// `readRuntimeWeights` is what keeps the readiness poll from spending a
// subprocess per non-MTPLX runtime.
await expect(readRuntimeWeights('ollama')).resolves.toBe('unknown');
await expect(readRuntimeWeights('nonsense')).resolves.toBe('unknown');
expect(mtplxCache.listMtplxCachedModels).not.toHaveBeenCalled();
});
it('stops at a failed download rather than starting a server that cannot serve', async () => {
streaming.runStreamingCommand.mockResolvedValue({ success: false, error: 'exit 1: connection reset' });
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1', action: 'pull-start' });
restore();
expect(mtplx.startMtplxServer).not.toHaveBeenCalled();
expect(result).toMatchObject({ success: false, error: expect.stringContaining('connection reset') });
});
it('announces the cached checkpoint once, not once per layer', async () => {
// The manager emits this line itself once it has the checkpoint, and both
// layers stream into the SAME setup modal.
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(reachable(['mtplx']));
// Stand in for the real manager's own emit, so the count covers both layers.
mtplx.startMtplxServer.mockImplementation(async ({ model, onProgress }) => {
if (model) onProgress(`Serving the cached MTPLX model ${model}.`);
return { success: true, endpoint: 'http://127.0.0.1:8000/v1' };
});
const lines = [];
const restore = pinPlatform('darwin');
await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1', emit: (l) => lines.push(l) });
restore();
expect(lines.filter((l) => /Serving the cached MTPLX model/.test(l))).toHaveLength(1);
});
it('exposes every action the route may accept', () => {
expect([...SETUP_ACTIONS].sort()).toEqual(['install', 'install-start', 'provision-start', 'pull-start', 'start']);
});
it('refuses when every cached MTPLX model is an incomplete download', async () => {
mtplxCache.listMtplxCachedModels.mockResolvedValue(cachedModels([{ repo_id: 'Example/Partial', validation: { ok: false } }]));
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1', action: 'start' });
restore();
expect(mtplx.startMtplxServer).not.toHaveBeenCalled();
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/none passed its own file check/) });
});
it('starts MTPLX on its own default when the cache cannot be READ', async () => {
// Unreadable is not empty: blocking here would refuse a start that works.
mtplxCache.listMtplxCachedModels.mockResolvedValue({ models: null, error: '`mtplx models` timed out' });
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(reachable(['mtplx']));
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', { endpoint: 'http://127.0.0.1:8000/v1' });
restore();
// No checkpoint to name, so the manager falls through to MTPLX's own default.
expect(mtplx.startMtplxServer).toHaveBeenCalledWith(expect.objectContaining({ model: null }));
expect(result.success).toBe(true);
});
it('does not start a server when the modal closed while the cache was being read', async () => {
// The cache lookup is an awaited subprocess, and the caller's cancellation
// check ran BEFORE it — without a re-check, a closed modal still leaves an
// MTPLX server running.
let cancelled = false;
mtplxCache.listMtplxCachedModels.mockImplementation(async () => {
cancelled = true; // the user closes the modal while `mtplx models` runs
return cachedModels([{ repo_id: 'Example/MTP-Model', validation: { ok: true } }]);
});
pathLookup.findCommandOnPath.mockReturnValue('/opt/homebrew/bin/mtplx');
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const restore = pinPlatform('darwin');
const result = await runLocalRuntimeSetup('mtplx', {
endpoint: 'http://127.0.0.1:8000/v1',
isCancelled: () => cancelled,
});
restore();
expect(mtplx.startMtplxServer).not.toHaveBeenCalled();
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/Cancelled/) });
});
it('refuses a runtime kind it has no row for', async () => {
const result = await runLocalRuntimeSetup('made-up', { endpoint: 'http://127.0.0.1:9/v1' });
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/no automatic setup/) });
});
});
describe('vllm — the registry offers it, the manager does it', () => {
const vllmEndpoint = 'http://127.0.0.1:18020/v1';
const run = async (action = null) => runLocalRuntimeSetup('vllm', { endpoint: vllmEndpoint, emit: () => {}, action });
it('is unsupported on darwin, and says where Mac users should go instead', () => {
const restore = pinPlatform('darwin');
expect(describeRuntimeSetup('vllm', { installed: false, running: false })).toMatchObject({
runtime: 'vllm',
action: null,
provisions: false,
blockedReason: expect.stringMatching(/MTPLX or llama.cpp DSpark/),
});
restore();
});
it('offers a plain start on a Linux/Windows host with a prepared project', () => {
const restore = pinPlatform('linux');
expect(describeRuntimeSetup('vllm', { installed: true, running: false, weights: 'ready' })).toMatchObject({
runtime: 'vllm',
action: 'start',
provisions: false,
blockedReason: null,
});
restore();
});
it('offers the provisioning button — naming the payload — when nothing is prepared', () => {
const restore = pinPlatform('linux');
expect(describeRuntimeSetup('vllm', { installed: true, running: false, weights: 'empty' })).toEqual({
runtime: 'vllm',
label: 'vLLM (Qwen3.8-27B)',
action: 'provision-start',
actionLabel: 'Clone, build & prepare vLLM (Qwen3.8-27B) (~30 GB), then start',
// The client renders the download icon and the payload tooltip off THIS
// flag, so it never re-derives the answer from the action's spelling.
provisions: true,
blockedReason: null,
});
expect(SETUP_ACTIONS).toContain('provision-start');
restore();
});
it('reads its setup state from the manager, and not at all on an unsupported platform', async () => {
const linux = pinPlatform('linux');
vllmManager.readVllmQwenSetupState.mockResolvedValue('empty');
expect(await readRuntimeWeights('vllm')).toBe('empty');
linux();
// Docker is on PATH almost everywhere, so a Mac would otherwise sweep the
// compose project's cache roots once a minute for a card it cannot have.
const darwin = pinPlatform('darwin');
vllmManager.readVllmQwenSetupState.mockClear();
expect(await readRuntimeWeights('vllm')).toBe('unknown');
expect(vllmManager.readVllmQwenSetupState).not.toHaveBeenCalled();
darwin();
});
it('provisions then starts, through the manager, for the provision-start action', async () => {
const restore = pinPlatform('linux');
pathLookup.findCommandOnPath.mockReturnValue('/usr/bin/docker');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValue(reachable(['qwen3.8-27b']));
const result = await run('provision-start');
expect(result.success).toBe(true);
expect(vllmManager.provisionVllmQwenProject).toHaveBeenCalledTimes(1);
expect(vllmManager.startVllmQwenProject).toHaveBeenCalledTimes(1);
restore();
});
it('never provisions behind a plain start', async () => {
const restore = pinPlatform('linux');
pathLookup.findCommandOnPath.mockReturnValue('/usr/bin/docker');
vllmManager.readVllmQwenSetupState.mockResolvedValue('ready');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValue(reachable(['qwen3.8-27b']));
await run(null);
// The whole point: ~30 GB is never spent on a button that did not say so.
expect(vllmManager.provisionVllmQwenProject).not.toHaveBeenCalled();
expect(vllmManager.startVllmQwenProject).toHaveBeenCalledTimes(1);
restore();
});
it('surfaces the manager\'s start refusal verbatim', async () => {
const restore = pinPlatform('linux');
pathLookup.findCommandOnPath.mockReturnValue('/usr/bin/docker');
probe.probeOpenAiModels.mockResolvedValue(unreachable);
vllmManager.readVllmQwenSetupState.mockResolvedValue('ready');
vllmManager.startVllmQwenProject.mockResolvedValue({ success: false, error: 'no Qwen weights are cached yet' });
const result = await run(null);
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/no Qwen weights are cached/) });
expect(vllmManager.provisionVllmQwenProject).not.toHaveBeenCalled();
restore();
});
it('refuses a pull-start aimed at vLLM — its provisioning step is not a model download', async () => {
const restore = pinPlatform('linux');
pathLookup.findCommandOnPath.mockReturnValue('/usr/bin/docker');
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const result = await run('pull-start');
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/cannot download model weights/) });
expect(vllmManager.provisionVllmQwenProject).not.toHaveBeenCalled();
restore();
});
it('never installs docker, WSL2, or the container toolkit', async () => {
const restore = pinPlatform('linux');
pathLookup.findCommandOnPath.mockReturnValue(null); // docker not on PATH
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const result = await run('provision-start');
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/does not install this stack/) });
expect(vllmManager.provisionVllmQwenProject).not.toHaveBeenCalled();
expect(localLlm.installBackend).not.toHaveBeenCalled();
restore();
});
});
describe('sglang — a hardware gate in front of the same never-provision posture', () => {
const sglangEndpoint = 'http://127.0.0.1:18021/v1';
const hopper = { status: 'available', gpus: [{ name: 'NVIDIA H200', computeCap: '9.0', vramGb: 141 }] };
const ampere = { status: 'available', gpus: [{ name: 'NVIDIA GeForce RTX 3090', computeCap: '8.6', vramGb: 24 }] };
const startOnLinux = async () => {
pathLookup.findCommandOnPath.mockReturnValue('/usr/bin/docker');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValue(reachable(['qwen3.8-27b']));
return runLocalRuntimeSetup('sglang', { endpoint: sglangEndpoint, emit: () => {} });
};
it('is unsupported on darwin, and says where Mac users should go instead', () => {
const restore = pinPlatform('darwin');
expect(describeRuntimeSetup('sglang', { installed: false, running: false })).toMatchObject({
runtime: 'sglang',
action: null,
blockedReason: expect.stringMatching(/MTPLX or llama\.cpp DSpark/),
});
restore();
});
it('offers a start button on a Linux/Windows host with docker present', () => {
const restore = pinPlatform('linux');
expect(describeRuntimeSetup('sglang', { installed: true, running: false })).toMatchObject({
runtime: 'sglang',
action: 'start',
blockedReason: null,
});
restore();
});
it('brings up an already-prepared compose project — no --profile, in its own directory', async () => {
const restore = pinPlatform('linux');
cuda.getCudaCapability.mockResolvedValue(hopper);
const result = await startOnLinux();
expect(result.success).toBe(true);
expect(streaming.runStreamingCommand).toHaveBeenCalledWith(
'docker',
['compose', 'up', '-d'],
expect.any(Function),
expect.objectContaining({ cwd: preparedSglangProject.dir }),
);
restore();
});
it('refuses an Ampere card BEFORE docker, and names the vLLM path instead', async () => {
// The cookbook has no 3090 cell. Refusing here — not after a `docker compose
// up` — is what keeps a wrong-hardware host from pulling the image.
const restore = pinPlatform('linux');
cuda.getCudaCapability.mockResolvedValue(ampere);
const result = await startOnLinux();
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/qwen38-rtx3090/) });
expect(streaming.runStreamingCommand).not.toHaveBeenCalled();
expect(sglangProject.inspectSglangQwenProject).not.toHaveBeenCalled();
restore();
});
it('says the probe failed rather than "no GPU" when nvidia-smi would not answer', async () => {
const restore = pinPlatform('linux');
cuda.getCudaCapability.mockResolvedValue({ status: 'unknown', gpus: [] });
const result = await startOnLinux();
expect(result.error).toMatch(/could not read/i);
expect(streaming.runStreamingCommand).not.toHaveBeenCalled();
restore();
});
it('refuses to run compose when the project is not demonstrably prepared', async () => {
const restore = pinPlatform('linux');
cuda.getCudaCapability.mockResolvedValue(hopper);
sglangProject.sglangStartBlockedReason.mockReturnValue('no Qwen weights are cached yet');
const result = await startOnLinux();
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/no Qwen weights are cached/) });
// The whole point: a 20 GB pull is never started on the user's behalf.
expect(streaming.runStreamingCommand).not.toHaveBeenCalled();
restore();
});
it('asks WSL where the hand-prepared project is on Windows, and records the answer', async () => {
// The whole point of #5832: SGLang ships no provisioner, so preparing it by
// hand INSIDE the distro is the only path — and every Windows operator used
// to be handed a `\\wsl.localhost\<distro>\…` template to look up themselves.
const restore = pinPlatform('win32');
cuda.getCudaCapability.mockResolvedValue(hopper);
const lines = [];
pathLookup.findCommandOnPath.mockReturnValue('C:\\docker.exe');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValue(reachable(['qwen3.8-27b']));
const result = await runLocalRuntimeSetup('sglang', { endpoint: sglangEndpoint, emit: (line) => lines.push(line) });
expect(result.success).toBe(true);
expect(wsl.detectWslProjectDir).toHaveBeenCalledWith('sglang-qwen38');
expect(sglangProject.recordSglangProjectDir).toHaveBeenCalledWith(SGLANG_WSL_DIR);
// Recorded AND applied to this run, so the inspection below it resolves the
// detected directory even if the one-line `.env` write had failed.
expect(process.env.SGLANG_QWEN_PROJECT_DIR).toBe(SGLANG_WSL_DIR);
expect(lines.join('\n')).toContain(SGLANG_WSL_DIR);
restore();
});
it('never spends a WSL probe when the directory is already settled', async () => {
const restore = pinPlatform('win32');
cuda.getCudaCapability.mockResolvedValue(hopper);
process.env.SGLANG_QWEN_PROJECT_DIR = SGLANG_WSL_DIR;
pathLookup.findCommandOnPath.mockReturnValue('C:\\docker.exe');
probe.probeOpenAiModels
.mockResolvedValueOnce(unreachable)
.mockResolvedValueOnce(unreachable)
.mockResolvedValue(reachable(['qwen3.8-27b']));
await runLocalRuntimeSetup('sglang', { endpoint: sglangEndpoint, emit: () => {} });
// An exported value is this run's decision, and it outranks the record — so
// there is nothing left to detect and no subprocess worth spending.
expect(wsl.detectWslProjectDir).not.toHaveBeenCalled();
expect(sglangProject.recordSglangProjectDir).not.toHaveBeenCalled();
restore();
});
it('refuses before docker when WSL cannot answer, naming that host\'s fix and the feature doc', async () => {
const restore = pinPlatform('win32');
cuda.getCudaCapability.mockResolvedValue(hopper);
wsl.detectWslProjectDir.mockResolvedValue({ dir: null, reason: 'internal-distro', distro: 'docker-desktop', distros: ['Ubuntu'] });
pathLookup.findCommandOnPath.mockReturnValue('C:\\docker.exe');
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const result = await runLocalRuntimeSetup('sglang', { endpoint: sglangEndpoint, emit: () => {} });
// Docker Desktop's own distro is wiped on a reset — and the refusal names
// the distro that ISN'T, rather than a `<distro>` placeholder.
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/docker-desktop/) });
expect(result.error).toMatch(/wsl --set-default/);
expect(result.error).toContain('Ubuntu');
expect(result.error).toContain('SGLANG_QWEN_PROJECT_DIR');
// Never reaches docker, so no image is ever pulled on a host that cannot
// hold the project.
expect(streaming.runStreamingCommand).not.toHaveBeenCalled();
expect(sglangProject.inspectSglangQwenProject).not.toHaveBeenCalled();
restore();
});
it('sends a Windows host with no WSL to the feature doc, never to a clone it does not have', async () => {
const restore = pinPlatform('win32');
cuda.getCudaCapability.mockResolvedValue(hopper);
wsl.detectWslProjectDir.mockResolvedValue({ dir: null, reason: 'no-wsl', error: 'spawn wsl.exe ENOENT' });
pathLookup.findCommandOnPath.mockReturnValue('C:\\docker.exe');
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const result = await runLocalRuntimeSetup('sglang', { endpoint: sglangEndpoint, emit: () => {} });
expect(result.success).toBe(false);
expect(result.error).toMatch(/wsl --install -d Ubuntu/);
// SGLang has no provisioner, so the refusal must NOT promise that clicking
// again places the project — it points at the doc the operator prepares it
// from. That clause is the one piece of this refusal that is per-stack.
expect(result.error).toContain('docs/features/sglang-qwen38.md');
expect(result.error).not.toMatch(/PortOS will place the project inside it/);
restore();
});
it('never installs docker or the container toolkit', async () => {
const restore = pinPlatform('linux');
cuda.getCudaCapability.mockResolvedValue(hopper);
pathLookup.findCommandOnPath.mockReturnValue(null); // docker not on PATH
probe.probeOpenAiModels.mockResolvedValue(unreachable);
const result = await runLocalRuntimeSetup('sglang', { endpoint: sglangEndpoint, emit: () => {} });
expect(result).toMatchObject({ success: false, error: expect.stringMatching(/does not install this stack/) });
expect(streaming.runStreamingCommand).not.toHaveBeenCalled();
restore();
});
});