From c85d13ac4309d6c0cf9f04dd093bf4b655500e76 Mon Sep 17 00:00:00 2001 From: Dongdong Chen Date: Thu, 19 Nov 2026 03:20:21 +0800 Subject: [PATCH] fix(desktop): word localmodels setup reasons by code in the setup window The setup window printed the localmodels tool's reason message verbatim and hid the Local model card when no model was offered. The installer's setup report now carries each reason as {code, message, gpuIndex?, freeBytes?, requiredBytes?}; the desktop passes the code and counts to the page and keeps the tool's words in its log. The page words every code (gpu-memory-required and free-memory-required with free against needed memory, gpu-sharing-required, plan-unavailable, facts-unavailable, unsupported-platform, and dev39's gpu-ownership-unknown), keeps the card visible and disabled with the reason, names the system tray off macOS and labels the card's memory as the whole stack's. Co-Authored-By: Claude Opus 5.5 --- apps/desktop/AGENTS.md | 19 +- apps/desktop/src/main/local-server.test.ts | 19 +- apps/desktop/src/main/local-server.ts | 61 +++--- apps/desktop/src/shared/setup.ts | 22 ++- apps/desktop/src/shell/setup-page.test.ts | 171 ++++++++++++---- apps/desktop/src/shell/setup.html | 186 ++++++++++++------ apps/linger-installer/src/server/api.test.ts | 2 +- apps/linger-installer/src/web/App.test.tsx | 5 +- .../src/generated/linger-installer/types.ts | 14 +- .../openapi/linger-installer/openapi.yaml | 26 ++- .../local-installation/src/setup-plan.test.ts | 68 +++++-- packages/local-installation/src/setup-plan.ts | 43 ++-- 12 files changed, 457 insertions(+), 179 deletions(-) diff --git a/apps/desktop/AGENTS.md b/apps/desktop/AGENTS.md index b82fc3cf4..19df59680 100644 --- a/apps/desktop/AGENTS.md +++ b/apps/desktop/AGENTS.md @@ -138,8 +138,14 @@ Gateway and runs Agents. The daemon exits with the app. Quick Install installs the `recommendation` of the localmodels setup report (`installer.js --inspect`, run once as the setup window opens): `local-models` is the planned model served by Pi, shown with the model, - GPU, memory and download, plus the tool's caveat when it has one; - otherwise the named runtime, with the tool's reason for no local model. + GPU, memory and download (the card's memory is the whole stack's, so + "with its services"); otherwise the named runtime, with why there is no + local model. The page words each reason by its code and the counts it + carries (`gpuIndex`, `freeBytes`, `requiredBytes`); the tool's message + goes only to the main process log (`local_server.inspected`), never to + the page. Under Customize the Local model card stays visible once the + check ends: disabled, "Not available on this computer", with that reason. + Off macOS the page names the system tray, not the menu bar. Under Customize the local model runs only behind Pi: with another runtime it is greyed (`aria-disabled`, still focusable), does not toggle, and says "Local models are only available with the Pi runtime."; choosing another @@ -149,10 +155,11 @@ Gateway and runs Agents. The daemon exits with the app. memory it needs now; a tool before that field marks it by `basis: "capacity"` or reason `free-memory-required`, either one), the install would plan again against the memory free then and stop, so the local model - shows on hold and is not offered. With the tool's `stack.memory` the page - says "quit other programs first; it needs X of memory, Y is free" (and the - graphics memory on a discrete GPU), adding the tool's words for any other - reason code; without it, the tool's reason. Quick Install installs the + shows on hold and is not offered. `gpu-memory-required` names the GPU and + its free against needed memory and says to close programs that use the + GPU; `free-memory-required` gives the RAM counts (from the reason, or the + tool's `stack.memory` when the reason has none). The page still words + `gpu-ownership-unknown`, which localmodels 0.1.0.dev39 reports. Quick Install installs the runtime the installer recommends instead, and Check again (`local.recheck`) runs the check again. A tool before `stack.state` still recommends `local-models` there, so the installer's setup adapter diff --git a/apps/desktop/src/main/local-server.test.ts b/apps/desktop/src/main/local-server.test.ts index 65b421c0f..dab12143e 100644 --- a/apps/desktop/src/main/local-server.test.ts +++ b/apps/desktop/src/main/local-server.test.ts @@ -113,8 +113,11 @@ if (args.includes("--inspect")) { } process.stderr.write("Checked this computer in 1.5s.\n"); const lowMemory = eligible && fs.existsSync(path.join(home, "low-memory")); - const reasons = eligible ? (lowMemory ? ["free-memory-required"] : []) : ["facts-unavailable"]; - const reasonMessages = eligible ? (lowMemory ? ["Close other programs before installing."] : []) : ["nvidia-smi was not found"]; + const reasons = eligible + ? lowMemory + ? [{ code: "free-memory-required", message: "Close other programs before installing.", freeBytes: 2899102924, requiredBytes: 13689304433 }] + : [] + : [{ code: "facts-unavailable", message: "nvidia-smi was not found" }]; // With the plan priced on capacity, the installer recommends a runtime. const recommendation = eligible && !lowMemory ? "local-models" : "codex"; const local = { @@ -122,7 +125,7 @@ if (args.includes("--inspect")) { state: lowMemory ? "blocked-now" : eligible ? "ready" : "unavailable", ...(lowMemory ? { basis: "capacity", memory: { ramAvailableBytes: 2899102924, ramRequiredBytes: 13689304433 } } : {}), }; - process.stdout.write(JSON.stringify({ hardware, localModels: { ...local, reasons, reasonMessages, estimate }, recommendation }) + "\n"); + process.stdout.write(JSON.stringify({ hardware, localModels: { ...local, reasons, estimate }, recommendation }) + "\n"); process.exit(0); } if (args.includes("--resume")) { @@ -1612,14 +1615,13 @@ describe("LocalServerModule", () => { expect(f.module.status().localModels).toMatchObject({ state: "checked", eligible: false, - reasons: [ - { code: "facts-unavailable", message: "nvidia-smi was not found" }, - ], + reasons: [{ code: "facts-unavailable" }], recommendation: "codex", }), ); expect(f.module.status().localModels).not.toHaveProperty("model"); - // The log says why, as the localmodels tool did. + // The page gets the code only; the tool's words go to the log. + expect(JSON.stringify(f.module.status())).not.toContain("nvidia-smi"); expect(info).toHaveBeenCalledWith( "local_server.inspected", expect.objectContaining({ @@ -1651,7 +1653,8 @@ describe("LocalServerModule", () => { reasons: [ { code: "free-memory-required", - message: "Close other programs before installing.", + freeBytes: 2899102924, + requiredBytes: 13689304433, }, ], recommendation: "codex", diff --git a/apps/desktop/src/main/local-server.ts b/apps/desktop/src/main/local-server.ts index d69e59d12..d9f615de3 100644 --- a/apps/desktop/src/main/local-server.ts +++ b/apps/desktop/src/main/local-server.ts @@ -69,7 +69,11 @@ import { savedProviderKeys, type ProviderKeyChanges, } from "./provider-keys.js"; -import type { SetupByokCheck, SetupByokConfig } from "../shared/setup.js"; +import type { + SetupByokCheck, + SetupByokConfig, + SetupReason, +} from "../shared/setup.js"; // The pinned linger source this build installs, written by the release build: // downloaded from `url` (or a mirror of it), or bundled in the app at `file`. @@ -123,19 +127,14 @@ export type LocalModelsCheck = readonly gpu?: string; // Present when eligible or when it needs free memory. readonly model?: LocalModel; - // The localmodels tool's code and words for why not, or, when - // eligible, for what could still stop the install. + // The localmodels tool's code for why not, or, when eligible, for + // what could still stop the install, with the counts it carries. readonly reasons?: readonly SetupReason[]; // The localmodels tool's pick for this computer, which Quick Install // installs; the page adds no rule of its own. readonly recommendation?: SetupChoice; }; -export interface SetupReason { - readonly code: string; - readonly message?: string; -} - // A download under way: its bytes so far and in all, and the rate when the // source reports one. partial: the counts cover only the file downloading // now, so nothing says what remains. @@ -600,7 +599,7 @@ export class LocalServerModule implements Module { this.#ctx?.bus.emit("local-server.changed"); }) .then( - (check) => { + ({ check, reasonLog }) => { this.#ctx?.log.info("local_server.inspected", { ms: Date.now() - started, eligible: check.state === "checked" && check.eligible, @@ -610,13 +609,7 @@ export class LocalServerModule implements Module { ...(check.state === "checked" && check.recommendation ? { recommendation: check.recommendation } : {}), - ...(check.state === "checked" && check.reasons - ? { - reasons: check.reasons.map(({ code, message }) => - message ? `${code}: ${message}` : code, - ), - } - : {}), + ...(reasonLog.length ? { reasons: reasonLog } : {}), }); this.#check = check; }, @@ -718,7 +711,11 @@ export class LocalServerModule implements Module { async #inspect( signal: AbortSignal, onDownload: (download: Transfer) => void, - ): Promise { + ): Promise<{ + check: LocalModelsCheck; + // The tool's codes with its words, for the log only. + reasonLog: string[]; + }> { // The app's own Node runs the check, so it needs no download of its own; // installing still uses the pinned Node runtime. const output = await new Promise((resolve, reject) => { @@ -776,7 +773,6 @@ export class LocalServerModule implements Module { state?: unknown; memory?: Record; reasons?: unknown; - reasonMessages?: unknown; estimate?: { model?: unknown; downloadBytes?: unknown; @@ -825,12 +821,26 @@ export class LocalServerModule implements Module { : {}), } : undefined; - const strings = (value: unknown) => - Array.isArray(value) ? value.map(String) : []; - const messages = strings(report.localModels.reasonMessages); - const reasons = strings(report.localModels.reasons).map( - (code, index): SetupReason => - messages[index] ? { code, message: messages[index] } : { code }, + const listed = Array.isArray(report.localModels.reasons) + ? (report.localModels.reasons as Record[]).filter( + (reason) => typeof reason?.code === "string", + ) + : []; + // The page words each reason by its code and counts, never the tool's. + const reasons = listed.map((reason): SetupReason => { + const counted = (key: "gpuIndex" | "freeBytes" | "requiredBytes") => + bytes(reason[key]) !== null ? { [key]: reason[key] as number } : {}; + return { + code: reason.code as string, + ...counted("gpuIndex"), + ...counted("freeBytes"), + ...counted("requiredBytes"), + }; + }); + const reasonLog = listed.map(({ code, message }) => + typeof message === "string" && message + ? `${code}: ${message}` + : `${code}`, ); const pick = report.recommendation; // The local model is recommended only with a model the page can show. @@ -840,7 +850,7 @@ export class LocalServerModule implements Module { (pick !== "local-models" || eligible) ? (pick as SetupChoice) : undefined; - return { + const check: LocalModelsCheck = { state: "checked", eligible, memoryBytes: hardware.totalMemoryBytes, @@ -864,6 +874,7 @@ export class LocalServerModule implements Module { ...(reasons.length ? { reasons } : {}), ...(recommendation ? { recommendation } : {}), }; + return { check, reasonLog }; } // Logs how long one part of setup took, so a slow setup says which part. diff --git a/apps/desktop/src/shared/setup.ts b/apps/desktop/src/shared/setup.ts index ef61ef8de..3ec2ccd49 100644 --- a/apps/desktop/src/shared/setup.ts +++ b/apps/desktop/src/shared/setup.ts @@ -123,6 +123,18 @@ export interface SetupTransfer { readonly partial?: boolean; } +// The localmodels tool's reason code with the counts it carries. Its words +// stay in the main process log; the page has its own copy per code. +export interface SetupReason { + readonly code: string; + // On gpu-memory-required: the card other programs hold memory on. + readonly gpuIndex?: number; + // The memory free now and what the install needs free: that card's VRAM, + // or RAM on free-memory-required. + readonly freeBytes?: number; + readonly requiredBytes?: number; +} + export type SetupLocalModelsCheck = | { readonly state: "unchecked" | "unavailable" } // While the check first downloads the localmodels tool: its bytes. @@ -147,12 +159,10 @@ export type SetupLocalModelsCheck = readonly diskBytes: number | null; readonly memoryBytes: number | null; }; - // The localmodels tool's code and words for why not, or, when - // eligible, for what could still stop the install. - readonly reasons?: readonly { - readonly code: string; - readonly message?: string; - }[]; + // The localmodels tool's code for why not, or, when eligible, for + // what could still stop the install, with the counts it carries. The + // page words each code itself. + readonly reasons?: readonly SetupReason[]; // The localmodels tool's pick, which Quick Install installs: // "local-models" is the model above served by Pi. readonly recommendation?: SetupChoice; diff --git a/apps/desktop/src/shell/setup-page.test.ts b/apps/desktop/src/shell/setup-page.test.ts index a837c6bc9..fa4b1e352 100644 --- a/apps/desktop/src/shell/setup-page.test.ts +++ b/apps/desktop/src/shell/setup-page.test.ts @@ -9,6 +9,7 @@ import type { SetupCommand, SetupLocalAccount, SetupLocalModelsCheck, + SetupReason, SetupState, } from "../shared/setup.js"; @@ -203,12 +204,13 @@ const small: SetupLocalModelsCheck = { eligible: false, memoryBytes: 8 * GB, diskFreeBytes: 100 * GB, - // A code the page never parses: it shows only the message. - reasons: [ - { code: "upstream_policy", message: "No model fits this computer." }, - ], + reasons: [{ code: "plan-unavailable" }], recommendation: "codex", }; +// The tool's own words, which the page must never show. +const TOOL_WORDS = "GPU service owners unknown; explicit sharing"; +const reason = (fields: SetupReason): SetupReason => + ({ ...fields, message: TOOL_WORDS }) as SetupReason; // The model fits the hardware, but other programs hold its memory now. const held: SetupLocalModelsCheck = { state: "checked", @@ -222,13 +224,7 @@ const held: SetupLocalModelsCheck = { diskBytes: 8 * GB, memoryBytes: 12 * GB, }, - reasons: [ - { - code: "free-memory-required", - message: - "Other programs are using memory it needs (now 2.7 GB of RAM is available).", - }, - ], + reasons: [reason({ code: "free-memory-required" })], recommendation: "codex", }; const welcome = (localModels: SetupLocalModelsCheck): SetupState => { @@ -263,7 +259,7 @@ describe("setup page Quick Install recommendation", () => { "Recommended for this computer: Codex", ); expect($("plan-why").textContent).toBe( - "No local model: No model fits this computer.", + "No local model fits this computer.", ); expect($("local-row").hidden).toBe(true); $("local-install").click(); @@ -278,7 +274,7 @@ describe("setup page Quick Install recommendation", () => { "Recommended for this computer: Codex", ); expect($("plan-why").textContent).toBe( - "Local model on hold: Other programs are using memory it needs (now 2.7 GB of RAM is available). Quick Install sets up Codex now, or choose Check again once memory is free.", + "Local model on hold. Other programs are using the memory it needs. Close other programs. Quick Install sets up Codex now, or choose Check again once memory is free.", ); expect($("local-recheck").hidden).toBe(false); $("local-customize").click(); @@ -313,25 +309,40 @@ describe("setup page Quick Install recommendation", () => { }); it("says how much memory a held local model needs and how much is free", async () => { - const counted = ( - code: string, - message: string, - vram = false, - ): SetupLocalModelsCheck => ({ + const withCounts = (reasons: SetupReason[]): SetupLocalModelsCheck => ({ ...held, freeMemory: { ramAvailableBytes: 2899102924, ramRequiredBytes: 13689304433, - ...(vram ? { vramFreeBytes: 3 * GB, vramRequiredBytes: 9 * GB } : {}), + vramFreeBytes: 3 * GB, + vramRequiredBytes: 9 * GB, }, - reasons: [{ code, message }], + reasons, }); + const customizeLocal = () => { + $("local-customize").click(); + document + .querySelector( + '[data-plan="source"] [data-value="local"]', + )! + .click(); + }; + // The GPU and the RAM each name what is free and what the install needs. await openPage( welcome( - counted( - "free-memory-required", - "Other programs are using memory it needs.", - ), + withCounts([ + reason({ + code: "gpu-memory-required", + gpuIndex: 1, + freeBytes: 3 * GB, + requiredBytes: 9 * GB, + }), + reason({ + code: "free-memory-required", + freeBytes: 2899102924, + requiredBytes: 13689304433, + }), + ]), ), "welcome", ); @@ -339,31 +350,95 @@ describe("setup page Quick Install recommendation", () => { "Recommended for this computer: Codex", ); expect($("plan-why").textContent).toBe( - "Local model on hold: quit other programs first; it needs 12.7 GB of memory, 2.7 GB is free. Quick Install sets up Codex now, or choose Check again once memory is free.", + "Local model on hold. Other programs are using GPU 1's memory (3.0 GB free, 9.0 GB needed). Close programs that use the GPU, such as games, video or other AI apps. Other programs are using the memory it needs (2.7 GB free, 12.7 GB needed). Close other programs. Quick Install sets up Codex now, or choose Check again once memory is free.", ); expect($("local-recheck").hidden).toBe(false); + customizeLocal(); + expect($("local-sub").textContent).toBe( + "On hold: GPU 1 has 3.0 GB free, needs 9.0 GB", + ); + expect(document.body.textContent).not.toContain(TOOL_WORDS); + // A tool that counts only the plan's memory: the RAM counts from it. + await openPage( + welcome(withCounts([reason({ code: "free-memory-required" })])), + "welcome", + ); + expect($("plan-why").textContent).toBe( + "Local model on hold. Other programs are using the memory it needs (2.7 GB free, 12.7 GB needed). Close other programs. Quick Install sets up Codex now, or choose Check again once memory is free.", + ); + customizeLocal(); + expect($("local-sub").textContent).toBe( + "On hold: 2.7 GB of memory free, needs 12.7 GB", + ); + }); + + it("words every localmodels reason by its code, never the tool's message", async () => { + const cases: [SetupLocalModelsCheck, string][] = [ + [ + { ...held, reasons: [reason({ code: "gpu-sharing-required" })] }, + "Local model on hold. Other work is running on the GPU. Close it.", + ], + [ + { ...held, reasons: [reason({ code: "plan-unavailable" })] }, + "Local model on hold. Another app is holding the memory it needs, such as another AI app. Quit it.", + ], + [ + { ...small, reasons: [reason({ code: "gpu-ownership-unknown" })] }, + "Linger couldn't tell which programs are using the GPU, so it can't share it. Close programs that use the GPU.", + ], + [ + { ...small, reasons: [reason({ code: "facts-unavailable" })] }, + "Linger couldn't read this computer's memory, disk or GPU.", + ], + [ + { ...small, reasons: [reason({ code: "unsupported-platform" })] }, + "Local models don't run on this system.", + ], + [ + { ...small, reasons: [reason({ code: "a-new-code" })] }, + "This computer can't run a local model now.", + ], + ]; + for (const [check, words] of cases) { + await openPage(welcome(check), "welcome"); + expect($("plan-why").textContent).toContain(words); + expect(document.body.textContent).not.toContain(TOOL_WORDS); + } + }); + + it("shows the Local model card disabled with the reason when none can run", async () => { + await openPage( + welcome({ + ...small, + reasons: [reason({ code: "gpu-ownership-unknown" })], + }), + "welcome", + ); $("local-customize").click(); document .querySelector( '[data-plan="source"] [data-value="local"]', )! .click(); - expect($("local-sub").textContent).toBe( - "On hold: 12.7 GB memory needed, 2.7 GB free", + expect($("local-row").hidden).toBe(false); + expect($("local-model").hidden).toBe(false); + expect(($("local-model") as HTMLButtonElement).disabled).toBe(true); + expect($("local-model").getAttribute("aria-checked")).toBe("false"); + expect($("local-model-name").textContent).toBe( + "Not available on this computer", ); - // Another code names what holds the memory, so its words stay. - await openPage( - welcome( - counted( - "plan-unavailable", - "Another inference app holds this Mac's memory; quit it and check again.", - true, - ), - ), - "welcome", + expect($("local-model-needs").textContent).toBe( + "Linger couldn't tell which programs are using the GPU, so it can't share it. Close programs that use the GPU.", ); - expect($("plan-why").textContent).toBe( - "Local model on hold: quit other programs first; it needs 12.7 GB of memory, 2.7 GB is free; graphics memory needs 9.0 GB, 3.0 GB is free. Another inference app holds this Mac's memory; quit it and check again. Quick Install sets up Codex now, or choose Check again once memory is free.", + expect(($("local-install") as HTMLButtonElement).disabled).toBe(true); + expect(document.body.textContent).not.toContain(TOOL_WORDS); + }); + + it("says the stack's memory covers the model and its services", async () => { + await openPage(welcome(capable), "welcome"); + $("local-customize").click(); + expect($("local-model-needs").textContent).toBe( + "6 GB download · 8 GB disk · 12 GB memory with its services", ); }); @@ -605,6 +680,24 @@ describe("setup page Quick Install recommendation", () => { }); }); +describe("setup page permissions", () => { + it("names the menu bar on macOS and the system tray elsewhere", async () => { + const permissions = () => + document.querySelector('[data-step="permissions"]')!.textContent!; + for (const [platform, place] of [ + ["darwin", "menu bar"], + ["win32", "system tray"], + ["linux", "system tray"], + ] as const) { + await openPage({ ...welcome(capable), platform }, "welcome"); + const words = permissions().replace(/\s+/g, " "); + expect(words).toContain(`Change these later from the ${place} or`); + expect(words).toContain(`Start in the ${place} when you log in.`); + if (platform !== "darwin") expect(words).not.toContain("menu bar"); + } + }); +}); + describe("setup page download progress", () => { const installing = (transfer?: SetupState["localServer"]["transfer"]) => { const base = state("installing"); diff --git a/apps/desktop/src/shell/setup.html b/apps/desktop/src/shell/setup.html index dd13c3f12..109de9257 100644 --- a/apps/desktop/src/shell/setup.html +++ b/apps/desktop/src/shell/setup.html @@ -2057,7 +2057,8 @@

Connect this computer

A few permissions

- Change these later from the menu bar or in your system settings. + Change these later from the menu bar or in your + system settings.

@@ -2162,7 +2163,10 @@

A few permissions

>
Open at loginStart in the menu bar when you log in. + >Start in the menu bar when you log + in.