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
/**
* What MTPLX has in its own model cache, and which entry PortOS may serve.
*
* `mtplx serve` takes NO model from its config — the CLI hard-codes its default
* checkpoint (`Youssofal/Qwen3.8-27B-…`) as the `--model` default. On a machine
* where that exact repo was never pulled the server prints
*
* error: model is not available locally
* detail: … is not cached. Run: mtplx pull …
*
* and exits 1 before it binds a port — including when the user HAS pulled a
* different MTP checkpoint that would have served fine. That is what turned the
* readiness checklist's "Start MTPLX" button into "MTPLX did not start: mtplx
* exited early (code 1)".
*
* So PortOS asks first. `mtplx models --json` walks local directories — it
* pulls no weights and loads no model — and naming a cached repo on the command
* line is the difference between a server that comes up and one that cannot. A
* start still never downloads weights: a multi-gigabyte pull stays the user's
* decision, made on a button that says so (`services/localRuntimeSetup.js`'s
* `pull-start` action), exactly as `docs/features/mtplx.md` promises.
*
* **It is NOT free, and it is NOT safe on an un-warmed status poll.** The
* `mtplx` Homebrew puts on PATH is a wrapper that bootstraps a version-keyed
* Python venv — several hundred megabytes over the network — on its first
* invocation, and `brew upgrade` re-arms it. So on such a host THIS spawn is
* that download: it outruns the timeout below, gets killed, and the next caller
* starts it over. Callers on a poll must gate on `lib/mtplxRuntime.js`'s
* `describeMtplxRuntime().ready` first — `services/mtplxServerManager.js` and
* `services/localRuntimeSetup.js` both do.
*/
import { bufferedSpawn, spawnFailureDetail } from './bufferedSpawn.js';
import { safeJSONParse } from './fileUtils.js';
import { findCommandOnPath } from './processEnv.js';
/** A cache listing walks the model directories to size them; be generous. */
const CACHE_QUERY_TIMEOUT_MS = 30_000;
/**
* The models in MTPLX's local cache.
*
* `models: null` means PortOS could not read the cache at all (no binary, the
* command failed, unparseable output) — deliberately NOT the same value as
* `models: []`, which means the cache was read and is empty. The caller starts
* MTPLX with its own default in the first case and refuses in the second; a
* shared falsy value would make an unreadable cache look like an empty one and
* block a start that would have worked.
*
* @param {{command?: string}} [options]
* @returns {Promise<{models: object[]|null, error: string|null}>}
*/
export async function listMtplxCachedModels({ command = 'mtplx' } = {}) {
const binary = findCommandOnPath(command);
if (!binary) return { models: null, error: `\`${command}\` is not on PortOS's PATH` };
const result = await bufferedSpawn(binary, ['models', '--json'], { timeoutMs: CACHE_QUERY_TIMEOUT_MS, shell: false });
if (result.timedOut) return { models: null, error: `\`${command} models\` timed out` };
if (!result.success) {
// A spawn failure (EACCES, ENOENT on a dangling symlink) reports nothing on
// either stream — its reason lives on `error`, and dropping it would leave
// the user with a bare exit code for a fixable permissions problem.
return { models: null, error: spawnFailureDetail(result, `\`${command} models\` exited with code ${result.code}`) };
}
// Parse from the first brace: MTPLX writes the JSON alone today, but a banner
// line ahead of it must not read as "nothing is cached".
const text = String(result.stdout || '');
const start = text.indexOf('{');
const parsed = start === -1 ? null : safeJSONParse(text.slice(start), null, { allowArray: false });
if (!Array.isArray(parsed?.models)) {
return { models: null, error: `\`${command} models --json\` did not return a model list` };
}
return { models: parsed.models, error: null };
}
/**
* The cache rows MTPLX itself calls complete, in listing order.
*
* `validation.ok` is false for a directory missing required files or an MTP
* sidecar, which is what an interrupted `mtplx pull` leaves behind. That rule
* decides both what PortOS may START a server on and what it may OFFER as a
* selectable model, so it lives here once rather than being spelled at each —
* the shape it reads is upstream's `models --json`, and a second copy would go
* stale the first time that payload grows a new incompleteness marker.
*
* `[]` for a non-array input: callers that must distinguish "could not read the
* cache" check `listMtplxCachedModels`' own `models: null` before calling.
*
* @param {object[]|null|undefined} models - rows from `listMtplxCachedModels`
* @returns {object[]}
*/
export function servableMtplxCachedModels(models) {
if (!Array.isArray(models)) return [];
return models.filter((row) => typeof row?.repo_id === 'string' && row.repo_id !== '' && row?.validation?.ok !== false);
}
/**
* The cached repo id PortOS should hand `mtplx serve --model`, or null when the
* cache holds nothing servable.
*
* Only entries MTPLX itself calls complete are eligible (see
* `servableMtplxCachedModels`) — starting the server on a partial pack trades an
* honest "nothing is cached" for a load failure minutes later. Among complete
* entries, one carrying `mtplx_runtime.json` wins: that is the recorded
* exactness contract, and the runtime warns on stats from artifacts without it.
*
* @param {object[]|null|undefined} models - rows from `listMtplxCachedModels`
* @returns {string|null}
*/
export function pickMtplxCachedModel(models) {
const usable = servableMtplxCachedModels(models);
const verified = usable.find((row) => row.has_runtime_contract === true);
return (verified || usable[0])?.repo_id ?? null;
}
/**
* The one value the readiness checklist and the setup button both key on:
* can MTPLX serve anything right now, and if not, why not.
*
* The checklist used to answer "MTPLX installed ✓ / server not responding ✗ —
* use Start MTPLX, PortOS does this for you", and Start then failed with "no
* model weights are cached". Both statements were true and the pair was a
* catch-22: the blocking fact (an empty cache) was only discoverable by
* clicking the button that could not work. Reading it up front is what lets the
* checklist say what is missing and offer the download instead of the start.
*
* States are deliberately four, not two — `unknown` (the cache could not be
* read) must not read as `empty` (read, and nothing is there), for the same
* reason `listMtplxCachedModels` distinguishes `null` from `[]`; and `partial`
* (an interrupted `mtplx pull`) needs a different sentence than a cache nobody
* has ever pulled into.
*
* @param {{models: object[]|null, error: string|null}} [cache] - a
* `listMtplxCachedModels` result
* @returns {{state: 'unknown'|'empty'|'partial'|'ready', model: string|null, count: number, error: string|null}}
*/
export function describeMtplxCache({ models, error } = {}) {
if (!Array.isArray(models)) return { state: 'unknown', model: null, count: 0, error: error || null };
const model = pickMtplxCachedModel(models);
if (model) return { state: 'ready', model, count: models.length, error: null };
return { state: models.length === 0 ? 'empty' : 'partial', model: null, count: models.length, error: null };
}