Skip to content

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

Go

fix(engine-manager): report install steps without fake percentages (#145)

ckelseynv27b342ada5e3
diff --git a/desktop/src/electron/service-bridge/modular-state.ts b/desktop/src/electron/service-bridge/modular-state.ts
index 4463803..17a3cd3 100644
--- a/desktop/src/electron/service-bridge/modular-state.ts
+++ b/desktop/src/electron/service-bridge/modular-state.ts
@@ -232,6 +232,16 @@ 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
}
@@ -1568,11 +1578,10 @@ class ModularBridgeState {
? engineProgressKey({ nodeId, engineType, operation: 'pull', model })
: ''
const existingPull = pullKey ? this.activePulls.get(pullKey) : undefined
- const framePercent = numberValue(obj.percent)
const percent =
operation === 'pull'
- ? mergePullProgressPercent(framePercent, existingPull?.percent)
- : framePercent
+ ? mergePullProgressPercent(numberValue(obj.percent), existingPull?.percent)
+ : measuredPercent(obj.percent)
const progress: EngineProgress = {
engineType,
nodeId,
@@ -2142,7 +2151,7 @@ class ModularBridgeState {
nodeName: node?.name ?? nodeId,
operation: 'install',
status: stage,
- percent: numberValue(obj.percent)
+ percent: measuredPercent(obj.percent)
}
emitBridgePush('engines:progress-changed', progress)
}
diff --git a/desktop/tests/modular/install-state.test.ts b/desktop/tests/modular/install-state.test.ts
index 0a89cc3..0f4c118 100644
--- a/desktop/tests/modular/install-state.test.ts
+++ b/desktop/tests/modular/install-state.test.ts
@@ -6,7 +6,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
vi.mock('electron', () => ({ BrowserWindow: { getAllWindows: () => [] } }))
vi.mock('@/electron/window', () => ({ createOverviewWindow: vi.fn() }))
-import type { EngineProcessStatus } from '@/shared/types/engines'
+import type { EngineProcessStatus, EngineProgress } from '@/shared/types/engines'
import { subscribePush } from '@/electron/service-bridge/push-bus'
import { getModularBridgeState } from '@/electron/service-bridge/modular-state'
@@ -71,7 +71,7 @@ describe('LM Studio install state', () => {
vi.advanceTimersByTime(120_000)
expect(statuses.at(-1)).toBe('installing')
- state.applyEngineManagerProgress({ engine: 'lmstudio', stage: 'installing', percent: 75 })
+ state.applyEngineManagerProgress({ engine: 'lmstudio', stage: 'installing' })
vi.advanceTimersByTime(30 * 60_000 - 1)
expect(statuses.at(-1)).toBe('installing')
vi.advanceTimersByTime(1)
@@ -82,3 +82,47 @@ describe('LM Studio install state', () => {
expect(statuses.at(-1)).toBe('not-installed')
})
})
+
+describe('install progress percent', () => {
+ function captureInstallProgress(): EngineProgress[] {
+ const frames: EngineProgress[] = []
+ unsubscribe = subscribePush(event => {
+ if (
+ event.channel === 'engines:progress-changed' &&
+ event.payload.operation === 'install'
+ ) {
+ frames.push(event.payload)
+ }
+ })
+ return frames
+ }
+
+ it('drops a local install to indeterminate after a measured download', () => {
+ const state = getModularBridgeState()
+ const frames = captureInstallProgress()
+ state.setSelfId('local-node')
+
+ state.applyEngineManagerProgress({ engine: 'lmstudio', stage: 'downloading', percent: 42 })
+ expect(frames.at(-1)?.percent).toBe(42)
+
+ state.applyEngineManagerProgress({ engine: 'lmstudio', stage: 'downloading', percent: 100 })
+ state.applyEngineManagerProgress({ engine: 'lmstudio', stage: 'installing' })
+ expect(frames.at(-1)?.status).toBe('installing')
+ expect(frames.at(-1)?.percent).toBeUndefined()
+ })
+
+ it('drops a remote install to indeterminate after a measured download', () => {
+ const state = getModularBridgeState()
+ const frames = captureInstallProgress()
+ const frame = { node: 'remote-node', engine: 'ollama', op: 'install' }
+
+ state.applyRemoteEngineProgress({ ...frame, stage: 'downloading', percent: 100 })
+ expect(frames.at(-1)?.percent).toBe(100)
+
+ state.applyRemoteEngineProgress({ ...frame, stage: 'installing' })
+ expect(frames.at(-1)?.status).toBe('installing')
+ expect(frames.at(-1)?.percent).toBeUndefined()
+
+ state.applyRemoteEngineProgress({ ...frame, stage: 'failed', percent: -1 })
+ })
+})
diff --git a/services/nvpair-engine-manager/README.md b/services/nvpair-engine-manager/README.md
index 72ef87e..2c15997 100644
--- a/services/nvpair-engine-manager/README.md
+++ b/services/nvpair-engine-manager/README.md
@@ -83,14 +83,15 @@ Notifications (service → caller): `engine:ready{version}`,
loaded (in-memory) models changes (explicit load/unload, JIT auto-load, or
TTL/idle eviction); `models` is the full `engine:models` shape (incl.
`loadedByEngine`) so a consumer swaps its whole snapshot,
-`engine:install-progress{engine, stage, percent}`,
-`engine:pull-progress{engine, op, stage, percent, message}` (live progress for a
+`engine:install-progress{engine, stage, percent?, error?}` (`error` on the
+terminal `failed` frame),
+`engine:pull-progress{engine, op, stage, percent?, message}` (live progress for a
local model pull driven via `engine:action{action:"pull_model"}` — the local
counterpart of `engine:remote-progress`; frames are coalesced to changes in
stage/percent, the engine's terminal success surfaces as `stage:"success"`, and
a failed pull emits a terminal `stage:"error", percent:-1, message` frame so a
UI converges even if its synchronous call already timed out),
-`engine:remote-progress{opId, node, engine, op, stage, percent, message}`
+`engine:remote-progress{opId, node, engine, op, stage, percent?, message}`
(relayed live progress for a remote install/pull), and — for the error
pipeline — `errors:report` / `errors:clear` (consumed by `nvpair-errors`
via the broker; see below).
@@ -117,6 +118,12 @@ If the start acknowledgement is lost or unreadable, acceptance and cancellation
are reported as unconfirmed without unloading an unowned download. The monitored
model must match `params.model`; mismatches are rejected before subscribing.
+`percent` on all three progress notifications is present only when the step is
+measurable (download bytes, byte-progress pulls) or terminal (`100` on install
+`done` / `already-installed`, `-1` on install `failed` and pull `error`). An
+indeterminate step omits it — the install `verified` and `installing` stages
+always do — so a UI renders the stage alone.
+
The `engine:remote-*` methods are the client half of remote engine
management: engine-manager resolves the target `node` in an `ec` peer
directory (fed by its own `discovery:subscribe{services:[ec]}` to the broker
diff --git a/services/nvpair-engine-manager/executor.go b/services/nvpair-engine-manager/executor.go
index 0ba772f..f715845 100644
--- a/services/nvpair-engine-manager/executor.go
+++ b/services/nvpair-engine-manager/executor.go
@@ -255,16 +255,26 @@ func (st *engineState) pathVars() map[string]string {
return vars
}
-func progress(engine, stage string, pct int) map[string]any {
- return map[string]any{"engine": engine, "stage": stage, "percent": pct}
-}
-
// emitInstallProgress reports one install-progress step to both consumers: the
// local engine:install-progress notification (this node's UI) and the progress
-// hub (so an ec streaming handler can relay it to a remote initiator).
+// hub (so an ec streaming handler can relay it to a remote initiator). A pct of
+// 0 marks a step with no measurable progress and is omitted from the wire.
func (e *Executor) emitInstallProgress(engine, stage string, pct int) {
- e.notify("engine:install-progress", progress(engine, stage, pct))
- e.progress.publish(ProgressEvent{Engine: engine, Op: "install", Stage: stage, Percent: pct})
+ e.emitInstallFrame(engine, stage, pct, "")
+}
+
+// emitInstallFrame is emitInstallProgress with an optional failure reason,
+// carried as "error" on the notification and Message on the hub event.
+func (e *Executor) emitInstallFrame(engine, stage string, pct int, errMsg string) {
+ params := map[string]any{"engine": engine, "stage": stage}
+ if wirePercentIncluded(pct) {
+ params["percent"] = pct
+ }
+ if errMsg != "" {
+ params["error"] = errMsg
+ }
+ e.notify("engine:install-progress", params)
+ e.progress.publish(ProgressEvent{Engine: engine, Op: "install", Stage: stage, Percent: pct, Message: errMsg})
}
// emitPullProgress reports one model-pull step to both consumers: the local
diff --git a/services/nvpair-engine-manager/install.go b/services/nvpair-engine-manager/install.go
index f9325c2..a201694 100644
--- a/services/nvpair-engine-manager/install.go
+++ b/services/nvpair-engine-manager/install.go
@@ -70,7 +70,7 @@ func (e *Executor) Install(ctx context.Context, engine string) error {
// Escape hatch: vendor-script install with no checksum. Logged
// loudly so the weaker guarantee is never silent.
slog.Warn("running UNPINNED script install (no checksum verification)", "engine", engine)
- e.emitInstallProgress(engine, "installing", 50)
+ e.emitInstallProgress(engine, "installing", 0)
argv, err := resolveArgs(inst.Script, vars)
if err != nil {
e.reportInstallFailed(engine, err)
@@ -94,7 +94,7 @@ func (e *Executor) Install(ctx context.Context, engine string) error {
}
defer os.Remove(dp)
vars["download"] = dp
- e.emitInstallProgress(engine, "verified", 50)
+ e.emitInstallProgress(engine, "verified", 0)
}
if len(inst.Artifacts) > 0 {
paths, artifactVars, err := e.downloadInstallArtifacts(ctx, engine, inst.Artifacts)
@@ -109,7 +109,7 @@ func (e *Executor) Install(ctx context.Context, engine string) error {
e.emitInstallProgress(engine, "verified", 50)
}
if len(inst.Run) > 0 {
- e.emitInstallProgress(engine, "installing", 75)
+ e.emitInstallProgress(engine, "installing", 0)
args, err := resolveArgs(inst.Run, vars)
if err != nil {
e.reportInstallFailed(engine, err)
@@ -456,8 +456,7 @@ func runManifestCommand(ctx context.Context, argv []string, environment map[stri
}
func (e *Executor) reportInstallFailed(engine string, err error) {
- e.notify("engine:install-progress", map[string]any{"engine": engine, "stage": "failed", "percent": -1, "error": err.Error()})
- e.progress.publish(ProgressEvent{Engine: engine, Op: "install", Stage: "failed", Percent: -1, Message: err.Error()})
+ e.emitInstallFrame(engine, "failed", -1, err.Error())
e.reporter.report(serviceError{
ID: installFailedID(engine), Message: err.Error(),
Severity: "error", Action: "retry", EngineType: engine, Operation: "install",
diff --git a/services/nvpair-engine-manager/progress.go b/services/nvpair-engine-manager/progress.go
index e8c4dd5..bbe05d5 100644
--- a/services/nvpair-engine-manager/progress.go
+++ b/services/nvpair-engine-manager/progress.go
@@ -17,10 +17,10 @@ type ProgressEvent struct {
Message string `json:"message,omitempty"`
}
-// wirePercentIncluded reports whether a pull progress percent should appear on
-// the wire. Zero means indeterminate (CLI pulls without byte progress); negative
-// values are terminal error sentinels. Install progress still always includes
-// percent (including 0) via emitInstallProgress.
+// wirePercentIncluded reports whether an install or pull progress percent should
+// appear on the wire. Zero means indeterminate (an opaque install command, or a
+// CLI pull or download without byte progress); negative values are terminal
+// error sentinels.
func wirePercentIncluded(pct int) bool {
return pct > 0 || pct < 0
}
diff --git a/services/nvpair-engine-manager/progress_test.go b/services/nvpair-engine-manager/progress_test.go
index a29eaec..9674e41 100644
--- a/services/nvpair-engine-manager/progress_test.go
+++ b/services/nvpair-engine-manager/progress_test.go
@@ -4,6 +4,13 @@
package main
import (
+ "context"
+ "crypto/sha256"
+ "encoding/hex"
+ "net/http"
+ "net/http/httptest"
+ "path/filepath"
+ "sync"
"testing"
"time"
)
@@ -65,15 +72,24 @@ func TestProgressHubDropsWhenFull(t *testing.T) {
// TestEmitInstallProgressPublishesToHub verifies the executor helper both
// notifies and feeds the hub.
func TestEmitInstallProgressPublishesToHub(t *testing.T) {
- e := &Executor{progress: newProgressHub()}
+ var gotParams map[string]any
+ e := &Executor{
+ progress: newProgressHub(),
+ emit: func(_ string, params any) {
+ gotParams, _ = params.(map[string]any)
+ },
+ }
ch, cancel := e.progress.subscribe("ollama")
defer cancel()
- e.emitInstallProgress("ollama", "installing", 75)
+ e.emitInstallProgress("ollama", "downloading", 42)
+ if gotParams["stage"] != "downloading" || gotParams["percent"] != 42 {
+ t.Fatalf("unexpected notification params: %+v", gotParams)
+ }
select {
case ev := <-ch:
- if ev.Op != "install" || ev.Stage != "installing" || ev.Percent != 75 {
+ if ev.Op != "install" || ev.Stage != "downloading" || ev.Percent != 42 {
t.Fatalf("unexpected event: %+v", ev)
}
case <-time.After(time.Second):
@@ -81,6 +97,119 @@ func TestEmitInstallProgressPublishesToHub(t *testing.T) {
}
}
+// TestEmitInstallProgressOmitsIndeterminatePercent verifies an unmeasurable
+// install step (percent 0) reaches the wire without a percent, so the UI shows
+// the stage alone instead of a made-up number.
+func TestEmitInstallProgressOmitsIndeterminatePercent(t *testing.T) {
+ var gotParams map[string]any
+ e := &Executor{
+ progress: newProgressHub(),
+ emit: func(_ string, params any) {
+ gotParams, _ = params.(map[string]any)
+ },
+ }
+ ch, cancel := e.progress.subscribe("ollama")
+ defer cancel()
+
+ e.emitInstallProgress("ollama", "installing", 0)
+
+ if gotParams["engine"] != "ollama" || gotParams["stage"] != "installing" {
+ t.Fatalf("unexpected notification params: %+v", gotParams)
+ }
+ if _, ok := gotParams["percent"]; ok {
+ t.Fatalf("indeterminate install progress carried a percent: %+v", gotParams)
+ }
+ select {
+ case ev := <-ch:
+ if ev.Stage != "installing" || ev.Percent != 0 {
+ t.Fatalf("unexpected hub event: %+v", ev)
+ }
+ case <-time.After(time.Second):
+ t.Fatal("emitInstallProgress did not publish to the hub")
+ }
+}
+
+// TestInstallFlowReportsOnlyMeasurablePercents drives a full fetch+run install
+// and checks that only measurable (download) and terminal frames carry a
+// percent; the verified and installing steps are indeterminate.
+func TestInstallFlowReportsOnlyMeasurablePercents(t *testing.T) {
+ payload := []byte("engine payload")
+ sum := sha256.Sum256(payload)
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ _, _ = w.Write(payload)
+ }))
+ defer srv.Close()
+ bin := filepath.Join(t.TempDir(), "engine"+exeExt())
+ m := &Manifest{
+ Engine: "fake", DisplayName: "Fake", ManifestVersion: 1,
+ Platforms: map[string]Platform{hostKey(): {
+ Detect: []string{bin},
+ Install: &Install{
+ Fetch: &Fetch{URL: srv.URL, SHA256: hex.EncodeToString(sum[:])},
+ Run: []string{fakeEngineBin, "touch", bin},
+ Mode: "user",
+ },
+ Runtime: Runtime{Bin: fakeEngineBin},
+ }},
+ }
+
+ var mu sync.Mutex
+ var frames []map[string]any
+ reg := NewRegistry()
+ reg.engines[m.Engine] = m
+ ex := NewExecutor(reg, NewReporter(nil), func(method string, params any) {
+ if method != "engine:install-progress" {
+ return
+ }
+ p, _ := params.(map[string]any)
+ mu.Lock()
+ frames = append(frames, p)
+ mu.Unlock()
+ }, t.TempDir())
+ ex.detectTimeout = 2 * time.Second
+
+ if err := ex.Install(context.Background(), m.Engine); err != nil {
+ t.Fatalf("install: %v", err)
+ }
+
+ mu.Lock()
+ defer mu.Unlock()
+ stages := map[string]bool{}
+ measuredDownload := false
+ for _, f := range frames {
+ stage, _ := f["stage"].(string)
+ stages[stage] = true
+ pct, hasPct := f["percent"]
+ switch stage {
+ case "downloading":
+ if hasPct {
+ if p, _ := pct.(int); p <= 0 {
+ t.Errorf("downloading frame carried a non-positive percent: %+v", f)
+ }
+ measuredDownload = true
+ }
+ case "verified", "installing":
+ if hasPct {
+ t.Errorf("%s frame carried a percent: %+v", stage, f)
+ }
+ case "done":
+ if pct != 100 {
+ t.Errorf("done frame percent = %v, want 100", pct)
+ }
+ default:
+ t.Errorf("unexpected install stage %q: %+v", stage, f)
+ }
+ }
+ if !measuredDownload {
+ t.Errorf("no downloading frame carried a measured percent; got %+v", frames)
+ }
+ for _, want := range []string{"downloading", "verified", "installing", "done"} {
+ if !stages[want] {
+ t.Errorf("missing %q frame; got %+v", want, frames)
+ }
+ }
+}
+
// TestEmitPullProgressNotifiesAndPublishes verifies the pull helper emits the
// local engine:pull-progress notification (with op/message) and also feeds the
// hub, so a local pull surfaces progress like a remote pull.
diff --git a/services/nvpair-engine-manager/spec.md b/services/nvpair-engine-manager/spec.md
index 66d0c1b..6f4c1a9 100644
--- a/services/nvpair-engine-manager/spec.md
+++ b/services/nvpair-engine-manager/spec.md
@@ -160,11 +160,14 @@ Requests (caller → service):
| `shutdown` | — | `null` |
| `log/set-level` | `{ level }` | `{ level }` |
-Notifications (service → caller): `ready{version}`, `engine:state-changed{EngineStatus}`, `engine:models-changed{engine, models}` (pushed when an engine's loaded-in-memory model set changes; `models` is the full `engine:models` shape incl. `loadedByEngine`), `engine:install-progress{engine, stage, percent}`, `engine:pull-progress{engine, op, stage, percent, message}` (live progress for a local model pull driven via `engine:action{action:"pull_model"}` — the local counterpart of `engine:remote-progress`), `engine:remote-progress{opId, node, engine, op, stage, percent, message}` (live progress relayed from a remote install/pull), and `errors:report` / `errors:clear` (consumed by `nvpair-errors` via the Broker). `install` / `start` / `stop` / `restart` / `action` / `remote-*` each run in their own goroutine so the read loop never blocks; their responses arrive when the op completes.
+Notifications (service → caller): `ready{version}`, `engine:state-changed{EngineStatus}`, `engine:models-changed{engine, models}` (pushed when an engine's loaded-in-memory model set changes; `models` is the full `engine:models` shape incl. `loadedByEngine`), `engine:install-progress{engine, stage, percent?, error?}` (`error` on the terminal `failed` frame), `engine:pull-progress{engine, op, stage, percent?, message}` (live progress for a local model pull driven via `engine:action{action:"pull_model"}` — the local counterpart of `engine:remote-progress`), `engine:remote-progress{opId, node, engine, op, stage, percent?, message}` (live progress relayed from a remote install/pull), and `errors:report` / `errors:clear` (consumed by `nvpair-errors` via the Broker). `install` / `start` / `stop` / `restart` / `action` / `remote-*` each run in their own goroutine so the read loop never blocks; their responses arrive when the op completes.
+
+`percent` on all three progress notifications follows one rule: it is present only when the step is measurable (download bytes, byte-progress pulls) or terminal (`100` on install `done` / `already-installed`, `-1` on install `failed` and pull `error`). An indeterminate step omits it — the install `verified` and `installing` stages always do, because the install command is opaque — and a consumer renders the stage alone rather than a percentage.
Example `engine:install-progress` (stdout):
```json
{"jsonrpc":"2.0","method":"engine:install-progress","params":{"engine":"ollama","stage":"downloading","percent":42}}
+{"jsonrpc":"2.0","method":"engine:install-progress","params":{"engine":"ollama","stage":"installing"}}
```
Example `engine:pull-progress` (stdout):