Skip to content

Router that virtually distributes inference across connected devices in the home.

Go
6.7 KB
Raw Blame
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

/**
 * Engine command API -- fire-and-forget commands + push event subscriptions.
 *
 * Commands are void (fire-and-forget). Errors arrive via errors:update push events.
 * All state flows via push events, not command responses.
 */
import type { PreloadServiceTransport as ServiceTransport } from '@/shared/types/service-bridge'
import type {
    EngineHubSearchResponse,
    EngineInitialState,
    EngineStatePatch,
    EngineCommandPayload
} from '@/shared/types/engine-api'
import type { EngineProgress, EngineType } from '@/shared/types/engines'
import { usePendingActionsStore } from '@/ui/stores/pending-actions.store'
import type {
    EngineSettingsTarget,
    EngineSettingsRequest,
    EngineSettingsSnapshot,
    EngineSettingsPreview,
    EngineSettingsReceipt
} from '@/shared/types/engine-settings'

export interface IEngineApi {
    /** Read the owning node's authoritative settings snapshot for one engine. */
    getSettings(target: EngineSettingsTarget): Promise<EngineSettingsSnapshot>
    /**
     * Validate a draft against the owner without persisting or touching any
     * process: returns the normalized settings, per-field errors, any port
     * conflict, and whether applying would restart or rebind.
     */
    previewSettings(request: EngineSettingsRequest): Promise<EngineSettingsPreview>
    /**
     * Commit a draft. The receipt only acknowledges that the owner accepted the
     * operation — completion arrives on `onSettingsChanged`, because a stop,
     * rebind, and restart outlive the call.
     */
    applySettings(request: EngineSettingsRequest): Promise<EngineSettingsReceipt>
    /** A settings snapshot changed on some node — the only source of applied state. */
    onSettingsChanged(callback: (snapshot: EngineSettingsSnapshot) => void): () => void
    /** A node's settings authority became unreachable; its cached snapshot is stale. */
    onSettingsDisconnected(callback: (target: { nodeId: string }) => void): () => void
    /** Fetch initial engine state: statuses, models, progress, and update availability. */
    getInitialState(): Promise<EngineInitialState>

    /** Start or stop an engine process on a node. */
    toggle(engineType: EngineType, nodeId: string): void
    /** Install an engine on a node. */
    install(engineType: EngineType, nodeId: string): void
    /** Uninstall an engine from a node without removing downloaded models. */
    uninstall(engineType: EngineType, nodeId: string): void
    /** Pull (download) a model on a node. */
    pullModel(engineType: EngineType, nodeId: string, model: string): void
    /** Load a model into memory on a node. */
    loadModel(engineType: EngineType, nodeId: string, model: string): void
    /** Unload a model from memory on a node. */
    unloadModel(engineType: EngineType, nodeId: string, model: string): void
    /** Delete a downloaded model from a node. */
    deleteModel(engineType: EngineType, nodeId: string, model: string): void
    /** Set the model keep-alive expiry duration on a node. */
    setModelExpiry(engineType: EngineType, nodeId: string, model: string, expiry: string): void
    /** Load an engine catalog or explicitly search its upstream registry. */
    searchHub(engineType: EngineType, query?: string): Promise<EngineHubSearchResponse>

    /** Durable engine state changed. Prefer this for new renderer state. */
    onStateChanged(callback: (patch: EngineStatePatch) => void): () => void
    /** Engine operation progress update (pull, install, etc.). */
    onProgress(callback: (progress: EngineProgress) => void): () => void
    /** An engine progress entry was removed (operation completed). */
    onProgressRemove(callback: (key: string) => void): () => void
    /** Trigger a one-click update (managed installs only). Fire-and-forget. */
    update(engineType: EngineType, nodeId: string): void
}

function fireCommand(transport: ServiceTransport, payload: EngineCommandPayload): void {
    // Optimistically flip the clicked control to a "working"/disabled state so
    // the user gets immediate feedback even when the backend push lags (esp.
    // remote nodes). The entry clears itself on the superseding push / timeout.
    usePendingActionsStore.getState().begin(payload)
    transport.invoke('engine:command', payload).catch(() => {})
}

export function createEngineApi(transport: ServiceTransport): IEngineApi {
    return {
        getSettings: target => transport.invoke('engines:get-settings', target),
        previewSettings: request => transport.invoke('engines:preview-settings', request),
        applySettings: request => transport.invoke('engines:apply-settings', request),
        onSettingsChanged: cb => transport.subscribePush('engines:settings-changed', cb),
        onSettingsDisconnected: cb => transport.subscribePush('engines:settings-disconnected', cb),
        getInitialState: () => transport.invoke('engines:get-initial'),

        toggle: (engineType, nodeId) =>
            fireCommand(transport, { command: 'toggle', engineType, nodeId }),
        install: (engineType, nodeId) =>
            fireCommand(transport, { command: 'install', engineType, nodeId }),
        uninstall: (engineType, nodeId) =>
            fireCommand(transport, { command: 'uninstall', engineType, nodeId }),
        pullModel: (engineType, nodeId, model) =>
            fireCommand(transport, { command: 'pullModel', engineType, nodeId, model }),
        loadModel: (engineType, nodeId, model) =>
            fireCommand(transport, { command: 'loadModel', engineType, nodeId, model }),
        unloadModel: (engineType, nodeId, model) =>
            fireCommand(transport, { command: 'unloadModel', engineType, nodeId, model }),
        deleteModel: (engineType, nodeId, model) =>
            fireCommand(transport, { command: 'deleteModel', engineType, nodeId, model }),
        setModelExpiry: (engineType, nodeId, model, expiry) =>
            fireCommand(transport, {
                command: 'setModelExpiry',
                engineType,
                nodeId,
                model,
                expiry
            }),
        searchHub: (engineType, query) =>
            transport.invoke(
                'engine:search-hub',
                query === undefined ? { engineType } : { engineType, query }
            ),

        onStateChanged: cb => transport.subscribePush('engines:state-changed', cb),
        onProgress: cb => transport.subscribePush('engines:progress-changed', cb),
        onProgressRemove: cb =>
            transport.subscribePush('engines:progress-cleared', ({ key }) => cb(key)),
        update: (engineType, nodeId) =>
            fireCommand(transport, { command: 'update', engineType, nodeId })
    }
}