Router that virtually distributes inference across connected devices in the home.
Go
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
import type { EngineInitialState } from '@/shared/types/engine-api'
import type {
EngineModels,
EngineProcessStatus,
EngineProgress,
EngineStatusData,
EngineType,
ModelItem
} from '@/shared/types/engines'
import type { LogEntry, LogPage } from '@/shared/types/log'
import type { NodeItemMetrics } from '@/shared/types/metrics'
import type { NodeItem } from '@/shared/types/nodes'
import type { ServiceError, ServiceErrorAction, ServiceErrorSeverity } from '@/shared/types/errors'
import type { Workload, WorkloadState } from '@/shared/types/workloads'
import type { ClusterNode, Invite } from '@/shared/types/cluster'
import type { WsInvokeResponse } from '@/shared/types/ws-channels'
import {
MODULAR_NODE_INFO_SELF_HOST,
MODULAR_SUPERSEDE_MIN_AGE_MS
} from '@/shared/constants/modular-runtime'
import { WorkloadStates } from '@/shared/constants/workloads'
import {
emptyEngineStatus,
engineManagerName,
engineTypeFromManagerName,
isEngineType
} from '@/shared/utils/engines'
import { engineProgressKey } from '@/shared/utils/engine-progress'
import { workloadKey } from '@/shared/utils/workloads'
import { currentPlatform, platformDisplayName } from '@/shared/utils/platform'
import { emitBridgePush } from './broadcaster'
import { mergePullProgressPercent } from './pull-error-handling'
import type { JsonObject, JsonRpcNotification, JsonValue } from './json-rpc-subprocess'
import { serviceLogLevel } from './service-log-level'
import {
isProxyEngine,
PROXY_ENGINES,
proxyEngineFromSource,
proxySourceForEngine,
type ProxyEngine,
type ProxyNodeSource
} from './proxy-engines'
// Live node sources are the reverse proxies, relayed through the broker, and
// the broker's consolidated discovery snapshot. Electron does not consume
// worker discovery protocols directly.
type BrokerNodeSource = ProxyNodeSource | 'broker'
/** Per-engine presence on a node — each proxy reports its own engine. */
interface EnginePresence {
up: boolean
/**
* The node's promoted inference **proxy** port for this engine, as
* advertised in discovery. Under secure inference the broker registers the
* `ol`/`lm` service at the proxy's port — never the engine's own port, which
* is loopback-private and reachable by peers only through that proxy's
* cluster-mTLS ingress. The engine's real server port is not in discovery;
* it comes from `engine:remote-get-installed` facts (a peer) or
* engine-manager status (self).
*/
port: number
version: string | null
}
/**
* Authoritative install/run facts for a remote peer's engine, read from that
* peer's cluster-scoped `ec` control surface via `engine:remote-get-installed`
* (pin-based mTLS). Unlike {@link EnginePresence} — which is inferred from mDNS
* proxy advertisement and can only ever say "up/down" — these are the peer
* engine-manager's own truth: whether it is installed, whether it is running,
* and the configured server port (present even while stopped). Only available
* for clustered, reachable peers; when absent we fall back to presence.
*/
interface RemoteEngineFacts {
installed: boolean
running: boolean
healthy: boolean
port: number
}
interface ModularNode {
// Canonical cross-domain node key = the backend's stable per-host UUID
// (`shared/nodeid`). The broker carries it on `AvailableNode.hostUuid`, the
// proxies key `Node.ID` by it, and `/v1/node-info` reports it, so every
// domain now agrees on this id: workload `originatedFrom`/`scheduledOn`,
// error `nodeId`, and proxy routing all resolve against it. Never key,
// dedupe, or attribute by hostname — that is display only (`name`).
id: string
sources: BrokerNodeSource[]
// Display hostname (broker `AvailableNode.name` / proxy `Node.Host`). Shown
// to the user; never a correlation key.
name: string
host: string
// Whether the node is a locally-trusted (pinned) peer and whether it already
// belongs to a cluster, from broker discovery (`AvailableNode.trusted` /
// `.clustered`). Absent on the proxy `node/*` feed (defaults false), so a
// proxy-sourced update keeps the last broker-reported values on merge.
// `clustered` gates invite eligibility (a node already in a cluster cannot be
// invited into another).
trusted: boolean
clustered: boolean
nodeInfoPort: number
nodeInfoUp: boolean
// The node's own ranked candidate list from broker discovery
// (`AvailableNode.ipAddresses`, or its single `ipAddress`). Authoritative and
// ordered: a broker snapshot replaces this wholesale, so an address the node
// has re-ranked away stops being polled and stops being projected. It is a
// separate field from {@link proxyAddresses} for exactly that reason — while
// the two feeds shared one list, a union was the only merge that did not
// discard the proxy's addresses, and a union can never drop anything.
brokerAddresses: string[]
// Addresses known only to the proxy `node/*` feed (`Node.Addresses`), which
// discovers independently of the broker. Projected behind the broker's order
// by {@link nodeAddresses}, and the only address list a proxy-only node has.
proxyAddresses: string[]
// The node's canonical LAN address. Both discovery sources now stamp it with
// the backend's shared `netpick.Primary` result: the broker's
// `AvailableNode.ipAddress` and the proxy `node/*` `ip` field. Used directly
// for the display IP and the node-info poll target — PAIR UI no longer ranks
// addresses itself. The broker value is preferred on merge; a proxy-only node
// carries the proxy's value. Empty only until a node's first event arrives.
reachableAddress: string
gpus: ModularGpu[]
cpu: ModularCpu | null
memory: ModularMemory | null
// Node-level list of inference-ready hardware ids from /v1/node-info, mapped
// straight to SystemTopology.inferenceHardwareIds. undefined = the backend
// does not report readiness yet (UI shows all GPUs). See the routing
// limitations in docs/services-parity.md.
inferenceHardwareIds?: string[]
// The node's unified model list, enriched by the broker daemon from the
// peer's engine-manager `/v1/models` (models-http) and carried on
// `AvailableNode.models`. It replaces the retired per-engine proxy
// `models=` TXT as the remote-node model source; the local node still prefers
// engine-manager `list_models`. Kept as the flat node-level union for the
// fallback path (a peer that sends no per-engine attribution).
models: string[]
// Per-engine attribution of the enriched model list, keyed by engine-manager
// engine name ("ollama", "lmstudio", "llamacpp"), carried on
// `AvailableNode.modelsByEngine`.
// When present it is authoritative — {@link toEngineModels} attributes each
// model to the engine that actually serves it, so a dual-engine node no
// longer blanks its cards. A present engine key with [] is known empty; an
// empty object means no successful attribution (or a peer that predates
// per-engine attribution) and falls back to {@link models}. Mirrors
// noderec.DirectoryNode.EngineModels.
modelsByEngine: Record<string, string[]>
// Per-engine set of models currently loaded in memory, keyed by
// engine-manager engine name ("ollama", "lmstudio", "llamacpp"), carried on
// `AvailableNode.loadedByEngine`. Normally a subset of
// {@link modelsByEngine}. An engine key with an empty list means
// "running, nothing loaded"; a missing key means loaded state wasn't
// reported. Drives {@link ModelItem.status} `'loaded'`. Empty object when no
// engine reports loaded state. Mirrors noderec.DirectoryNode.LoadedByEngine.
loadedByEngine: Record<string, string[]>
engines: Record<ProxyEngine, EnginePresence>
lastSeen: number
}
function emptyPresence(): EnginePresence {
return { up: false, port: 0, version: null }
}
function emptyEngines(): Record<ProxyEngine, EnginePresence> {
return {
ollama: emptyPresence(),
'lm-studio': emptyPresence(),
'llama-cpp': emptyPresence()
}
}
/** Immutably set one engine's presence, preserving the other. */
function setEngine(
engines: Record<ProxyEngine, EnginePresence>,
engine: ProxyEngine,
presence: EnginePresence
): Record<ProxyEngine, EnginePresence> {
return { ...engines, [engine]: presence }
}
/**
* A node's primary reachable service port: a live engine's promoted proxy port
* when one is up (the endpoint peers route inference to), else the node-info
* HTTP port. Display-only — never dialed directly for inference.
*/
function primaryServicePort(node: ModularNode): number {
for (const engine of PROXY_ENGINES) {
const presence = node.engines[engine]
if (presence.up && presence.port > 0) return presence.port
}
return node.nodeInfoPort
}
/** Whether any proxy engine reports the node as up. */
function anyEngineUp(node: ModularNode): boolean {
return PROXY_ENGINES.some(engine => node.engines[engine].up)
}
interface ModularGpu {
name: string
vramBytes: number
vramUsedBytes: number
utilizationPercent: number
}
interface ModularCpu {
name: string
cores: number
utilizationPercent: number
}
interface ModularMemory {
totalBytes: number
usedBytes: number
}
const appStartTime = new Date().toISOString()
function objectValue(value: JsonValue | undefined): JsonObject | null {
if (!value || typeof value !== 'object' || Array.isArray(value)) return null
return value
}
function stringValue(value: JsonValue | undefined): string {
return typeof value === 'string' ? value : ''
}
function numberValue(value: JsonValue | undefined): number {
return typeof value === 'number' ? value : 0
}
/**
* An install frame's percent, or undefined when the step is indeterminate. The
* engine-manager omits percent (or sends 0) for steps it cannot measure; each
* frame replaces the last, so a missing percent must not carry forward.
*/
function measuredPercent(value: JsonValue | undefined): number | undefined {
const pct = numberValue(value)
return pct > 0 ? pct : undefined
}
function booleanValue(value: JsonValue | undefined): boolean {
return typeof value === 'boolean' ? value : false
}
function stringArrayValue(value: JsonValue | undefined): string[] {
if (!Array.isArray(value)) return []
return value.filter((entry): entry is string => typeof entry === 'string')
}
/**
* Parse the broker `AvailableNode.modelsByEngine` map (engine name -> model
* names). A missing/malformed field yields `{}`, which {@link modelsForEngine}
* treats as "no attribution" and falls back to the flat union. Keyed by
* engine-manager engine name ("ollama", "lmstudio").
*/
function parseModelsByEngine(value: JsonValue | undefined): Record<string, string[]> {
const obj = objectValue(value)
if (!obj) return {}
const out: Record<string, string[]> = {}
for (const [engine, list] of Object.entries(obj)) {
out[engine] = stringArrayValue(list)
}
return out
}
/**
* Read an optional string array, preserving the absent vs empty distinction the
* `inference_hardware_ids` contract relies on: a missing field returns
* `undefined` (backend reports no readiness — show all GPUs), an empty array
* returns `[]` (no inference-ready hardware). See the routing limitations in
* docs/services-parity.md.
*/
function optionalStringArrayValue(value: JsonValue | undefined): string[] | undefined {
if (!Array.isArray(value)) return undefined
return value.filter((entry): entry is string => typeof entry === 'string')
}
function nullableStringValue(value: JsonValue | undefined): string | null {
return typeof value === 'string' ? value : null
}
function nullableNumberValue(value: JsonValue | undefined): number | null {
return typeof value === 'number' ? value : null
}
function serviceErrorSeverity(value: JsonValue | undefined): ServiceErrorSeverity | undefined {
return value === 'info' || value === 'warning' || value === 'error' ? value : undefined
}
function serviceErrorAction(value: JsonValue | undefined): ServiceErrorAction | undefined {
return value === 'retry' || value === 'none' || value === 'dismiss' ? value : undefined
}
function parseServiceError(value: JsonValue | undefined): ServiceError | null {
const obj = objectValue(value)
if (!obj) return null
const id = stringValue(obj.id)
const message = stringValue(obj.message)
if (!id || !message) return null
const error: ServiceError = {
id,
message,
timestamp: numberValue(obj.timestamp) || Date.now()
}
const severity = serviceErrorSeverity(obj.severity)
if (severity) error.severity = severity
const action = serviceErrorAction(obj.action)
if (action) error.action = action
const nodeId = stringValue(obj.nodeId)
if (nodeId) error.nodeId = nodeId
// The engine-manager stamps its own id (`lmstudio`); map it onto our closed
// `EngineType` union so the renderer's retry/display logic recognizes it.
// Unknown ids fall through unchanged (no retry affordance will match).
const engineType = stringValue(obj.engineType)
if (engineType) error.engineType = engineTypeFromManagerName(engineType) ?? engineType
const operation = stringValue(obj.operation)
if (operation) error.operation = operation
const modelName = stringValue(obj.modelName)
if (modelName) error.modelName = modelName
return error
}
/** Parse a `nvpair-errors` `errors:update` / `errors:get-initial` payload. */
export function parseServiceErrors(value: JsonValue | undefined): ServiceError[] {
if (!Array.isArray(value)) return []
const errors: ServiceError[] = []
for (const entry of value) {
const error = parseServiceError(entry)
if (error) errors.push(error)
}
return errors
}
/**
* Per-node proxy "upstream unreachable" warnings duplicate the node list's
* offline group, so they are never surfaced in the error UI. Backend id shape:
* `<engine>-proxy:upstream-unreachable:<nodeId>`
* (services/nvpair-proxy/proxy.go `upstreamUnreachableID`).
*/
export function isUpstreamUnreachableError(error: ServiceError): boolean {
return error.id.includes(':upstream-unreachable:')
}
const WORKLOAD_STATE_SET: ReadonlySet<string> = new Set(WorkloadStates)
function isWorkloadState(value: string): value is WorkloadState {
return WORKLOAD_STATE_SET.has(value)
}
/** Parse a workload-manager `params.workloadInfo` into a typed Workload. */
function parseWorkload(value: JsonValue | undefined): Workload | null {
const obj = objectValue(value)
if (!obj) return null
const id = stringValue(obj.id)
if (!id) return null
// The workload-manager stamps the engine-manager id (`lmstudio`); map it onto
// our closed `EngineType` union (`lm-studio`) before narrowing so LM Studio
// jobs are not silently dropped.
const engine = engineTypeFromManagerName(stringValue(obj.engine))
if (!engine) return null
const stateValue = stringValue(obj.state)
if (!isWorkloadState(stateValue)) return null
const workload: Workload = {
id,
model: stringValue(obj.model),
engine,
state: stateValue,
originatedFrom: nullableStringValue(obj.originatedFrom),
createdAt: numberValue(obj.createdAt),
startedAt: nullableNumberValue(obj.startedAt),
completedAt: nullableNumberValue(obj.completedAt),
error: nullableStringValue(obj.error),
requesterId: nullableStringValue(obj.requesterId)
}
const scheduledOn = nullableStringValue(obj.scheduledOn)
if (scheduledOn) workload.scheduledOn = scheduledOn
return workload
}
/**
* Parse a broker `workloads:get-initial` baseline (`{ workloads: workloadInfo[] }`,
* ordered by createdAt). Each element is a bare `workloadInfo` — the same shape
* carried inside a `workloads:upsert` `params.workloadInfo` — so it parses with
* {@link parseWorkload} directly. Malformed entries are skipped.
*/
export function parseWorkloadsInitial(value: JsonValue | undefined): Workload[] {
const obj = objectValue(value)
const entries = Array.isArray(obj?.workloads) ? obj.workloads : []
const workloads: Workload[] = []
for (const entry of entries) {
const workload = parseWorkload(entry)
if (workload) workloads.push(workload)
}
return workloads
}
const PENDING_OP_IDLE_TIMEOUT_MS = 90_000
// Vendor installers can be quiet for minutes; allow a bounded 30-minute window.
const INSTALL_PENDING_OP_IDLE_TIMEOUT_MS = 30 * 60_000
function pendingEngineOpIdleTimeoutMs(status: EngineProcessStatus): number {
return status === 'installing' ? INSTALL_PENDING_OP_IDLE_TIMEOUT_MS : PENDING_OP_IDLE_TIMEOUT_MS
}
/**
* The set of models a node reports loaded in memory for an engine, read from
* `ModularNode.loadedByEngine` (enriched from the backend's per-engine
* `loadedByEngine`), whose keys use the engine-manager's spelling.
*/
function loadedNamesForEngine(node: ModularNode | undefined, engineType: EngineType): Set<string> {
return new Set(node?.loadedByEngine[engineManagerName(engineType)] ?? [])
}
function sameStringList(left: string[], right: string[]): boolean {
if (left.length !== right.length) return false
for (let index = 0; index < left.length; index += 1) {
if (left[index] !== right[index]) return false
}
return true
}
/**
* Order-insensitive comparison for de-duped string lists. mDNS browses report a
* node's addresses (and TXT) in whatever order the responder returned them, so
* an order-only change must NOT count as a node change.
*/
function sameStringSet(left: string[], right: string[]): boolean {
if (left.length !== right.length) return false
const set = new Set(left)
for (const value of right) {
if (!set.has(value)) return false
}
return true
}
/** Union two address lists, de-duped, keeping the first list's order. */
function mergeAddresses(existing: string[], next: string[]): string[] {
const seen = new Set<string>()
const out: string[] = []
for (const addr of [...existing, ...next]) {
if (!addr || seen.has(addr)) continue
seen.add(addr)
out.push(addr)
}
return out
}
/**
* Every address a node is currently known to answer at: the broker's ranked
* order first, then whatever only the proxy feed reported. The single effective
* list — poll order, `NodeItem.allIpAddresses`, and `AvailableNode.ipAddresses`
* all derive from it, so none of them can outlive a broker re-rank.
*/
function nodeAddresses(node: ModularNode): string[] {
return mergeAddresses(node.brokerAddresses, node.proxyAddresses)
}
/**
* The node's primary IP for display and node-info polling. Both discovery
* sources now stamp `ModularNode.reachableAddress` with the backend's canonical
* `netpick.Primary` LAN address (the broker's `AvailableNode.ipAddress` and the
* proxy `node/*` `ip` field), so there is no local heuristic to fall
* back to; `host` only covers a node that somehow carries no canonical address.
*/
function primaryNodeAddress(node: ModularNode): string {
return node.reachableAddress || node.host
}
function mergeSources(sources: BrokerNodeSource[], source: BrokerNodeSource): BrokerNodeSource[] {
return sources.includes(source) ? sources : [...sources, source]
}
function removeSource(sources: BrokerNodeSource[], source: BrokerNodeSource): BrokerNodeSource[] {
return sources.filter(entry => entry !== source)
}
function nvidiaGpuRank(gpu: ModularGpu): number {
return gpu.name.toLowerCase().includes('nvidia') ? 0 : 1
}
function gpuArrayValue(value: JsonValue | undefined): ModularGpu[] {
if (!Array.isArray(value)) return []
const gpus: ModularGpu[] = []
for (const entry of value) {
const obj = objectValue(entry)
if (!obj) continue
gpus.push({
name: stringValue(obj.name),
vramBytes: numberValue(obj.vram_bytes),
vramUsedBytes: numberValue(obj.vram_used_bytes),
utilizationPercent: numberValue(obj.utilization_percent)
})
}
return gpus.sort((left, right) => nvidiaGpuRank(left) - nvidiaGpuRank(right))
}
function cpuValue(value: JsonValue | undefined): ModularCpu | null {
const obj = objectValue(value)
if (!obj) return null
return {
name: stringValue(obj.name),
cores: numberValue(obj.cores),
utilizationPercent: numberValue(obj.utilization_percent)
}
}
function memoryValue(value: JsonValue | undefined): ModularMemory | null {
const obj = objectValue(value)
if (!obj) return null
return {
totalBytes: numberValue(obj.total_bytes),
usedBytes: numberValue(obj.used_bytes)
}
}
function normalizeLastSeen(value: number): number {
if (value <= 0) return Date.now()
return value < 10_000_000_000 ? value * 1000 : value
}
function sameGpu(left: ModularGpu, right: ModularGpu): boolean {
return (
left.name === right.name &&
left.vramBytes === right.vramBytes &&
left.vramUsedBytes === right.vramUsedBytes &&
left.utilizationPercent === right.utilizationPercent
)
}
function sameGpuList(left: ModularGpu[], right: ModularGpu[]): boolean {
if (left.length !== right.length) return false
for (let index = 0; index < left.length; index += 1) {
if (!sameGpu(left[index], right[index])) return false
}
return true
}
function sameCpu(left: ModularCpu | null, right: ModularCpu | null): boolean {
if (!left || !right) return left === right
return (
left.name === right.name &&
left.cores === right.cores &&
left.utilizationPercent === right.utilizationPercent
)
}
function sameMemory(left: ModularMemory | null, right: ModularMemory | null): boolean {
if (!left || !right) return left === right
return left.totalBytes === right.totalBytes && left.usedBytes === right.usedBytes
}
function sameInferenceHardwareIds(left?: string[], right?: string[]): boolean {
// Preserve absent (undefined) vs empty ([]) — they mean different things.
if (!left || !right) return left === right
return sameStringList(left, right)
}
function sameTelemetry(
node: ModularNode,
gpus: ModularGpu[],
cpu: ModularCpu | null,
memory: ModularMemory | null,
inferenceHardwareIds: string[] | undefined
): boolean {
return (
sameGpuList(node.gpus, gpus) &&
sameCpu(node.cpu, cpu) &&
sameMemory(node.memory, memory) &&
sameInferenceHardwareIds(node.inferenceHardwareIds, inferenceHardwareIds)
)
}
function modelItem(name: string, loaded = false): ModelItem {
return {
name,
size: 0,
downloaded: true,
status: loaded ? 'loaded' : 'idle',
parameterSize: '',
quantization: '',
family: '',
digest: '',
sizeVram: null,
expiresAt: null,
expiry: '10m',
capabilities: []
}
}
function toNodeItem(node: ModularNode, selfId: string | null): NodeItem {
const ipAddress = primaryNodeAddress(node)
const addresses = nodeAddresses(node)
// `NodeItem.port` is the node's primary reachable service port: a live
// engine's promoted proxy port when one is up, otherwise the node-info HTTP
// port. This keeps the value meaningful regardless of which discovery source
// produced the node (a proxy reports the promoted proxy port, the broker
// reports the node-info port).
const port = primaryServicePort(node)
return {
id: node.id,
// Display label: the hostname, else the reachable address; never the raw
// UUID key (falls back to it only if a node somehow has neither).
name: node.name || ipAddress || node.id,
// The backend evicts mDNS nodes on its own (~60s of unbroken silence with
// no inference traffic from the node either), but manual nodes persist and
// report reachability via flags. Reflect that so an unreachable/sleeping
// node drops into the UI's offline group instead of lingering as an active
// card.
status: anyEngineUp(node) || node.nodeInfoUp ? 'active' : 'offline',
ipAddress,
port,
allIpAddresses: addresses.length > 0 ? addresses : [ipAddress],
topology: {
cpu: {
model: node.cpu?.name ?? '',
cores: node.cpu?.cores ?? 0,
threads: node.cpu?.cores ?? 0
},
gpus: node.gpus.map((gpu, index) => ({
id: `${node.id}:gpu:${index}`,
name: gpu.name,
vramTotal: gpu.vramBytes
})),
ram: node.memory?.totalBytes ?? 0,
storage: [],
inferenceHardwareIds: node.inferenceHardwareIds
},
// The local node's OS is known from the running process; the backend's
// discovery/node-info plane reports no OS for remote nodes, so they fall
// back to a placeholder. Remote OS is not reported by the current
// discovery/node-info contract.
os: node.id === selfId ? platformDisplayName(currentPlatform()) : 'Windows'
}
}
function toMetrics(node: ModularNode): NodeItemMetrics {
const memoryUsage =
node.memory && node.memory.totalBytes > 0
? (node.memory.usedBytes / node.memory.totalBytes) * 100
: 0
const current = {
timestamp: Date.now(),
cpuUtilization: node.cpu?.utilizationPercent ?? 0,
memoryUsage,
gpuUtilization: node.gpus.map((gpu, index) => ({
id: `${node.id}:gpu:${index}`,
value: gpu.utilizationPercent
})),
gpuVramUsage: node.gpus.map((gpu, index) => ({
id: `${node.id}:gpu:${index}`,
value: gpu.vramBytes > 0 ? (gpu.vramUsedBytes / gpu.vramBytes) * 100 : 0
}))
}
return { id: node.id, current, historical: [current] }
}
function toEngineStatus(
node: ModularNode,
engine: ProxyEngine,
proxyPort: number | null
): EngineStatusData {
const presence = node.engines[engine]
const status: EngineStatusData = {
engineType: engine,
nodeId: node.id,
processStatus: presence.up ? 'running' : 'stopped',
// Discovery advertises the promoted proxy port, never the engine's own
// (now loopback-private) port, so the engine port is unknown from a
// proxy `node/*` event; it is filled only from engine-manager facts.
enginePort: null,
// Prefer an authoritative proxy port from the caller (the local broker's
// bound port). Otherwise the port the peer advertised in discovery IS
// its promoted proxy port for this engine — never a guess.
proxyPort:
proxyPort && proxyPort > 0
? proxyPort
: presence.up && presence.port > 0
? presence.port
: null
}
if (presence.version) {
status.installedVersion = presence.version
}
return status
}
/**
* Parse a proxy `node/*` payload for a given engine. The `ollama-proxy` and
* `lmstudio-proxy` both emit the same `Node` shape (id/host/port/addresses/txt);
* the engine is determined by which relay namespace it arrived on. The presence
* is stamped onto that engine only; the other engine stays empty.
*/
function parseProxyNode(params: JsonValue | undefined, engine: ProxyEngine): ModularNode | null {
const obj = objectValue(params)
if (!obj) return null
// The proxy keys `Node.ID` by the stable per-host UUID (and rejects empty),
// so this is already the canonical node key — no TXT parsing needed.
const id = stringValue(obj.id)
if (!id) return null
const engines = emptyEngines()
engines[engine] = {
up: true,
// Under secure inference this is the peer's promoted inference proxy
// port, not the engine's own (loopback-private) port.
port: numberValue(obj.port),
// The proxy `Node` carries no version field; engine version comes from
// nvpair-engine-manager, not discovery.
version: null
}
return {
id,
sources: [proxySourceForEngine(engine)],
// `Node.Host` is the hostname; empty for the self-bridge manual node,
// in which case the broker discovery entry supplies the display name on
// merge (see mergeNode). Never fall back to the UUID id here.
name: stringValue(obj.name) || stringValue(obj.host),
host: stringValue(obj.host),
// The proxy `node/*` feed carries no trust/cluster flags; keep whatever
// the broker last reported (see mergeNode).
trusted: false,
clustered: false,
// The proxy `node/*` payload no longer carries a model list (models-http
// moved it off the mDNS TXT to the broker's `AvailableNode.models`); a
// proxy-sourced node contributes engine presence only, never models.
models: [],
modelsByEngine: {},
// A proxy `node/*` event carries no loaded-model state either; the
// broker-enriched value is preserved across the proxy merge (see mergeNode).
loadedByEngine: {},
nodeInfoPort: 0,
nodeInfoUp: false,
// A proxy `node/*` event carries no broker ranking; its `Addresses` are
// this feed's own contribution and are kept behind the broker's list.
brokerAddresses: [],
proxyAddresses: stringArrayValue(obj.addresses),
// The proxy stamps the node's canonical LAN address (netpick.Primary over
// its TXT + addresses) on the `ip` field of every node/* payload,
// so a proxy-only node carries a real reachable address instead
// of forcing PAIR UI to re-rank the raw address list itself.
reachableAddress: stringValue(obj.ip),
gpus: [],
cpu: null,
memory: null,
engines,
lastSeen: Date.now()
}
}
function parseBrokerNode(params: JsonValue | undefined): ModularNode | null {
const obj = objectValue(params)
if (!obj) return null
// `AvailableNode.hostUuid` is the canonical node key. The broker's discovery
// store rejects an empty UUID, so every node it reports carries one; a
// payload without it is malformed and dropped rather than keyed by hostname.
const hostUuid = stringValue(obj.hostUuid)
if (!hostUuid) return null
// `AvailableNode.id`/`.name` are the mDNS instance hostname (display only).
const hostname = stringValue(obj.name) || stringValue(obj.id)
const ipAddress = stringValue(obj.ipAddress) || stringValue(obj.ip_address)
const port = numberValue(obj.port)
// `AvailableNode.ipAddresses` is the node's own ranked candidate list, omitted
// when it published a single address (where it would only repeat ipAddress).
const ipAddresses = stringArrayValue(obj.ipAddresses)
const brokerAddresses = ipAddresses.length > 0 ? ipAddresses : ipAddress ? [ipAddress] : []
return {
id: hostUuid,
sources: ['broker'],
name: hostname,
host: ipAddress,
// Broker discovery is authoritative for trust/cluster membership state.
trusted: booleanValue(obj.trusted),
clustered: booleanValue(obj.clustered),
nodeInfoPort: port,
nodeInfoUp: Boolean(ipAddress) && port > 0,
brokerAddresses,
proxyAddresses: [],
// Broker `AvailableNode.ipAddress` is the head of the node's own ranked
// candidate list — one canonical address shared across broker /
// cluster-manager / errors / workload-manager, so the display IP and the
// node-info poll target agree. The backend owns the ranking and the
// failover across the rest of the list; PAIR never re-ranks.
reachableAddress: ipAddress,
gpus: [],
cpu: null,
memory: null,
// Broker `AvailableNode.models`: the node's model list, enriched by its
// daemon from the peer's engine-manager `/v1/models` (models-http). This
// is the remote-node model source now that the proxy `models=` TXT is
// retired. `omitempty` on the wire — absent when the node runs no engines.
models: stringArrayValue(obj.models),
// Broker `AvailableNode.modelsByEngine`: the same list attributed per
// engine. `omitempty` on the wire — an empty object (no engines, or a
// peer that predates per-engine attribution) drives the
// {@link modelsForEngine} fallback to the flat union.
modelsByEngine: parseModelsByEngine(obj.modelsByEngine),
// Broker `AvailableNode.loadedByEngine`: the per-engine set of models
// loaded in memory, enriched from the peer's engine-manager
// `/v1/models`. `omitempty` on the wire — absent for a peer that reports
// no loaded state, which stamps every model `idle`.
loadedByEngine: parseModelsByEngine(obj.loadedByEngine),
engines: emptyEngines(),
lastSeen: normalizeLastSeen(numberValue(obj.lastSeen) || numberValue(obj.last_seen))
}
}
function brokerNodesValue(value: JsonValue | undefined): ModularNode[] {
const obj = objectValue(value)
const entries = Array.isArray(value) ? value : Array.isArray(obj?.nodes) ? obj.nodes : []
const nodes = new Map<string, ModularNode>()
for (const entry of entries) {
const node = parseBrokerNode(entry)
if (node) nodes.set(node.id, node)
}
return Array.from(nodes.values())
}
function samePresence(left: EnginePresence, right: EnginePresence): boolean {
return left.up === right.up && left.port === right.port && left.version === right.version
}
function sameEngines(
left: Record<ProxyEngine, EnginePresence>,
right: Record<ProxyEngine, EnginePresence>
): boolean {
for (const engine of PROXY_ENGINES) {
if (!samePresence(left[engine], right[engine])) return false
}
return true
}
function sameNode(left: ModularNode, right: ModularNode): boolean {
return (
left.id === right.id &&
sameStringList(left.sources, right.sources) &&
left.name === right.name &&
left.host === right.host &&
left.trusted === right.trusted &&
left.clustered === right.clustered &&
left.reachableAddress === right.reachableAddress &&
left.nodeInfoPort === right.nodeInfoPort &&
left.nodeInfoUp === right.nodeInfoUp &&
// Order matters for the broker's list and only for it: that order is the
// node's own ranking of where to reach it, and it drives the poll order.
sameStringList(left.brokerAddresses, right.brokerAddresses) &&
sameStringSet(left.proxyAddresses, right.proxyAddresses) &&
sameTelemetry(left, right.gpus, right.cpu, right.memory, right.inferenceHardwareIds) &&
sameStringList(left.models, right.models) &&
sameModelsByEngine(left.modelsByEngine, right.modelsByEngine) &&
// A residency-only change (a model loaded/evicted with the installed set
// unchanged) must still count as a node change so the loaded dot updates.
sameModelsByEngine(left.loadedByEngine, right.loadedByEngine) &&
sameEngines(left.engines, right.engines) &&
left.lastSeen === right.lastSeen
)
}
/**
* Compare two per-engine model maps. The attribution can change while the flat
* union stays identical (e.g. a model that multiple engines now serve moved between
* the per-engine buckets), so this must be checked independently of
* {@link sameStringList} on `models` or a card would miss the re-attribution.
*/
function sameModelsByEngine(
left: Record<string, string[]>,
right: Record<string, string[]>
): boolean {
const leftKeys = Object.keys(left)
if (leftKeys.length !== Object.keys(right).length) return false
for (const key of leftKeys) {
if (!(key in right) || !sameStringList(left[key], right[key])) return false
}
return true
}
class ModularBridgeState {
private nodes = new Map<string, ModularNode>()
private brokerNodeIds = new Set<string>()
private errors: ServiceError[] = []
private workloads = new Map<string, Workload>()
private logs: LogEntry[] = []
// Per-engine bound proxy port reported by the broker. 0 = not reported yet;
// we never fabricate a default — an unknown port surfaces as null, not a
// guess. Keys map to relay sources through proxy-engines.ts.
private proxyPorts: Record<ProxyEngine, number> = {
ollama: 0,
'lm-studio': 0,
'llama-cpp': 0
}
private selfId: string | null = null
/**
* Authoritative local-engine facts from `nvpair-engine-manager`, keyed by
* engine type. Stored independent of `selfId` because engine-manager
* reports before the self node is discovered, then resolved against
* `selfId` at emit time.
*/
private engineManagerFacts = new Map<
EngineType,
{ installed: boolean; running: boolean; port: number }
>()
/**
* Local model lists pulled from `nvpair-engine-manager`'s `list_models` action by
* the supervisor. Cached so `engines:get-initial` can include them and survive
* a UI refresh, just like the engine-manager lifecycle facts above. Stored for
* every engine including the discovery engine (Ollama): for non-discovery
* engines (LM Studio, …) it is the only model source; for Ollama it is the
* complete authoritative list that {@link discoveryModelsForNode} prefers over
* the (possibly TXT-truncated) mDNS-advertised list.
*/
private localManagerModels = new Map<EngineType, ModelItem[]>()
/** Supervisor-registered hook to re-pull the local discovery engine's
* authoritative `list_models` when discovery reports its model set changed. */
private onLocalDiscoveryModelsChanged: ((engine: ProxyEngine) => void) | null = null
/**
* Optimistic transitional process status for a local engine while a
* user-initiated lifecycle op is in flight. `nvpair-engine-manager` never emits
* `starting`/`stopping`/`installing`/`uninstalling` — it only streams
* `engine:install-progress` (install only) and one terminal
* `engine:state-changed`. The UI renders its spinner/progress line solely for
* these transitional statuses, so without synthesizing them here the UI sits
* idle for the entire op. Held until the backend resolves the op (state
* change, terminal progress, or matching error), with a safety timer.
*/
private pendingEngineOps = new Map<EngineType, EngineProcessStatus>()
private pendingOpTimers = new Map<EngineType, ReturnType<typeof setTimeout>>()
/**
* Optimistic transitional status for a remote peer while a user-initiated
* `engine:remote-*` op is in flight on this node (the client). Keyed by
* `${nodeId}:${engineType}`; cleared when discovery reports the resolved
* run state or on idle timeout.
*/
private pendingRemoteEngineOps = new Map<string, EngineProcessStatus>()
private pendingRemoteOpTimers = new Map<string, ReturnType<typeof setTimeout>>()
/**
* In-flight model pulls keyed by {@link engineProgressKey}. The pull is
* dispatched fire-and-forget, so we synthesize a `pulling` progress entry on
* dispatch (so {@link IncomingSyncPullRow} renders immediately) and clear it
* when the supervisor's awaited completion resolves. While the pull runs the
* backend streams live `engine:pull-progress` frames that advance
* this entry's percent in place. Held here too so `engines:get-initial` can
* replay it after a UI refresh mid-download.
*/
private activePulls = new Map<string, EngineProgress>()
/**
* Authoritative remote-engine facts keyed by {@link remoteOpKey}
* (`${nodeId}:${engineType}`). Populated by the supervisor from each
* clustered peer's `engine:remote-get-installed` (mTLS `ec` surface) — the
* only source of a remote engine's real installed/running/port. When present
* these override the best-effort mDNS presence in
* {@link resolveRemoteEngineStatus}; when absent (an unclustered peer, or one
* not polled yet) only an active advertisement is inferred from. Kept across a
* failed poll — see `refreshRemoteEngineStatus`. Dropped when the node is
* evicted.
*/
private remoteEngineFacts = new Map<string, RemoteEngineFacts>()
/**
* The model of an in-flight remote pull keyed by {@link remoteOpKey}. The
* backend's `engine:remote-progress` frames carry **no** `model` field
* (`nvpair-engine-manager/remote.go` `remoteProgress`), so we stamp the model
* we dispatched with here and backfill it onto every incoming frame — that
* keeps the optimistic entry, the streamed percent updates, and the terminal
* clear all on one {@link engineProgressKey}. Cleared by
* {@link finishRemoteModelPull}.
*/
private remotePullModels = new Map<string, string>()
/**
* The model of an in-flight local pull keyed by `engineType`. The backend's
* `engine:pull-progress` frames (the local counterpart of
* `engine:remote-progress`) carry **no** `model` field
* (`nvpair-engine-manager/executor.go` `emitPullProgress`), so we stamp the
* model we dispatched here and backfill it onto every incoming frame — one
* active local pull per engine, matching the backend's engine-scoped
* progress hub. Set by {@link beginModelPull}, cleared by
* {@link finishModelPull}.
*/
private localPullModels = new Map<EngineType, string>()
/**
* The authoritative set of live inbound invites awaiting the local user's PIN
* entry, keyed by `inviteId`. The cluster-manager pushes `cluster:invite-received`
* exactly once per invite (always `pending`) and has no list-pending RPC, so
* main accumulates them here and prunes them as they resolve — via membership
* (`nodes:changed`), the local accept/decline result, the receiver-side
* `cluster:invite-canceled` / `cluster:invite-expired` pushes, or the per-invite
* `cluster:invite-status` sweep (the backstop for a missed push). The backend
* owns inbound-invite expiry, so there is no client-side TTL.
* Every mutation re-emits the full `cluster:pending-invites-changed` snapshot.
*/
private pendingInvites = new Map<string, Invite>()
getNodesInitial(): WsInvokeResponse<'nodes:get-initial'> {
const nodes: Record<string, NodeItem> = {}
for (const node of Array.from(this.nodes.values())) {
nodes[node.id] = toNodeItem(node, this.selfId)
}
return {
nodes,
fetchedNodes: true
}
}
getSelfId(): string | null {
return this.selfId
}
/**
* The display hostname for a node key (UUID), or '' when unknown. Used as a
* last-resort manual-removal key when address matching finds no persisted
* entry (see {@link resolveManualNodeKey}).
*/
getNodeHostname(nodeId: string): string {
return this.nodes.get(nodeId)?.name ?? ''
}
/**
* Every address a node key (UUID) is known to be reachable at — its
* canonical `reachableAddress`, its discovered addresses, and its `host`.
* Used to map a UUID back to the manual-nodes store entry (keyed by the
* user-entered address) when removing a manual node. Empty for an unknown id.
*/
getNodeAddresses(nodeId: string): string[] {
const node = this.nodes.get(nodeId)
if (!node) return []
const out = new Set<string>()
if (node.reachableAddress) out.add(node.reachableAddress)
for (const address of nodeAddresses(node)) out.add(address)
if (node.host) out.add(node.host)
return Array.from(out)
}
/** The authoritative live inbound invites awaiting a PIN, oldest first. */
getPendingInvites(): Invite[] {
return Array.from(this.pendingInvites.values()).sort((a, b) => a.createdAt - b.createdAt)
}
/**
* Record a freshly-arrived inbound invite (from `cluster:invite-received`).
* Only `pending` invites are actionable; a non-pending arrival prunes any
* stored copy instead. Re-emits the snapshot when the set changes.
*/
addPendingInvite(invite: Invite): void {
if (invite.state !== 'pending' || !invite.inviteId) {
this.prunePendingInvite(invite.inviteId)
return
}
this.pendingInvites.set(invite.inviteId, invite)
this.emitPendingInvites()
}
/** Drop a single invite by id (resolved, evicted, or expired). */
prunePendingInvite(inviteId: string): void {
if (this.pendingInvites.delete(inviteId)) this.emitPendingInvites()
}
/**
* Drop any pending invite whose inviter is now a confirmed `member` — the
* pairing completed (`nodes:changed`), so the PIN prompt is obsolete.
*/
reconcilePendingInvitesWithMembers(members: ClusterNode[]): void {
if (this.pendingInvites.size === 0) return
const memberUuids = new Set(members.filter(m => m.state === 'member').map(m => m.nodeUuid))
let changed = false
for (const invite of Array.from(this.pendingInvites.values())) {
if (memberUuids.has(invite.fromNodeUuid)) {
this.pendingInvites.delete(invite.inviteId)
changed = true
}
}
if (changed) this.emitPendingInvites()
}
private emitPendingInvites(): void {
emitBridgePush('cluster:pending-invites-changed', this.getPendingInvites())
}
/**
* Fix the local node id to the cluster-manager's stable node UUID
* (`cluster:get-node-id` → `nodeUuid`). This is the sole self-identity
* source: discovery and proxy ids are the same UUID key, so there is no
* hostname guessing to guard against. A no-op when unchanged; a change
* triggers a renderer refresh so per-node views re-resolve self.
*/
setSelfId(nodeUuid: string): void {
const trimmed = nodeUuid.trim()
if (!trimmed || this.selfId === trimmed) return
this.selfId = trimmed
emitBridgePush('state:request-refresh', undefined)
}
/** Bound proxy port for an engine reported by the broker, or null if unknown. */
getProxyPort(engine: ProxyEngine): number | null {
const port = this.proxyPorts[engine]
return port > 0 ? port : null
}
getEngineInitialState(): EngineInitialState {
const statuses: EngineStatusData[] = []
const models: EngineModels[] = []
// Local engines (self): every engine `nvpair-engine-manager` reports,
// proxy-fronted or not. engine-manager is authoritative for the local
// node's install/run state; proxy-engine models prefer its cached
// `list_models` and fall back to discovery. Emitted here (not in the
// per-node loop) so they survive a UI refresh even before the self node
// is discovered.
const selfId = this.selfId
for (const engineType of Array.from(this.engineManagerFacts.keys())) {
const selfNode = selfId ? this.nodes.get(selfId) : undefined
const status = this.resolveLocalEngineStatus(engineType, selfNode)
if (status) statuses.push(status)
if (!selfId) continue
if (isProxyEngine(engineType)) {
models.push(this.discoveryModelsForNode(selfNode, engineType, selfId))
} else {
const cached = this.localManagerModels.get(engineType)
if (cached) {
const loaded = loadedNamesForEngine(selfNode, engineType)
models.push({
engineType,
nodeId: selfId,
models: cached.map(item => ({
...item,
status: loaded.has(item.name) ? 'loaded' : 'idle'
}))
})
}
}
}
// Remote nodes: per proxy-engine status + models from discovery. Status
// prefers the authoritative `engine:remote-get-installed` facts (mTLS)
// over the inferred presence, and is omitted entirely when neither is
// known — see {@link resolveRemoteEngineStatus}.
for (const node of Array.from(this.nodes.values())) {
if (node.id === selfId) continue
for (const engine of PROXY_ENGINES) {
const status = this.resolveRemoteEngineStatus(node.id, engine)
if (status) statuses.push(status)
models.push(this.toEngineModels(node, engine))
}
}
return {
statuses,
models,
activeProgress: Array.from(this.activePulls.values()),
updateAvailable: []
}
}
getAvailableNodes(): WsInvokeResponse<'discovery:get-nodes'> {
return Array.from(this.nodes.values()).map(node => {
const addresses = nodeAddresses(node)
return {
id: node.id,
// Display label: hostname, else reachable address; never the raw UUID.
name: node.name || primaryNodeAddress(node) || node.id,
ipAddress: primaryNodeAddress(node),
// Only for a genuinely multi-homed node: a one-entry list would just
// repeat ipAddress.
...(addresses.length > 1 ? { ipAddresses: addresses } : {}),
port: node.nodeInfoPort > 0 ? node.nodeInfoPort : primaryServicePort(node),
lastSeen: node.lastSeen,
// Invite eligibility: a node already in a cluster cannot be invited
// into another; `trusted` marks an already-pinned peer.
trusted: node.trusted,
clustered: node.clustered
}
})
}
getNodeInfoPollTargets(): { id: string; hosts: string[]; port: number }[] {
const targets: { id: string; hosts: string[]; port: number }[] = []
for (const node of Array.from(this.nodes.values())) {
if (!node.nodeInfoUp || node.nodeInfoPort <= 0) continue
// This machine appears in its own discovery snapshot, but its own
// node-info is on this machine: loopback reaches it without depending
// on the host's inbound path. Loopback alone, with no failover — the
// addresses it advertises are longer routes to the listener loopback
// just reached, so asking them after loopback fails only spends
// connections.
if (node.id === this.selfId) {
targets.push({
id: node.id,
hosts: [MODULAR_NODE_INFO_SELF_HOST],
port: node.nodeInfoPort
})
continue
}
// Lead with the canonical display address, then retain the node's
// published alternatives. The poller walks them in order and verifies
// hostUuid, so a direct-connect address that resolves to another host
// cannot hide telemetry available at a later address.
const hosts = mergeAddresses([primaryNodeAddress(node)], nodeAddresses(node))
if (hosts.length === 0) continue
targets.push({ id: node.id, hosts, port: node.nodeInfoPort })
}
return targets
}
mergeNodeInfoResponse(nodeId: string, response: JsonValue): void {
const node = this.nodes.get(nodeId)
if (!node) return
const obj = objectValue(response)
if (!obj) return
// `/v1/node-info` now reports the node's own hostUuid. If it disagrees
// with the node we polled (the address resolved to a different host),
// skip the merge rather than attribute another host's telemetry here.
const reportedUuid = stringValue(obj.hostUuid)
if (reportedUuid && reportedUuid !== nodeId) return
const gpus = gpuArrayValue(obj.GPUs)
const cpu = cpuValue(obj.cpu)
const memory = memoryValue(obj.memory)
const inferenceHardwareIds = optionalStringArrayValue(obj.inference_hardware_ids)
if (node.nodeInfoUp && sameTelemetry(node, gpus, cpu, memory, inferenceHardwareIds)) {
emitBridgePush('metrics:update', toMetrics(node))
return
}
this.upsertNode({
...node,
gpus,
cpu,
memory,
inferenceHardwareIds,
nodeInfoUp: true
})
}
getErrors(): ServiceError[] {
return [...this.errors]
}
/**
* Authoritative replace from `nvpair-errors` `errors:update`.
*
* Errors are pushed to whichever windows are open and are replayed from
* `errors:get-initial` when Overview is opened later. They never raise or
* focus a window: an error the user did not ask about must not interrupt
* what they are doing.
*/
replaceErrors(errors: ServiceError[]): void {
this.errors = [...errors]
emitBridgePush('errors:update', [...this.errors])
}
/** Local fallback upsert used only when `nvpair-errors` is not running. */
upsertError(error: ServiceError): void {
this.errors = [error, ...this.errors.filter(existing => existing.id !== error.id)].slice(
0,
200
)
emitBridgePush('errors:update', [...this.errors])
}
clearError(id: string): void {
this.errors = this.errors.filter(error => error.id !== id)
emitBridgePush('errors:update', [...this.errors])
}
getWorkloads(): WsInvokeResponse<'workloads:get-initial'> {
const workloads: Record<string, Workload> = {}
for (const [key, workload] of this.workloads) {
workloads[key] = workload
}
return workloads
}
/**
* Seed the catalog from a broker `workloads:get-initial` baseline and return
* the full current map. Adds each entry (keyed by `(originatedFrom, id)`)
* only when the key is absent, rather than clearing or overwriting: a live
* `workloads:upsert` that already landed at that key (the realtime stream is
* at least as fresh as this durable snapshot) is preserved, and the baseline
* only fills in jobs the stream has not delivered yet. No push is emitted —
* the caller (renderer / CLI) receives the seeded snapshot as the invoke
* response and observes subsequent changes on the push stream.
*/
seedWorkloads(workloads: Workload[]): WsInvokeResponse<'workloads:get-initial'> {
for (const workload of workloads) {
const key = workloadKey(workload.originatedFrom, workload.id)
if (!this.workloads.has(key)) this.workloads.set(key, workload)
}
return this.getWorkloads()
}
/** Relay a broker `workloads:upsert` (`{ workloadInfo }`) into the catalog + UI. */
upsertWorkloadFromInfo(params: JsonValue | undefined): void {
const obj = objectValue(params)
const workload = parseWorkload(obj?.workloadInfo)
if (!workload) return
this.workloads.set(workloadKey(workload.originatedFrom, workload.id), workload)
emitBridgePush('workloads:upsert', workload)
}
/** Relay a broker `workloads:remove` (`{ workloadId, originatedFrom? }`) into the catalog + UI. */
removeWorkloadFromParams(params: JsonValue | undefined): void {
const obj = objectValue(params)
const workloadId = stringValue(obj?.workloadId)
if (!workloadId) return
const originatedFrom = nullableStringValue(obj?.originatedFrom)
this.workloads.delete(workloadKey(originatedFrom, workloadId))
emitBridgePush('workloads:remove', { workloadId, originatedFrom })
}
/** Push a `workloads:remove` for an entry and drop it from the catalog. */
private evictWorkload(key: string, workload: Workload): void {
this.workloads.delete(key)
emitBridgePush('workloads:remove', {
workloadId: workload.id,
originatedFrom: workload.originatedFrom
})
}
/**
* Drop every workload that touched a remote peer (originated on or scheduled
* on a node other than this one). Called when the local node leaves a cluster
* (clusterId cleared): the peers are gone, so their jobs must not linger in the
* catalog or be re-served by `workloads:get-initial` on the next refresh.
* Purely-local jobs (origin + schedule self/unset) are kept.
*/
dropRemoteWorkloads(): void {
const selfId = this.selfId
const isRemoteNode = (nodeId: string | null | undefined): boolean =>
nodeId !== null && nodeId !== undefined && nodeId !== selfId
for (const [key, workload] of Array.from(this.workloads)) {
if (!isRemoteNode(workload.originatedFrom) && !isRemoteNode(workload.scheduledOn)) {
continue
}
this.evictWorkload(key, workload)
}
}
/**
* Empty the entire workload catalog. Called on backend restart to drop
* anything that ended (or whose tracking proxy died) during the restart,
* which would otherwise linger forever in this map. Emits a `workloads:remove`
* per entry so both the renderer and CLI `workloads watch` clear immediately;
* the supervisor then re-seeds from the broker's durable `workloads:get-initial`
* baseline and the live `workloads:upsert` stream repopulates from there.
*/
clearWorkloads(): void {
for (const [key, workload] of Array.from(this.workloads)) {
this.evictWorkload(key, workload)
}
}
/**
* Record a `nvpair-engine-manager` `engine:state-changed` (or hydrated
* `engine:get-installed` entry). Facts are kept regardless of whether the
* self node is known yet; `setSelfId` triggers a refresh once it resolves.
*/
applyEngineManagerStatus(params: JsonValue | undefined): void {
const obj = objectValue(params)
if (!obj) return
const engineType = engineTypeFromManagerName(stringValue(obj.engine))
if (!engineType) return
this.engineManagerFacts.set(engineType, {
installed: booleanValue(obj.installed),
running: booleanValue(obj.running),
port: numberValue(obj.port)
})
// A fresh authoritative state is the resolution of whatever op was in
// flight (start/stop done, install `done`+installed, uninstall removed).
// Drop the optimistic status without re-emitting here — the emit below
// already carries the resolved, fact-derived status.
this.discardPendingOp(engineType)
this.emitLocalEngineStatus(engineType)
}
/**
* Begin an optimistic transitional status for a local-engine lifecycle op so
* the UI shows a spinner / progress line immediately. The backend never emits
* these intermediate states; it resolves the op later via
* `engine:state-changed`, a terminal `engine:install-progress` stage, or a
* matching `errors:report`, each of which clears the optimistic status.
*/
beginLocalEngineOp(engineType: EngineType, status: EngineProcessStatus): void {
if (!this.selfId) return
this.pendingEngineOps.set(engineType, status)
this.armPendingOpTimer(engineType, status)
this.emitLocalEngineStatus(engineType)
}
/**
* Clear a pending op when its lifecycle operation fails with an
* `errors:report` that carries no `engine:state-changed` (LM Studio
* start-command failure, uninstall failure, install failure). Called by the
* supervisor's error demux. `operation` is the engine-manager error's
* `operation` field (`start` | `install` | `uninstall`).
*/
failLocalEngineOp(engineManagerEngine: string, operation: string): void {
if (operation !== 'start' && operation !== 'install' && operation !== 'uninstall') return
const engineType =
engineTypeFromManagerName(engineManagerEngine) ??
(isEngineType(engineManagerEngine) ? engineManagerEngine : null)
if (!engineType) return
this.clearLocalEngineOp(engineType)
}
/**
* Clear an optimistic op when a fire-and-forget lifecycle send never reaches
* the backend (process down / write rejected), so no resolving
* `engine:state-changed` or `errors:report` will ever arrive. Unlike
* {@link failLocalEngineOp} this is keyed directly by `EngineType` and covers
* every op (including `stopping`), since the caller already knows the engine.
*/
clearPendingEngineOp(engineType: EngineType): void {
this.clearLocalEngineOp(engineType)
}
private armPendingOpTimer(engineType: EngineType, status: EngineProcessStatus): void {
const existing = this.pendingOpTimers.get(engineType)
if (existing) clearTimeout(existing)
this.pendingOpTimers.set(
engineType,
setTimeout(
() => this.clearLocalEngineOp(engineType),
pendingEngineOpIdleTimeoutMs(status)
)
)
}
/** Drop a pending op + its timer without emitting (caller emits). */
private discardPendingOp(engineType: EngineType): void {
const timer = this.pendingOpTimers.get(engineType)
if (timer) {
clearTimeout(timer)
this.pendingOpTimers.delete(engineType)
}
this.pendingEngineOps.delete(engineType)
}
/** Drop a pending op and re-emit the now fact-derived status. */
private clearLocalEngineOp(engineType: EngineType): void {
if (!this.pendingEngineOps.has(engineType)) {
this.discardPendingOp(engineType)
return
}
this.discardPendingOp(engineType)
this.emitLocalEngineStatus(engineType)
}
private remoteOpKey(nodeId: string, engineType: EngineType): string {
return `${nodeId}:${engineType}`
}
/**
* Whether a remote peer's proxy-engine is currently reported as running.
* Mirrors {@link resolveRemoteEngineStatus}: authoritative facts are used
* alone when present, and the coarser per-engine mDNS proxy presence
* (`up`/`down`) is the fallback only for a peer with no facts, so the toggle
* decision matches the displayed status.
*/
isRemoteEngineRunning(nodeId: string, engineType: EngineType): boolean {
if (!isProxyEngine(engineType)) return false
const facts = this.remoteEngineFacts.get(this.remoteOpKey(nodeId, engineType))
if (facts) return facts.running
const node = this.nodes.get(nodeId)
if (!node || node.clustered || node.trusted) return false
return node.engines[engineType].up
}
beginRemoteEngineOp(nodeId: string, engineType: EngineType, status: EngineProcessStatus): void {
const key = this.remoteOpKey(nodeId, engineType)
this.pendingRemoteEngineOps.set(key, status)
this.armPendingRemoteOpTimer(nodeId, engineType, status)
this.emitRemoteEngineStatus(nodeId, engineType)
}
clearPendingRemoteEngineOp(nodeId: string, engineType: EngineType): void {
this.clearRemoteEngineOp(nodeId, engineType)
}
beginRemoteModelPull(nodeId: string, engineType: EngineType, model: string): void {
const node = this.nodes.get(nodeId)
const progress: EngineProgress = {
engineType,
nodeId,
nodeName: node?.name ?? nodeId,
operation: 'pull',
model,
status: 'pulling'
}
// Remember the model so the model-less `engine:remote-progress` frames can
// be re-associated with this exact entry (see remotePullModels).
this.remotePullModels.set(this.remoteOpKey(nodeId, engineType), model)
this.activePulls.set(engineProgressKey(progress), progress)
emitBridgePush('engines:progress-changed', progress)
}
/** Whether an optimistic remote pull entry for this model is still in flight. */
isRemoteModelPullActive(nodeId: string, engineType: EngineType, model: string): boolean {
return this.activePulls.has(
engineProgressKey({ nodeId, engineType, operation: 'pull', model })
)
}
/**
* Clear the optimistic remote pull entry once the awaited
* `engine:remote-pull-model` RPC settles. The backend emits **no** terminal
* `engine:remote-progress` for a pull (the peer's terminal stream frame
* becomes the JSON-RPC reply, never a notification —
* `nvpair-engine-manager/controlstream.go`), so this awaited-completion clear
* is the only signal that removes the spinner.
*/
finishRemoteModelPull(nodeId: string, engineType: EngineType, model: string): void {
this.remotePullModels.delete(this.remoteOpKey(nodeId, engineType))
const key = engineProgressKey({ nodeId, engineType, operation: 'pull', model })
if (!this.activePulls.delete(key)) return
emitBridgePush('engines:progress-cleared', { key })
}
applyRemoteEngineProgress(params: JsonValue | undefined): void {
const obj = objectValue(params)
if (!obj) return
const nodeId = stringValue(obj.node)
const engineType = engineTypeFromManagerName(stringValue(obj.engine))
if (!nodeId || !engineType) return
const op = stringValue(obj.op)
const operation = op === 'pull' || op === 'pull_model' ? 'pull' : 'install'
const stage = stringValue(obj.stage) || 'working'
// `engine:remote-progress` carries no `model`, so for a pull we backfill
// the model captured at dispatch — otherwise the frame would emit under a
// different key than the optimistic entry and never update/clear it.
const model =
stringValue(obj.model) ||
(operation === 'pull'
? (this.remotePullModels.get(this.remoteOpKey(nodeId, engineType)) ?? '')
: '')
if (stage === 'done' || stage === 'already-installed' || stage === 'failed') {
const progressKey =
operation === 'pull' && model
? engineProgressKey({ nodeId, engineType, operation: 'pull', model })
: `${nodeId}:${engineType}:${operation}`
emitBridgePush('engines:progress-cleared', { key: progressKey })
if (operation === 'pull') {
this.remotePullModels.delete(this.remoteOpKey(nodeId, engineType))
if (model) {
this.activePulls.delete(
engineProgressKey({ nodeId, engineType, operation: 'pull', model })
)
}
}
if (stage === 'already-installed' || stage === 'failed') {
this.clearRemoteEngineOp(nodeId, engineType)
}
if (stage === 'done' && operation === 'install') {
this.clearRemoteEngineOp(nodeId, engineType)
}
return
}
if (
operation === 'install' &&
this.pendingRemoteEngineOps.get(this.remoteOpKey(nodeId, engineType)) !== 'installing'
) {
this.pendingRemoteEngineOps.set(this.remoteOpKey(nodeId, engineType), 'installing')
this.emitRemoteEngineStatus(nodeId, engineType)
}
if (operation === 'install') {
this.armPendingRemoteOpTimer(nodeId, engineType, 'installing')
}
const node = this.nodes.get(nodeId)
const pullKey =
operation === 'pull' && model
? engineProgressKey({ nodeId, engineType, operation: 'pull', model })
: ''
const existingPull = pullKey ? this.activePulls.get(pullKey) : undefined
const percent =
operation === 'pull'
? mergePullProgressPercent(numberValue(obj.percent), existingPull?.percent)
: measuredPercent(obj.percent)
const progress: EngineProgress = {
engineType,
nodeId,
nodeName: node?.name ?? nodeId,
operation,
status: stage,
percent,
model: model || undefined
}
if (operation === 'pull' && model) {
this.activePulls.set(engineProgressKey(progress), progress)
}
emitBridgePush('engines:progress-changed', progress)
}
private armPendingRemoteOpTimer(
nodeId: string,
engineType: EngineType,
status: EngineProcessStatus
): void {
const key = this.remoteOpKey(nodeId, engineType)
const existing = this.pendingRemoteOpTimers.get(key)
if (existing) clearTimeout(existing)
this.pendingRemoteOpTimers.set(
key,
setTimeout(
() => this.clearRemoteEngineOp(nodeId, engineType),
pendingEngineOpIdleTimeoutMs(status)
)
)
}
private discardPendingRemoteOp(nodeId: string, engineType: EngineType): void {
const key = this.remoteOpKey(nodeId, engineType)
const timer = this.pendingRemoteOpTimers.get(key)
if (timer) {
clearTimeout(timer)
this.pendingRemoteOpTimers.delete(key)
}
this.pendingRemoteEngineOps.delete(key)
}
private clearRemoteEngineOp(nodeId: string, engineType: EngineType): void {
if (!this.pendingRemoteEngineOps.has(this.remoteOpKey(nodeId, engineType))) {
this.discardPendingRemoteOp(nodeId, engineType)
return
}
this.discardPendingRemoteOp(nodeId, engineType)
this.emitRemoteEngineStatus(nodeId, engineType)
}
private maybeClearRemotePendingFromDiscovery(
nodeId: string,
engine: ProxyEngine,
node: ModularNode
): void {
const pending = this.pendingRemoteEngineOps.get(this.remoteOpKey(nodeId, engine))
if (!pending) return
const up = node.engines[engine].up
if (pending === 'starting' && up) {
this.discardPendingRemoteOp(nodeId, engine)
} else if (pending === 'stopping' && !up) {
this.discardPendingRemoteOp(nodeId, engine)
} else if (pending === 'installing' && up) {
this.discardPendingRemoteOp(nodeId, engine)
}
}
private emitRemoteEngineStatus(nodeId: string, engineType: EngineType): void {
if (!isProxyEngine(engineType)) return
if (!this.nodes.has(nodeId)) return
// Re-emit models alongside status: authoritative facts arriving here can
// flip which engine is the single active one, which changes model
// attribution ({@link modelsForEngine}). Without this the list would stay
// stale until the next node-change event. When install/run state is
// unknown, push `initializing` so a prior inferred `stopped` is retracted
// from the renderer store (the compact row hides that placeholder).
emitBridgePush('engines:state-changed', {
nodeId,
engineType,
status: this.remoteEngineStatusForPush(nodeId, engineType),
models: this.discoveryModelsForNode(this.nodes.get(nodeId), engineType, nodeId)
})
}
/**
* Status to publish for a remote peer engine. Returns an `initializing`
* placeholder when nothing is known so stale inferred state is cleared
* without asserting installed-but-off.
*/
private remoteEngineStatusForPush(nodeId: string, engine: ProxyEngine): EngineStatusData {
const status = this.resolveRemoteEngineStatus(nodeId, engine)
return status ?? emptyEngineStatus(nodeId, engine)
}
/**
* Build a remote peer's engine status, in precedence order:
* 1. an in-flight transitional op (`starting`/`installing`/…) — the
* optimistic spinner while a user action is pending;
* 2. authoritative `engine:remote-get-installed` facts (mTLS `ec`) — the
* only source of a peer's real installed/not-installed/port;
* 3. best-effort per-engine mDNS proxy presence — all an
* unclustered/unreachable peer can offer.
* Facts decide install/run state and the engine port. Proxy presence is
* per-engine (each relay adds/removes its peer as that engine becomes
* reachable), but it is coarser than facts: it only says `up`/`down`, so it
* cannot tell `stopped` from `not-installed` and never carries the engine's
* own port. Facts are the peer engine-manager's own truth, so they win
* outright for status/engine-port; an advertisement with no facts is still
* positive evidence of a running engine. A just-started engine lands
* immediately because {@link applyRemoteEngineStatusResult} writes the toggle
* RPC's `EngineStatus` into facts, and the `pendingRemoteEngineOps` overlay
* covers the gap before that.
*
* Returns **null** when nothing is known: no facts and no advertisement. An
* absent advertisement is not evidence — it cannot distinguish a stopped
* engine from one that was never installed — so no status is asserted and
* the renderer renders the peer engine as unavailable rather than as an
* installed-but-off toggle.
*
* The peer's promoted **proxy** port IS carried in discovery (the `ol`/`lm`
* advertisement points at the proxy), so it is surfaced as `proxyPort` from
* that per-engine presence regardless of facts.
* The peer's engine port stays private (loopback) and comes only from facts;
* the LOCAL proxy port is never attributed to a peer.
*/
private resolveRemoteEngineStatus(
nodeId: string,
engine: ProxyEngine
): EngineStatusData | null {
const node = this.nodes.get(nodeId)
const presence = node?.engines[engine]
const facts = this.remoteEngineFacts.get(this.remoteOpKey(nodeId, engine))
const pending = this.pendingRemoteEngineOps.get(this.remoteOpKey(nodeId, engine))
let base: EngineStatusData | null = null
if (facts) {
base = {
engineType: engine,
nodeId,
processStatus: facts.running
? 'running'
: facts.installed
? 'stopped'
: 'not-installed',
// Only the peer engine-manager's own port is a real engine port;
// the discovery presence port is the proxy, so never fall back to
// it for the engine port.
enginePort: facts.installed && facts.port > 0 ? facts.port : null,
// The peer's promoted proxy port, when its engine is advertised.
proxyPort: presence?.up && presence.port > 0 ? presence.port : null
}
} else if (node && presence?.up && !node.clustered && !node.trusted) {
// A live advertisement means the engine is reachable and serving, so
// `running` is sound even without facts — for an unclustered peer that
// cannot be polled over ec. Clustered / pinned members must wait for
// `engine:remote-get-installed` facts so a routable proxy overlay does
// not masquerade as install/run truth (and cannot distinguish stopped
// from not-installed).
base = toEngineStatus(node, engine, null)
}
if (base && presence?.version) base.installedVersion = presence.version
if (!pending) return base
// A user-initiated remote op shows its optimistic status even while the
// underlying state is still unknown.
return base
? { ...base, processStatus: pending }
: {
engineType: engine,
nodeId,
processStatus: pending,
enginePort: null,
proxyPort: null
}
}
/**
* Apply a peer's full `engine:remote-get-installed` response
* (`{ engines: EngineStatus[] }` from its `ec` `/v1/engines`). Stores facts
* for each proxy engine and re-emits status so installed/running/port reflect
* the peer's own truth rather than inferred presence.
*/
applyRemoteEngineFacts(nodeId: string, result: JsonValue | undefined): void {
const obj = objectValue(result)
const list = obj?.engines
if (!Array.isArray(list)) return
const seen = new Set<ProxyEngine>()
for (const entry of list) {
const engineObj = objectValue(entry)
if (!engineObj) continue
const engineType = engineTypeFromManagerName(stringValue(engineObj.engine))
if (!engineType || !isProxyEngine(engineType)) continue
this.remoteEngineFacts.set(this.remoteOpKey(nodeId, engineType), {
installed: booleanValue(engineObj.installed),
running: booleanValue(engineObj.running),
healthy: booleanValue(engineObj.healthy),
port: numberValue(engineObj.port)
})
seen.add(engineType)
}
for (const engine of PROXY_ENGINES) {
if (!seen.has(engine)) {
this.remoteEngineFacts.delete(this.remoteOpKey(nodeId, engine))
}
this.emitRemoteEngineStatus(nodeId, engine)
}
}
/**
* Apply the single `EngineStatus` returned by `engine:remote-start` /
* `engine:remote-stop`, so a toggled remote engine's resolved run state lands
* immediately instead of waiting on the next facts poll or mDNS flip.
*/
applyRemoteEngineStatusResult(
nodeId: string,
engineType: EngineType,
result: JsonValue | undefined
): void {
if (!isProxyEngine(engineType)) return
const obj = objectValue(result)
if (!obj) return
this.remoteEngineFacts.set(this.remoteOpKey(nodeId, engineType), {
installed: booleanValue(obj.installed),
running: booleanValue(obj.running),
healthy: booleanValue(obj.healthy),
port: numberValue(obj.port)
})
this.emitRemoteEngineStatus(nodeId, engineType)
}
/** Forget a node's authoritative remote-engine facts (on eviction/leave). */
private dropRemoteEngineFacts(nodeId: string): void {
for (const engine of PROXY_ENGINES) {
this.remoteEngineFacts.delete(this.remoteOpKey(nodeId, engine))
this.remotePullModels.delete(this.remoteOpKey(nodeId, engine))
}
}
/**
* Resolve which local engine (if any) needs its models pulled from
* engine-manager's `list_models` action for a given engine-manager engine
* id. Returns null only for unknown engines — **the discovery engine (Ollama)
* is included.** Its mDNS advertisement carries no model list (the proxy
* `node/*` TXT is empty), so engine-manager's `/api/tags` is the only working
* source for the local node's Ollama models. `setLocalEngineModels` scopes the
* result to the local node, so remote nodes keep their discovery-derived lists
* — no double-sourcing.
*/
modelPullTarget(engineManagerEngine: string): EngineType | null {
return engineTypeFromManagerName(engineManagerEngine)
}
/**
* Registered by the supervisor. Invoked with the affected proxy engine when
* discovery reports the local node's model set for that engine changed, so the
* supervisor can re-pull the complete, authoritative `list_models` (TXT can
* truncate; a pull/delete on an already-running engine emits no
* `engine:state-changed`).
*/
setLocalDiscoveryModelRefresher(fn: (engine: ProxyEngine) => void): void {
this.onLocalDiscoveryModelsChanged = fn
}
/**
* Cache and push the local node's model list for a non-discovery engine.
* Called by the supervisor after a `list_models` pull (or with an empty list
* when the engine is stopped, since its HTTP `list_models` is unreachable).
*/
setLocalEngineModels(engineType: EngineType, modelNames: string[]): void {
const nodeId = this.selfId
// Stamp `'loaded'` from the self node's loaded set so a `list_models`
// refresh (pull/lifecycle) preserves residency instead of resetting every
// row to idle. The loaded set is seeded by discovery self-enrichment and
// kept fresh by {@link applyLocalLoadedModels}.
const loaded = loadedNamesForEngine(nodeId ? this.nodes.get(nodeId) : undefined, engineType)
const items = modelNames.map(name => modelItem(name, loaded.has(name)))
this.localManagerModels.set(engineType, items)
if (!nodeId) return
emitBridgePush('engines:state-changed', {
nodeId,
engineType,
models: { engineType, nodeId, models: items }
})
}
/**
* Update the local node's per-engine loaded-in-memory model set from an
* `engine:models-changed` push and re-publish the affected local
* engines, so an explicit load/unload, LM Studio JIT auto-load, or TTL/idle
* eviction reflects immediately instead of waiting for the next discovery
* model-refresh sweep. The push carries the full `engine:models` snapshot, so
* the whole loaded map is replaced: an engine absent from `loadedByEngine` is
* not running / not queryable and therefore has nothing loaded. Discovery
* self-enrichment (`AvailableNode.loadedByEngine` over the loopback
* `/v1/models`) remains the seed and backstop until the self node is
* discovered.
*/
applyLocalLoadedModels(loadedByEngine: Record<string, string[]>): void {
const nodeId = this.selfId
if (!nodeId) return
const node = this.nodes.get(nodeId)
// Before the self node is discovered there is nothing to stamp against;
// discovery seeds the loaded set when the node arrives.
if (!node) return
if (sameModelsByEngine(node.loadedByEngine, loadedByEngine)) return
const next: ModularNode = { ...node, loadedByEngine }
this.nodes.set(nodeId, next)
// Loaded state feeds only the engine model rows (node identity, metrics,
// and the invite-only discovery snapshot are unaffected), so re-emit just
// the per-engine model patches.
for (const engine of PROXY_ENGINES) {
const status =
this.resolveLocalEngineStatus(engine, next) ??
toEngineStatus(next, engine, this.getProxyPort(engine))
emitBridgePush('engines:state-changed', {
nodeId,
engineType: engine,
status,
models: this.discoveryModelsForNode(next, engine, nodeId)
})
}
}
/**
* Drop the local node's cached engine-manager model override for a proxy
* engine and re-publish the discovery-derived list. Used when engine-manager
* cannot supply an initial `list_models` inventory (for example an external
* engine it has not adopted), or when a stopped-state empty sentinel must be
* released after restart. Clearing the override lets discovery be the source
* of truth rather than blanking the UI with an empty list.
*/
fallbackLocalEngineModelsToDiscovery(engine: ProxyEngine): void {
this.localManagerModels.delete(engine)
const nodeId = this.selfId
if (!nodeId) return
const models = this.discoveryModelsForNode(this.nodes.get(nodeId), engine, nodeId)
emitBridgePush('engines:state-changed', {
nodeId,
engineType: engine,
models
})
}
/**
* Whether an engine is "active" on a node for the purpose of model
* attribution, resolved from the authoritative engine-manager running fact
* (`engineManagerFacts` for the local node, `remoteEngineFacts` from
* `engine:remote-get-installed`/mTLS for a clustered peer) with best-effort
* mDNS proxy `up` presence used only as a fallback.
*
* Remote peers prefer facts over proxy presence for attribution. Presence is
* per-engine but coarse — it only says the peer is reachable for that engine,
* not which engine actually serves a given model. For a pre-attribution peer
* that sends no `modelsByEngine`, whenever multiple engines are momentarily `up`,
* leaning on presence makes multiple engines look "active" at once, which defeats
* the single-active-engine attribution in {@link modelsForEngine} and blanks
* the model list. So once a peer's authoritative facts exist they are the sole
* truth; presence is used only when facts are absent (an unclustered peer, or
* one that has not been polled yet).
*
* The local node keeps the union: its models come from the `localManagerModels`
* cache in {@link discoveryModelsForNode}, and the presence fallback still
* preserves attribution for an externally-running engine that engine-manager
* has not adopted (fact `running: false`) but the daemon enriched with models.
*/
private engineActiveForModels(node: ModularNode, engine: ProxyEngine): boolean {
const presenceUp = node.engines[engine].up
if (node.id === this.selfId) {
return (this.engineManagerFacts.get(engine)?.running ?? false) || presenceUp
}
const facts = this.remoteEngineFacts.get(this.remoteOpKey(node.id, engine))
return facts ? facts.running : presenceUp
}
/**
* Attribute a node's model list to one proxy engine. The backend's per-engine
* breakdown (`AvailableNode.modelsByEngine`) is authoritative when present,
* so a dual-engine node attributes each model to the engine that serves it.
* A pre-attribution peer sends no map, so the flat `AvailableNode.models`
* union is attributed only when exactly one proxy engine is active (never
* cross-attributed when multiple run). Mirrors
* noderec.DirectoryNode.EngineModels.
*/
private modelsForEngine(node: ModularNode, engine: ProxyEngine): string[] {
// Per-engine attribution is authoritative when the node carries any:
// return exactly this engine's models so a dual-engine node attributes
// each model to the engine that serves it, and a missing key means this
// engine serves none (NOT the cross-engine union). Mirrors
// noderec.DirectoryNode.EngineModels.
if (Object.keys(node.modelsByEngine).length > 0) {
return node.modelsByEngine[engineManagerName(engine)] ?? []
}
// Fallback for a pre-attribution peer: the flat union is unattributed, so
// attribute it only when exactly one proxy engine is active on the node,
// and never cross-attribute when multiple run.
const active = PROXY_ENGINES.filter(candidate =>
this.engineActiveForModels(node, candidate)
)
return active.length === 1 && active[0] === engine ? node.models : []
}
private toEngineModels(node: ModularNode, engine: ProxyEngine): EngineModels {
const loaded = loadedNamesForEngine(node, engine)
return {
engineType: engine,
nodeId: node.id,
models: this.modelsForEngine(node, engine).map(name =>
modelItem(name, loaded.has(name))
)
}
}
/**
* Proxy-engine models for a node. The broker daemon enriches each node's
* model list from its engine-manager `/v1/models` (models-http) onto
* `AvailableNode.models`, which {@link parseBrokerNode} stamps node-level and
* {@link toEngineModels} attributes to a uniquely-active proxy engine — so
* discovery is a live, refresh-safe source for every node.
*
* For the **local** node we prefer engine-manager `list_models` whenever a
* successful result is cached, including an explicit empty list. Cache
* absence means unknown and falls back to discovery (for example, an
* externally-running Ollama that engine-manager has not adopted). This
* presence check prevents a last-model deletion from resurrecting stale
* discovery data. The cache is re-pulled whenever discovery reports the
* local model set changed (see {@link upsertNode}).
*/
private discoveryModelsForNode(
node: ModularNode | undefined,
engine: ProxyEngine,
nodeId: string
): EngineModels {
if (nodeId === this.selfId) {
const cached = this.localManagerModels.get(engine)
if (cached !== undefined) {
// The cached list is the authoritative `list_models` set (names
// only); stamp `'loaded'` from the self node's discovery/push
// loaded set so the local card reflects in-memory residency too.
const loaded = loadedNamesForEngine(node, engine)
return {
engineType: engine,
nodeId,
models: cached.map(item => ({
...item,
status: loaded.has(item.name) ? 'loaded' : 'idle'
}))
}
}
}
if (!node) return { engineType: engine, nodeId, models: [] }
return this.toEngineModels(node, engine)
}
/**
* Resolve the local node's status for an engine. `nvpair-engine-manager` is the
* sole authority on the local engine's install/running state — we do NOT let
* a proxy's discovery `up` flag override it, so the UI's run state always
* matches what the toggle (`engine:status`) decides on. An externally-running
* engine the manager hasn't adopted therefore shows as `stopped` until the
* user starts it (which adopts it); discovery only contributes models. The
* backend has no managed/external distinction, so we never synthesize
* `installType` — it reports install/uninstall/stop failures via
* errors:report.
*/
private resolveLocalEngineStatus(
engineType: EngineType,
node: ModularNode | undefined
): EngineStatusData | undefined {
const nodeId = this.selfId
if (!nodeId) return undefined
const facts = this.engineManagerFacts.get(engineType)
// An in-flight lifecycle op outranks the fact-derived status so the UI
// shows the spinner/progress immediately; the op is dropped the moment
// the backend reports a resolution.
const pending = this.pendingEngineOps.get(engineType)
if (pending) {
return {
engineType,
nodeId,
processStatus: pending,
enginePort: facts && facts.running && facts.port > 0 ? facts.port : null,
proxyPort: isProxyEngine(engineType) ? this.getProxyPort(engineType) : null
}
}
if (facts) {
return {
engineType,
nodeId,
processStatus: facts.running
? 'running'
: facts.installed
? 'stopped'
: 'not-installed',
// The engine-manager reports the manifest's configured port for a
// pinned-port engine (for example managed llama.cpp on 8081 behind
// its 8080 proxy facade) whether it is running or merely installed,
// so surface it in both states —
// matching the `EngineStatusData.enginePort` contract. Auto-assign
// engines report 0 until started, which stays null.
enginePort: facts.installed && facts.port > 0 ? facts.port : null,
// Each proxy-fronted engine has its own broker proxy
// (mapped in proxy-engines.ts); report that engine's bound
// proxy port. Loopback-only engines get null.
proxyPort: isProxyEngine(engineType) ? this.getProxyPort(engineType) : null
}
}
return node && isProxyEngine(engineType)
? toEngineStatus(node, engineType, this.getProxyPort(engineType))
: undefined
}
/** Push a fresh `engines:state-changed` for one local engine. */
private emitLocalEngineStatus(engineType: EngineType): void {
const nodeId = this.selfId
if (!nodeId) return
const status = this.resolveLocalEngineStatus(engineType, this.nodes.get(nodeId))
if (!status) return
emitBridgePush('engines:state-changed', { nodeId, engineType, status })
}
/** Project a `nvpair-engine-manager` `engine:install-progress` for the local node. */
applyEngineManagerProgress(params: JsonValue | undefined): void {
const nodeId = this.selfId
if (!nodeId) return
const obj = objectValue(params)
if (!obj) return
const engineType = engineTypeFromManagerName(stringValue(obj.engine))
if (!engineType) return
const stage = stringValue(obj.stage) || 'installing'
// nvpair-engine-manager emits these terminal stages (see install.go):
// done / already-installed -> success, failed -> error (percent -1).
// On any terminal stage we clear the ephemeral progress entry.
if (stage === 'done' || stage === 'already-installed' || stage === 'failed') {
emitBridgePush('engines:progress-cleared', {
key: `${nodeId}:${engineType}:install`
})
// `done` is immediately followed by engine:state-changed
// (installed:true), which clears the optimistic `installing` status
// and emits the resolved one. `already-installed` and `failed` emit
// NO state-changed, so we must clear the optimistic status here or
// the spinner sticks.
if (stage === 'already-installed' || stage === 'failed') {
this.clearLocalEngineOp(engineType)
}
return
}
// Reflect any in-flight install as a transitional status — even one
// started outside our UI (backend auto-resume) — so the progress line
// renders. The UI only shows progress when processStatus is transitional.
if (this.pendingEngineOps.get(engineType) !== 'installing') {
this.pendingEngineOps.set(engineType, 'installing')
this.emitLocalEngineStatus(engineType)
}
this.armPendingOpTimer(engineType, 'installing')
const node = this.nodes.get(nodeId)
const progress: EngineProgress = {
engineType,
nodeId,
nodeName: node?.name ?? nodeId,
operation: 'install',
status: stage,
percent: measuredPercent(obj.percent)
}
emitBridgePush('engines:progress-changed', progress)
}
/**
* Emit an optimistic `pulling` progress entry for a model the user just asked
* to download. This indeterminate entry makes the UI's spinner row appear the
* instant the modal closes instead of looking like nothing happened; the
* backend then streams live percent via `engine:pull-progress`
* ({@link applyLocalEngineProgress}), which updates this same entry
* in place. Cleared by {@link finishModelPull} when the supervisor's awaited
* pull resolves.
*/
beginModelPull(engineType: EngineType, model: string): void {
const nodeId = this.selfId
if (!nodeId) return
const node = this.nodes.get(nodeId)
const progress: EngineProgress = {
engineType,
nodeId,
nodeName: node?.name ?? nodeId,
operation: 'pull',
model,
status: 'pulling'
}
// Remember the model so the model-less `engine:pull-progress` frames can
// be re-associated with this exact entry (see localPullModels).
this.localPullModels.set(engineType, model)
this.activePulls.set(engineProgressKey(progress), progress)
emitBridgePush('engines:progress-changed', progress)
}
/**
* Project a `nvpair-engine-manager` `engine:pull-progress` for the local node
* — the local counterpart of `engine:remote-progress`: live
* download progress for a model pull driven via `engine:action`
* `pull_model`. The frame carries `{ engine, op, stage, percent, message }`
* and **no** `model`, so we backfill the model captured at dispatch and
* refresh the optimistic entry in place. Clearing stays with the awaited pull
* ({@link finishModelPull}), so this only advances percent/stage: it ignores
* the terminal error sentinel (`percent: -1`) and the non-download frames'
* `percent: 0` so the rendered bar never jumps backwards.
*/
applyLocalEngineProgress(params: JsonValue | undefined): void {
const nodeId = this.selfId
if (!nodeId) return
const obj = objectValue(params)
if (!obj) return
const engineType = engineTypeFromManagerName(stringValue(obj.engine))
if (!engineType) return
const model = this.localPullModels.get(engineType)
if (!model) return
const key = engineProgressKey({ nodeId, engineType, operation: 'pull', model })
const existing = this.activePulls.get(key)
if (!existing) return
const percent = numberValue(obj.percent)
const progress: EngineProgress = {
...existing,
status: stringValue(obj.stage) || existing.status,
percent: mergePullProgressPercent(percent, existing.percent)
}
this.activePulls.set(key, progress)
emitBridgePush('engines:progress-changed', progress)
}
/** Whether an optimistic pull entry for this model is still in flight. */
isModelPullActive(engineType: EngineType, model: string): boolean {
const nodeId = this.selfId
if (!nodeId) return false
return this.activePulls.has(
engineProgressKey({ nodeId, engineType, operation: 'pull', model })
)
}
/** Clear the optimistic pull entry once the pull completes, fails, or times out. */
finishModelPull(engineType: EngineType, model: string): void {
const nodeId = this.selfId
if (!nodeId) return
this.localPullModels.delete(engineType)
const key = engineProgressKey({ nodeId, engineType, operation: 'pull', model })
if (!this.activePulls.delete(key)) return
emitBridgePush('engines:progress-cleared', { key })
}
getLogs(): LogEntry[] {
return [...this.logs]
}
getLogPage(): LogPage {
return {
entries: [...this.logs],
total: this.logs.length,
levels: ['info', 'warn', 'error', 'verbose'],
sources: Array.from(new Set(this.logs.map(entry => entry.source ?? 'service-bridge'))),
sublevels: Array.from(new Set(this.logs.map(entry => entry.sublevel)))
}
}
getAppStartTime(): string {
return appStartTime
}
appendLog(source: string, stream: 'stdout' | 'stderr', text: string): void {
const entry: LogEntry = {
level: serviceLogLevel(stream, text),
time: new Date().toISOString(),
source,
sublevel: stream,
message: text
}
this.logs.push(entry)
if (this.logs.length > 2000) {
this.logs = this.logs.slice(this.logs.length - 1000)
}
}
handleNotification(notification: JsonRpcNotification): void {
const proxyEngine = proxyEngineFromSource(notification.source)
if (proxyEngine) {
this.handleProxyNotification(notification, proxyEngine)
return
}
if (notification.source === 'broker') {
this.handleBrokerNotification(notification)
}
}
private handleProxyNotification(notification: JsonRpcNotification, engine: ProxyEngine): void {
if (notification.method === 'ready') {
const params = objectValue(notification.params)
// Trust the broker-reported port only. If `ready` carries no port we
// keep the last known value (0 = unknown) rather than guessing.
const nextPort = numberValue(params?.port)
if (nextPort <= 0) return
const changed = nextPort !== this.proxyPorts[engine]
this.proxyPorts[engine] = nextPort
// A runtime proxy:set-port (or a broker steer onto a free port)
// re-emits `ready` with the new port. Push a fresh status for that
// engine so the Edit Node proxy port reflects the actually-bound value
// immediately. Only on a real change so the startup baseline `ready`
// (and redundant re-readies) stay quiet.
if (changed) this.emitLocalEngineStatus(engine)
return
}
if (notification.method === 'error') {
const params = objectValue(notification.params)
this.upsertError({
id: `${engine}-proxy:${Date.now()}`,
message: stringValue(params?.message) || 'Modular proxy failed',
timestamp: Date.now(),
severity: 'error',
nodeId: this.selfId ?? ''
})
return
}
if (notification.method === 'node/removed') {
const node = parseProxyNode(notification.params, engine)
if (!node) return
this.clearNodeEngine(node.id, engine)
return
}
if (notification.method === 'node/discovered' || notification.method === 'node/updated') {
const node = parseProxyNode(notification.params, engine)
if (!node) return
this.upsertNode(node, proxySourceForEngine(engine))
}
}
/**
* A proxy reported a node gone for one engine. Drop just that engine's
* presence + source; keep the node alive if another engine or the node-info
* snapshot still references it, otherwise evict it entirely.
*/
private clearNodeEngine(nodeId: string, engine: ProxyEngine): void {
const existing = this.nodes.get(nodeId)
if (!existing) return
const source = proxySourceForEngine(engine)
const sources = removeSource(existing.sources, source)
if (sources.length === 0 && !existing.nodeInfoUp) {
this.removeNodeEntry(nodeId)
return
}
const next: ModularNode = {
...existing,
sources,
// With no proxy left reporting the node, that feed's addresses are
// claimed by nothing; the broker's ranked list stands alone.
proxyAddresses: sources.some(entry => entry !== 'broker')
? existing.proxyAddresses
: [],
engines: setEngine(existing.engines, engine, emptyPresence()),
lastSeen: Date.now()
}
this.nodes.set(next.id, next)
this.emitNodeChanged(next)
}
private handleBrokerNotification(notification: JsonRpcNotification): void {
if (notification.method !== 'discovery:nodes-changed') return
const nodes = brokerNodesValue(notification.params)
const nextBrokerNodeIds = new Set(nodes.map(node => node.id))
for (const nodeId of Array.from(this.brokerNodeIds)) {
if (!nextBrokerNodeIds.has(nodeId)) {
this.removeBrokerNode(nodeId)
}
}
this.brokerNodeIds = nextBrokerNodeIds
for (const node of nodes) {
this.upsertNode(node, 'broker')
}
}
private removeBrokerNode(nodeId: string): void {
const existing = this.nodes.get(nodeId)
if (!existing) return
const remainingSources = removeSource(existing.sources, 'broker')
if (remainingSources.length === 0) {
this.removeNodeEntry(nodeId)
return
}
// A proxy source still reports the node; drop only the node-info snapshot
// (the broker is the sole node-info / telemetry source now).
const next: ModularNode = {
...existing,
sources: remainingSources,
nodeInfoPort: 0,
nodeInfoUp: false,
// Clear the broker's now-stale canonical address and ranking; a
// still-present proxy source repopulates `reachableAddress` from its
// `ip` field on the next node/* event, so we never keep a dead broker
// IP — nor project addresses no live source claims any more.
reachableAddress: '',
brokerAddresses: [],
gpus: [],
cpu: null,
memory: null,
lastSeen: Date.now()
}
this.nodes.set(next.id, next)
this.emitNodeChanged(next)
}
private upsertNode(node: ModularNode, source?: BrokerNodeSource): void {
// Self is identified authoritatively by the cluster-manager's node UUID
// (`cluster:get-node-id`), which equals the discovery/proxy hostUuid key,
// so there is no hostname guessing here — `setSelfId` is the sole source.
const existing = this.nodes.get(node.id)
const merged = this.mergeNode(existing, node, source)
// Collapse a wiped-and-rejoined host onto its new UUID before storing,
// so the pre-wipe record never reaches the map (see resolveAddressCollision).
if (this.resolveAddressCollision(merged)) {
this.removeNodeEntry(merged.id)
return
}
if (existing && sameNode(existing, merged)) return
this.nodes.set(merged.id, merged)
this.emitNodeChanged(merged)
// A model pulled/deleted while an engine is already running produces no
// `engine:state-changed`, so the engine-manager model cache would go stale.
// Refresh on a flat-union change and on this engine's attribution change:
// deleting a model shared with another engine changes only the latter.
if (merged.id === this.selfId && existing) {
const unionChanged = !sameStringList(existing.models, merged.models)
for (const engine of PROXY_ENGINES) {
const managerEngine = engineManagerName(engine)
const hadEngine = managerEngine in existing.modelsByEngine
const hasEngine = managerEngine in merged.modelsByEngine
const attributionChanged =
hadEngine !== hasEngine ||
!sameStringList(
existing.modelsByEngine[managerEngine] ?? [],
merged.modelsByEngine[managerEngine] ?? []
)
// Proxy presence is not a lifecycle fact: the broker can keep
// serving engine-manager while this optional routing proxy is
// unavailable. Use the local manager fact first, with proxy
// presence only as the existing external-engine fallback.
if (
this.engineActiveForModels(merged, engine) &&
(unionChanged || attributionChanged)
) {
this.onLocalDiscoveryModelsChanged?.(engine)
}
}
}
}
/**
* Collapse two UUIDs that are really one machine.
*
* A node whose appdata is wiped mints a fresh hostUuid, so peers advertise
* the same machine under a new key while the pre-wipe key survives — the
* fleet sees a duplicate "ghost" row. Nothing on the wire marks the two as
* the same host, so this infers it from the three signals the node-scanner
* uses to nominate a superseded record (`directory.supersedeCandidates`):
* same address, same hostname, and a `lastSeen` gap of at least
* MODULAR_SUPERSEDE_MIN_AGE_MS.
*
* It stops there, and the scanner does not. Those signals come from an
* unauthenticated mDNS advertisement, and `lastSeen` is not a liveness
* clock — the backend re-stamps a node only when its record CHANGES, so a
* healthy peer's `lastSeen` freezes exactly like a ghost's. The scanner
* therefore treats them as a suspicion and deletes only once node-info
* names a different host. This has no such proof available, so it must stay
* a display-side collapse: it hides a row until the next snapshot, and must
* never be read as the directory having evicted anything.
*
* Two caveats on how faithfully this can mirror the backend, both stemming
* from a proxy-sourced node carrying less than a discovery record does:
* `parseProxyNode` stamps `lastSeen` locally rather than echoing the
* backend's, and `primaryNodeAddress` falls back to `host` (a hostname for a
* proxy node), which can collapse the address and name conditions into one.
* Both only ever make this rule fire LESS often than the scanner's, so the
* node list stays a subset of the directory rather than contradicting it.
*
* Returns true when `node` is the STALE side and must not be stored — a
* backend that has not yet evicted the ghost keeps re-publishing it in every
* `discovery:nodes-changed` snapshot, so refusing it on arrival is what
* makes the eviction stick. Otherwise the losing entries are evicted here.
*/
private resolveAddressCollision(node: ModularNode): boolean {
const address = primaryNodeAddress(node)
if (!address || !node.name) return false
const rivals: ModularNode[] = []
for (const other of this.nodes.values()) {
if (other.id === node.id || other.id === this.selfId) continue
if (primaryNodeAddress(other) !== address || other.name !== node.name) continue
rivals.push(other)
}
// Self is pinned by the cluster-manager's node UUID, so it is always the
// live identity for this machine's address: skipped above so it can
// never be evicted, and skipped as a claimant below so it never evicts.
// The backend applies the same asymmetry (directory.supersedeCandidates).
if (node.id === this.selfId) return false
// Decide before mutating. Returning mid-loop would strand entries
// already marked stale, leaving a partially applied collapse.
if (rivals.some(other => other.lastSeen - node.lastSeen >= MODULAR_SUPERSEDE_MIN_AGE_MS)) {
return true
}
for (const other of rivals) {
if (node.lastSeen - other.lastSeen >= MODULAR_SUPERSEDE_MIN_AGE_MS) {
this.removeNodeEntry(other.id)
}
}
return false
}
/** Delete a node and clean every index that referenced it. */
private removeNodeEntry(nodeId: string): void {
if (!this.nodes.delete(nodeId)) return
this.brokerNodeIds.delete(nodeId)
this.dropRemoteEngineFacts(nodeId)
emitBridgePush('nodes:remove', nodeId)
emitBridgePush('discovery:nodes-changed', this.getAvailableNodes())
}
private emitNodeChanged(merged: ModularNode): void {
emitBridgePush('nodes:upsert', toNodeItem(merged, this.selfId))
emitBridgePush('metrics:update', toMetrics(merged))
emitBridgePush('discovery:nodes-changed', this.getAvailableNodes())
// For the local node, engine-manager is the source of truth for
// install/running state; discovery only fills in models. A remote node
// has no local engine-manager, so its status comes from authoritative
// peer facts or its advertisement, and is omitted when neither is known.
// Push per proxy engine so each one lights up independently per node.
const isSelf = merged.id === this.selfId
for (const engine of PROXY_ENGINES) {
if (!isSelf) {
this.maybeClearRemotePendingFromDiscovery(merged.id, engine, merged)
}
const status = isSelf
? (this.resolveLocalEngineStatus(engine, merged) ??
toEngineStatus(merged, engine, this.getProxyPort(engine)))
: this.remoteEngineStatusForPush(merged.id, engine)
emitBridgePush('engines:state-changed', {
nodeId: merged.id,
engineType: engine,
...(status ? { status } : {}),
models: this.discoveryModelsForNode(merged, engine, merged.id)
})
}
}
private mergeNode(
existing: ModularNode | undefined,
next: ModularNode,
source: BrokerNodeSource | undefined
): ModularNode {
if (!existing || !source) return next
if (source === 'broker') {
// node-info discovery snapshot (now also carries manual nodes). Keep
// the live per-engine proxy data we already merged; refresh identity,
// addresses, and node-info from the snapshot.
return {
...next,
sources: mergeSources(existing.sources, 'broker'),
// Broker discovery is authoritative for the display hostname and
// trust/cluster flags; keep the prior hostname only if a snapshot
// ever lacks one.
name: next.name || existing.name,
// The snapshot is the broker's whole list, so it replaces the
// previous one (carried by the spread): an address the node has
// re-ranked away must stop being polled and projected, which a
// union could never express. The proxy feed's own contribution
// survives untouched and is projected behind this list.
proxyAddresses: existing.proxyAddresses,
// Prefer the broker's canonical address (netpick.Primary), keeping
// a prior value only if a snapshot ever lacks ipAddress. The proxy
// supplies one too now, but the broker's wins on merge.
reachableAddress: next.reachableAddress || existing.reachableAddress,
gpus: existing.gpus,
cpu: existing.cpu,
memory: existing.memory,
inferenceHardwareIds: existing.inferenceHardwareIds,
engines: existing.engines
}
}
// A proxy source refreshes only that engine's presence; keep the other
// engines, telemetry, and node-info.
const engine = proxyEngineFromSource(source)
return {
...next,
sources: mergeSources(existing.sources, source),
// The proxy feed carries no hostname/trust/cluster facts; keep the
// broker-reported values rather than overwriting them with the proxy
// node's empty name and default-false flags.
name: existing.name || next.name,
trusted: existing.trusted,
clustered: existing.clustered,
// Symmetrically: this event is the proxy feed's whole list (carried by
// the spread), and the broker's ranking is none of its business.
brokerAddresses: existing.brokerAddresses,
// The proxy now carries the node's canonical `ip`, but the
// broker's value is preferred when present; fall back to the proxy's
// for a proxy-only node (existing empty after a broker drop).
reachableAddress: existing.reachableAddress || next.reachableAddress,
nodeInfoPort: existing.nodeInfoPort,
nodeInfoUp: existing.nodeInfoUp,
gpus: existing.gpus,
cpu: existing.cpu,
memory: existing.memory,
inferenceHardwareIds: existing.inferenceHardwareIds,
// A proxy event carries no model list (models-http); keep the
// broker-enriched `AvailableNode.models` (+ per-engine attribution and
// loaded set) we already merged.
models: existing.models,
modelsByEngine: existing.modelsByEngine,
loadedByEngine: existing.loadedByEngine,
engines: setEngine(existing.engines, engine, next.engines[engine]),
lastSeen: Math.max(existing.lastSeen, next.lastSeen)
}
}
}
let state: ModularBridgeState | null = null
export function getModularBridgeState(): ModularBridgeState {
if (!state) {
state = new ModularBridgeState()
}
return state
}