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
/**
* SSD-streaming MoE process manager
*
* Lifecycle management (status probe, install, start, stop, recent logs) for a
* local `slotstream serve` OpenAI-compatible API server, managed as an optional
* PM2 process (`portos-slotstream`) — the same shape as `mtplxServerManager.js`.
*
* A start never downloads weights. An absent checkpoint is reported, not
* silently fetched. The memory plan (target GB, expected peak, expected warm
* decode) is part of the status payload so the LLMs row can show it, and an
* explicit memory-cap override is persisted on the saved launch line the
* on-demand start replays.
*
* Always passes `--port` explicitly. Upstream's default (11434) collides with
* a PortOS-managed Ollama, so that port is refused.
*/
import { chmod, mkdir, writeFile } from 'fs/promises';
import { tmpdir } from 'os';
import { join } from 'path';
import { commandExists } from '../lib/commandExists.js';
import { ServerError } from '../lib/errorHandler.js';
import { sleep } from '../lib/fileUtils.js';
import { LOCAL_RUNTIMES, localEndpointPort, localRuntimeKind, isLocalInstanceEndpoint } from '../lib/localProviderRuntime.js';
import {
createDaemonWatcher,
createOnDemandDaemon,
createPm2ExitTail,
pm2ArgValue,
SLOTSTREAM_APP,
} from '../lib/managedDaemon.js';
import { persistDaemonLaunchConfig } from './localDaemonLaunchConfig.js';
import { probeOpenAiModels } from '../lib/openAiModelsProbe.js';
import { isAppleSilicon, isPortInUse } from '../lib/platform.js';
import { PORTS } from '../lib/ports.js';
import { findCommandOnPath } from '../lib/processEnv.js';
import { SLOTSTREAM_CATALOG } from '../lib/slotstreamCatalog.js';
import {
listSlotstreamCachedModels,
pickSlotstreamCachedModel,
planSlotstreamMemory,
slotstreamBinDir,
slotstreamCacheDir,
} from '../lib/slotstreamModels.js';
import { runStreamingCommand } from '../lib/streamingSpawn.js';
import { execPm2, getAppStatusStrict, clearJlistCache, getSavedProcessNames } from './pm2.js';
export { SLOTSTREAM_APP };
const PROBE_TIMEOUT_MS = 1500;
const INSTALL_TIMEOUT_MS = 20 * 60 * 1000;
const OLLAMA_COLLISION_PORT = 11434;
let startupWaitMs = 8_000;
let startupPollMs = 1500;
let relaunchReadyTimeoutMs = 300_000;
let relaunchPollMs = 1000;
const DEFAULT_HOST = '127.0.0.1';
const DEFAULT_PORT = Number(localEndpointPort(LOCAL_RUNTIMES.slotstream.defaultBaseUrl)) || PORTS.SLOTSTREAM;
export const SLOTSTREAM_UNSUPPORTED_REASON = 'Slotstream runs only on macOS with Apple Silicon.';
const slotstreamNoModelError = () => `Slotstream has no model weights cached, so its server would exit before it binds a port. A start never downloads weights — place a checkpoint directory in ${slotstreamCacheDir()}, then start it again.`;
const SLOTSTREAM_OLLAMA_PORT_ERROR = `Port ${OLLAMA_COLLISION_PORT} is Ollama's default and a PortOS-managed Ollama already uses it. Point Slotstream at its dedicated loopback port (${DEFAULT_PORT}) instead.`;
const DEFAULT_SLOTSTREAM_LOG_FILES = {
stdout: join(tmpdir(), 'portos-slotstream-out.log'),
stderr: join(tmpdir(), 'portos-slotstream-error.log'),
};
let slotstreamLogFiles = DEFAULT_SLOTSTREAM_LOG_FILES;
const resetSlotstreamLogs = async () => {
const results = await Promise.all(
Object.entries(slotstreamLogFiles).map(([stream, path]) => (
writeFile(path, '')
.then(() => true)
.catch((error) => {
console.error(`❌ Slotstream: could not reset ${stream} startup log (${error?.code || 'unknown'}); bootstrap diagnosis disabled for this launch`);
return false;
})
)),
);
return results.every(Boolean);
};
let currentConfig = null;
let lastExitError = null;
const probeEndpoint = async (endpoint) =>
(await probeOpenAiModels(endpoint, { timeoutMs: PROBE_TIMEOUT_MS })).reachable;
const endpointFor = (config) =>
`http://${DEFAULT_HOST}:${config?.port ?? DEFAULT_PORT}/v1`;
const daemon = createDaemonWatcher({
appName: SLOTSTREAM_APP,
defaultHost: DEFAULT_HOST,
defaultPort: DEFAULT_PORT,
endpointFor,
parseConfigFromArgs,
probe: probeEndpoint,
isPortInUse: (...args) => isPortInUse(...args),
sleep,
getConfig: () => currentConfig,
setConfig: (config) => { currentConfig = config; },
getLastExitError: () => lastExitError,
getAppStatus: (...args) => getAppStatusStrict(...args),
getSavedProcessNames: (...args) => getSavedProcessNames(...args),
execPm2: (...args) => execPm2(...args),
});
const appendLog = daemon.appendLog;
// `settings.js` reached only through a dynamic import — see the note beside
// `mtplxServerManager.js`'s copy of this same pattern.
const readSettings = () => import('./settings.js').then((m) => m.getSettings()).catch(() => null);
/**
* The shared on-demand wake mechanism (#8105) — see the identical block in
* `mtplxServerManager.js` for the full contract. `resolveLaunch` here carries
* `memoryGb` instead of `tuning`.
*/
const onDemand = createOnDemandDaemon({
appName: SLOTSTREAM_APP,
label: 'Slotstream',
emoji: '🌊',
readSection: () => readSettings().then((settings) => settings?.localLlm?.slotstream ?? null),
endpointFor,
probe: probeEndpoint,
start: (config) => launchSlotstreamServer(config),
stop: () => stopSlotstreamServer(),
getStatusStrict: () => getAppStatusStrict(SLOTSTREAM_APP),
clearStatusCache: () => clearJlistCache(),
exitTail: createPm2ExitTail({ appName: SLOTSTREAM_APP, execPm2: (...args) => execPm2(...args), appendLog }),
resolveLaunch: (current, saved) => ({
port: current?.port ?? saved.port ?? DEFAULT_PORT,
model: current?.model ?? saved.model ?? null,
memoryGb: current?.memoryGb ?? (Number.isFinite(Number(saved.raw?.memoryGb)) ? Number(saved.raw.memoryGb) : null),
}),
getConfig: () => currentConfig,
parseConfigFromArgs,
sleep,
getRelaunchReadyTimeoutMs: () => relaunchReadyTimeoutMs,
getRelaunchPollMs: () => relaunchPollMs,
});
onDemand.registerIdle();
/**
* Reconstructs the launch config from PM2 process args when PortOS restarted
* while the PM2 process stayed online.
*/
function parseConfigFromArgs(args) {
if (!args) return null;
const list = Array.isArray(args) ? args : String(args).split(' ');
if (!list.includes('serve')) return null;
const port = pm2ArgValue(list, '--port');
const memoryGb = pm2ArgValue(list, '--memory-gb');
return {
port: port ? Number(port) : DEFAULT_PORT,
model: pm2ArgValue(list, '--model'),
memoryGb: memoryGb && Number.isFinite(Number(memoryGb)) ? Number(memoryGb) : null,
};
}
const resolveStartPort = (requested) => {
const port = Number.isFinite(Number(requested)) ? Number(requested) : DEFAULT_PORT;
if (port === OLLAMA_COLLISION_PORT) {
throw new ServerError(SLOTSTREAM_OLLAMA_PORT_ERROR, { status: 400, code: 'SLOTSTREAM_PORT_COLLISION' });
}
return port;
};
/** Resolve the `slotstream` executable on PATH, then the release-install location. */
export const resolveSlotstreamBinary = () =>
findCommandOnPath('slotstream') || findCommandOnPath(join(slotstreamBinDir(), 'slotstream'));
export async function getSlotstreamServerEndpoint() {
if (!currentConfig) {
await daemon.readLaunch();
}
return daemon.endpoint();
}
/**
* Current Slotstream state: binary, process, endpoint, memory plan, cache, logs.
*/
export async function getSlotstreamServerStatus() {
const binaryPath = resolveSlotstreamBinary();
const installed = Boolean(binaryPath);
const supported = installed || isAppleSilicon();
const base = await daemon.getStatusBase({ installed });
const saved = await savedLaunchConfig();
const cache = installed ? await listSlotstreamCachedModels() : { models: null, error: null };
// The SAVED override, never the running config: `--memory-gb` is always on
// the launch line, so reading the target back off it would report every
// auto-sized start as an explicit cap and `auto` would never be true.
const memoryPlan = planSlotstreamMemory({ overrideGb: saved.memoryGb });
return {
...base,
supported,
unsupportedReason: supported ? null : SLOTSTREAM_UNSUPPORTED_REASON,
idleMinutes: await onDemand.idleMinutes(),
keepLoaded: await onDemand.keepLoaded(),
launch: saved,
memoryPlan,
cachedModels: (cache.models || []).map((m) => m?.id).filter(Boolean),
cacheDir: slotstreamCacheDir(),
cacheError: cache.error,
// The download menu rides on the status payload rather than a route of its
// own: it is three frozen rows, so a second fetch (and a second cache to
// keep in step with the cached-checkpoint list beside it) would buy nothing.
catalog: SLOTSTREAM_CATALOG,
};
}
/**
* Install the Apple Silicon Slotstream binary from GitHub Releases into
* `~/.slotstream/bin`. Never pipes a remote script to a shell, and never
* fetches model weights.
*/
export async function installSlotstream({ onProgress = () => {} } = {}) {
const emit = (message) => onProgress({ event: 'progress', message });
if (!isAppleSilicon()) {
throw new ServerError(SLOTSTREAM_UNSUPPORTED_REASON, { status: 400, code: 'SLOTSTREAM_UNSUPPORTED_PLATFORM' });
}
const binDir = slotstreamBinDir();
await mkdir(binDir, { recursive: true });
if (!(await commandExists('gh', ['--version']))) {
throw new ServerError(
'PortOS could not install Slotstream because GitHub CLI is not available on this machine.',
{ status: 400, code: 'SLOTSTREAM_INSTALL_UNAVAILABLE' },
);
}
emit('Downloading Slotstream from GitHub Releases…');
const download = await runStreamingCommand('gh', [
'release', 'download',
'--repo', 'carloslfu/slotstream',
'--pattern', 'slotstream-arm64.tar.gz',
'--dir', binDir,
'--clobber',
], emit, { timeoutMs: INSTALL_TIMEOUT_MS });
if (!download.success) throw new ServerError(`Slotstream install failed: ${download.error}`, { status: 500 });
const archive = join(binDir, 'slotstream-arm64.tar.gz');
emit('Extracting Slotstream…');
const extract = await runStreamingCommand('tar', ['-xzf', archive, '-C', binDir], emit, { timeoutMs: 60_000 });
if (!extract.success) throw new ServerError(`Slotstream extract failed: ${extract.error}`, { status: 500 });
const binary = join(binDir, 'slotstream');
await chmod(binary, 0o755).catch(() => {});
if (!resolveSlotstreamBinary() && !findCommandOnPath(binary)) {
throw new ServerError('Slotstream downloaded but the binary was not found in ~/.slotstream/bin.', { status: 500 });
}
return { success: true, message: 'Slotstream installed' };
}
/**
* The checkpoint a start hands `--model`, always resolved against the on-disk
* cache.
*
* An explicitly requested checkpoint is verified to be cached rather than
* passed straight through: `slotstream serve` treats an uncached name as
* something to fetch, so trusting the request would be the one path that
* downloads weights on a start.
*/
async function resolveStartModel(requested, emit) {
const cache = await listSlotstreamCachedModels();
if (cache.models === null) {
emit(`Could not read Slotstream's model cache (${cache.error}) — refusing to start rather than fetching weights.`);
return { error: slotstreamNoModelError() };
}
if (cache.models.length === 0) return { error: slotstreamNoModelError() };
const model = pickSlotstreamCachedModel(cache.models, requested);
if (!model) return { error: slotstreamNoModelError() };
if (!cache.models.some((row) => row?.id === model)) {
return {
error: `Slotstream has no cached checkpoint named "${model}". A start never downloads weights — pick one of the cached checkpoints (${cache.models.map((row) => row.id).join(', ')}) instead.`,
};
}
return { model };
}
/**
* Start `slotstream serve` under PM2, queued behind any in-flight on-demand
* wake or explicit start (`onDemand.runStart`, #12723) so it cannot
* `pm2 delete` a launch that is still loading.
*
* @param {Parameters<typeof launchSlotstreamServer>[0]} [options]
*/
export const startSlotstreamServer = (options = {}) => onDemand.runStart(() => launchSlotstreamServer(options));
/**
* The unserialized start behind `startSlotstreamServer`; only the on-demand
* wake, which already holds the start slot, calls it directly.
*
* @param {{port?: number, model?: string, memoryGb?: number, waitMs?: number, onProgress?: (line: string) => void}} options
*/
async function launchSlotstreamServer(options = {}) {
const { port: requestedPort, model: requestedModel = null, memoryGb = null, waitMs, onProgress = () => {} } = options;
const port = resolveStartPort(requestedPort ?? DEFAULT_PORT);
const emit = (line) => { appendLog(line); onProgress(line); };
if (!isAppleSilicon()) {
throw new ServerError(SLOTSTREAM_UNSUPPORTED_REASON, { status: 400, code: 'SLOTSTREAM_UNSUPPORTED_PLATFORM' });
}
const binaryPath = resolveSlotstreamBinary();
if (!binaryPath) {
throw new ServerError(
'The Slotstream binary was not found. Install it from this card, then try again.',
{ status: 400, code: 'SLOTSTREAM_NOT_INSTALLED' },
);
}
const pm2Status = await getAppStatusStrict(SLOTSTREAM_APP);
if (pm2Status && pm2Status.status === 'online') {
throw new ServerError(`Slotstream is already running with PID ${pm2Status.pid}`, { status: 409 });
}
const endpoint = `http://${DEFAULT_HOST}:${port}/v1`;
if (await probeEndpoint(endpoint)) {
throw new ServerError(`Port ${port} is already in use by an active server at ${endpoint}`, { status: 409 });
}
if (await isPortInUse(port)) {
throw new ServerError(
`Port ${port} is already in use on ${DEFAULT_HOST}. Point Slotstream at a different port before starting it.`,
{ status: 409, code: 'SLOTSTREAM_PORT_IN_USE' },
);
}
daemon.resetLogs();
lastExitError = null;
const resolved = await resolveStartModel(requestedModel, emit);
if (resolved.error) throw new ServerError(resolved.error, { status: 400, code: 'SLOTSTREAM_NO_CACHED_MODEL' });
const model = resolved.model;
if (model) emit(`Serving the cached Slotstream checkpoint ${model}.`);
const plan = planSlotstreamMemory({ overrideGb: memoryGb });
const args = [
'serve',
'--port', String(port),
'--memory-gb', String(plan.targetGb),
...(model ? ['--model', model] : []),
];
// `config.memoryGb` is the resolved target actually in effect — the same
// number `parseConfigFromArgs` reads back off the PM2 launch line. The
// user's *override* (null when PortOS sized it) is a separate fact, kept on
// the saved launch below, because the launch line alone cannot tell an
// auto-sized 85.8 GB from one the user typed.
currentConfig = { port, model, memoryGb: plan.targetGb };
appendLog(`Starting: slotstream ${args.join(' ')}`);
await execPm2(['delete', SLOTSTREAM_APP]).catch(() => {});
clearJlistCache();
console.log(`🌊 Slotstream starting on ${DEFAULT_HOST}:${port}${model ? ` (model ${model})` : ''} (memory ${plan.targetGb} GB${plan.auto ? ', auto' : ''})`);
const logsReset = await resetSlotstreamLogs();
await execPm2([
'start', binaryPath,
'--name', SLOTSTREAM_APP,
'--interpreter', 'none',
'--no-autorestart',
'--output', slotstreamLogFiles.stdout,
'--error', slotstreamLogFiles.stderr,
'--',
...args,
]);
clearJlistCache();
const deadline = Date.now() + (Number.isFinite(waitMs) ? waitMs : startupWaitMs);
let online = false;
let currentProc = null;
while (Date.now() < deadline) {
await sleep(startupPollMs);
clearJlistCache();
currentProc = await getAppStatusStrict(SLOTSTREAM_APP);
if (currentProc && ['errored', 'stopped', 'not_found'].includes(currentProc.status)) break;
online = await probeEndpoint(endpoint);
if (online) break;
}
if (currentProc && ['errored', 'stopped', 'not_found'].includes(currentProc.status)) {
const pm2Logs = await execPm2(['logs', SLOTSTREAM_APP, '--nostream', '--lines', '15']).catch(() => null);
// Only trust the tail when the startup logs were actually truncated —
// otherwise this launch's diagnosis would be the PREVIOUS launch's output,
// sending the user after an error they already fixed.
const lines = logsReset
? `${pm2Logs?.stderr || pm2Logs?.stdout || ''}`.split('\n').map((l) => l.trimEnd()).filter(Boolean)
: [];
for (const line of lines) appendLog(line);
const tail = (lines.length ? lines : daemon.snapshotLogs()).slice(-4).join(' | ');
lastExitError = `PM2 status: ${currentProc.status}`;
await execPm2(['delete', SLOTSTREAM_APP]).catch(() => {});
clearJlistCache();
currentConfig = null;
throw new ServerError(
`Slotstream exited immediately (${lastExitError}).${tail ? ` Last output: ${tail}` : ''}`,
{ status: 500, code: 'SLOTSTREAM_EXITED' },
);
}
// `memoryGb` stays the user's *override* (null when PortOS sized it), never
// the resolved target — `--memory-gb` is always on the launch line, so the
// saved override is the only thing that can tell an auto-sized 85.8 GB from
// one the user typed apart later.
await persistDaemonLaunchConfig({ key: 'slotstream', label: 'Slotstream', launch: { port, model, memoryGb: plan.auto ? null : plan.targetGb } });
const finalProc = await getAppStatusStrict(SLOTSTREAM_APP);
return {
success: true,
running: true,
managed: true,
pid: finalProc?.pid || null,
endpoint,
online,
config: currentConfig,
memoryPlan: plan,
};
}
/** Stop the managed Slotstream process. */
export async function stopSlotstreamServer() {
const pm2Status = await getAppStatusStrict(SLOTSTREAM_APP);
const isManaged = Boolean(pm2Status && pm2Status.status === 'online');
if (!isManaged) {
const endpoint = endpointFor(currentConfig);
if (await probeEndpoint(endpoint)) {
return {
success: false,
message: `An external process is listening on ${endpoint}. It was not started by PortOS and cannot be stopped here.`,
};
}
return { success: true, message: 'Slotstream is not running' };
}
appendLog(`Stopping ${SLOTSTREAM_APP}`);
await execPm2(['delete', SLOTSTREAM_APP]).catch((err) => {
throw new ServerError(`Failed to stop Slotstream: ${err.message}`, { status: 500 });
});
clearJlistCache();
currentConfig = null;
return { success: true, message: 'Slotstream stopped' };
}
export function _resetSlotstreamServerStateForTests({
startupWait,
startupPoll,
relaunchReadyTimeout,
relaunchPoll,
idleMinutes = 0,
keepLoaded = null,
logFiles,
} = {}) {
onDemand.setIdleMinutesOverrideForTests(idleMinutes);
onDemand.setKeepLoadedOverrideForTests(keepLoaded);
slotstreamLogFiles = logFiles ? {
stdout: logFiles.stdout || DEFAULT_SLOTSTREAM_LOG_FILES.stdout,
stderr: logFiles.stderr || DEFAULT_SLOTSTREAM_LOG_FILES.stderr,
} : DEFAULT_SLOTSTREAM_LOG_FILES;
currentConfig = null;
daemon.resetLogs();
lastExitError = null;
startupWaitMs = Number.isFinite(startupWait) ? startupWait : 8_000;
startupPollMs = Number.isFinite(startupPoll) ? startupPoll : 1500;
relaunchReadyTimeoutMs = Number.isFinite(relaunchReadyTimeout) ? relaunchReadyTimeout : 300_000;
relaunchPollMs = Number.isFinite(relaunchPoll) ? relaunchPoll : 1000;
}
// Test hook for pinning
export function _setSlotstreamKeepLoadedOverrideForTests(val) {
onDemand.setKeepLoadedOverrideForTests(val);
}
/**
* The launch line last saved on the Slotstream card, for a lazy start to
* replay — including the `memoryGb` override, the one field the shared
* `onDemand.savedLaunch()` (model/port only) does not sanitize on its own.
*/
async function savedLaunchConfig() {
const { model, port, raw } = await onDemand.savedLaunch();
return {
model,
port,
memoryGb: Number.isFinite(Number(raw?.memoryGb)) ? Number(raw.memoryGb) : null,
};
}
// `registerIdleDaemon`, the idle-minutes/keep-loaded reads, `markSlotstreamUsed`,
// and `ensureSlotstreamRunning` all now live in `onDemand` (#8105) — see the
// identical block in `mtplxServerManager.js`.
export const markSlotstreamUsed = () => onDemand.markUsed();
/**
* Bring Slotstream up if the idle reaper (or the user) stopped it. See
* `onDemand.ensureRunning` for the shared mechanism; Slotstream's own
* contribution is the `resolveLaunch` hook wired above, which carries
* `memoryGb` alongside `port`/`model`.
*
* @returns {Promise<{ready: boolean, reason: string|null}>}
*/
export const ensureSlotstreamRunning = () => onDemand.ensureRunning();
export function isSlotstreamProvider(provider) {
if (!provider || !['api', 'tui'].includes(provider.type)) return false;
if (!isLocalInstanceEndpoint(provider.endpoint)) return false;
if (localRuntimeKind(provider) === 'slotstream') return true;
return onDemand.servesPort(provider, currentConfig?.port);
}
/**
* The checkpoints THIS machine can serve, for a Slotstream provider's model
* refresh — the Slotstream half of `services/localCachedModels.js`.
*
* Same shape of bug as MTPLX, and worse in one way: `slotstream serve` loads one
* checkpoint and answers only under that id, while the shipped `slotstream`
* record lists THREE. So a refresh did not merely fail to add a newly downloaded
* checkpoint — it pruned the record's other two shipped ids down to whatever the
* daemon happened to have loaded, including the `defaultModel` pin whenever that
* was not the loaded one.
*
* `null` for a provider that is not this daemon's and for a cache that could not
* be READ — deliberately not `[]`, which the caller must be free to read as
* "read, and genuinely empty". Unlike MTPLX this costs no subprocess and needs
* no runtime gate: the listing is a directory read (`lib/slotstreamModels.js`).
*
* @param {{type?: string, endpoint?: string}|null} provider
* @returns {Promise<string[]|null>}
*/
export async function slotstreamCachedModelIds(provider) {
if (!isSlotstreamProvider(provider)) return null;
const { models } = await listSlotstreamCachedModels();
if (!Array.isArray(models)) return null;
return models.map((row) => row?.id).filter((id) => typeof id === 'string' && id !== '');
}
export async function ensureSlotstreamProviderReady(provider) {
if (!isSlotstreamProvider(provider)) return { success: true };
const { ready, reason } = await ensureSlotstreamRunning();
return ready ? { success: true } : { success: false, error: reason };
}