Repository navigation
fix(desktop): word localmodels setup reasons by code in the setup window - #235
oldwinter53 wants to merge 1 commit into
Conversation
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 <noreply@anthropic.com>
There was a problem hiding this comment.
Approve with nits (2 P2, 1 P3)
Scope: base main, merge base 080cbcf9, 1 commit, 12 files, reviewed at c85d13ac. Loaded the coderbook, ponytail-review and karpathy-guidelines skills (ponytail-review sections 1–3 used). Ran in a separate session.
Findings
P2: with the pinned localmodels dev39, a GPU-bound hold no longer shows any GPU memory figures. apps/desktop/src/shell/setup.html:2580 (reasonText / heldLine)
- Main still pins
0.1.0.dev39(scripts/installs/stack.sh:5). dev39 has nogpu-memory-requiredand puts no counts on reasons, so on that tool the VRAM figures exist only instack.memory(freeMemory.vramFreeBytes/vramRequiredBytes).local-server.ts:815still parses them, but the page no longer reads them. - Before this PR, a held hold on a discrete GPU said "graphics memory needs 9.0 GB, 3.0 GB is free". The old test asserting that text was removed. Now
free-memory-requiredwithout counts falls back to RAM only. - Failure case: a Windows or Linux box whose RAM is fine but whose VRAM is taken (for example 20 GB RAM free against 12.7 GB needed, 3 GB VRAM free against 9 GB needed). The page says "Other programs are using the memory it needs (20 GB free, 12.7 GB needed)", and the held card says "On hold: 20 GB of memory free, needs 12.7 GB". That contradicts itself and doesn't point at the GPU.
- This lasts until BC2's dev40 pin bump lands. That bump isn't in this PR, and the release may ship without it.
- Fix: when no reason carries GPU counts, fall back to
freeMemory.vram*inreasonText/heldLine, as the old code did. Keep the test case withvramFreeBytesinfreeMemory.
P2: reasons on an eligible check are now dropped silently, and the PR description doesn't say so. apps/desktop/src/shell/setup.html:2750
SetupReasonis documented as "when eligible, for what could still stop the install" (shared/setup.ts:162). Before this PR the eligible line appendedreasons[0].message. Now themodel ?branch shows only model, GPU, memory and download.- The AGENTS.md edit removes "plus the tool's caveat when it has one", but the PR body only says the tool's words are replaced by the page's words. It doesn't say that eligible caveats disappear entirely.
- Failure case: an eligible report with any reason, for example
gpu-sharing-required, which the PR itself maps. The user sees no warning, and the install may then fail on exactly that condition. - Fix: append
reasonsText(models, false)whenmodels.reasons?.length, or state the removal in the PR description.
P3: under Customize, the "Not available" reason is reachable only inside a disabled button. apps/desktop/src/shell/setup.html:2844
#plan-whyis hidden while customizing, so the reason exists only in#local-model-needsinside<button disabled>. Keyboard users can't Tab to a disabled button.- The Pi-runtime gating described in
apps/desktop/AGENTS.mdusesaria-disabledso the control stays focusable. - Fix: use
aria-disabled="true"with the click guard, or render the reason in#local-sub, outside the button.
Verified as fine
- Contract change: the OpenAPI
reasonsitems are objects,reasonMessagesis removed, and the generatedtypes.tsmatches the YAML edit.check (contracts)will confirm. assertLocalModelsEligiblehad no remaining callers (git grep), so deleting it is correct.- Rollout: the desktop runs the installer from the source it pins, so the two ship together. If an older installer sends string reasons,
typeof reason?.code === "string"drops them and the page falls back to its generic sentence. It does not crash. - Count validation:
okinsetup-plan.tsandbytes()inlocal-server.tsdrop negative and non-finite counts, and this is tested. - No tool text reaches the page:
local-server.tsbuildsSetupReasonfromcodeplus counts only, and the tool's message goes tolocal_server.inspected. Tests assert this in both main and the page. - Copy is chosen by structured
code, not by matching the tool's prose, as the repo convention requires. The default branch covers unknown codes. - The menu bar / system tray text switches on
state.platformand is tested for darwin, win32 and linux. apps/desktop/AGENTS.mdis updated for the new page behavior.- No CJK characters were added and no
apps/*code imports another app's source. Nothing touches the user message →provider_readypath.
Process notes
- One commit, no merge commits, with a descriptive commit body.
CI
- At review time most checks were still pending (contracts, desktop, installer, packages, repository-gate, web).
changespassed. Confirm they're green before merging. - I ran no tests locally; the findings come from reading the code and the updated tests.
Automated review by Claude Code
Automated review of c85d13a by Claude Code.
Summary
0.1.4 E1 (FIXLIST P2-5 Linger part, P2-8, P2-14 Linger part, P2-22): the setup window now puts every localmodels
setup inspectreason into its own English words, chosen by reason code. It never shows the tool's message.setup.htmlprintedmodels.reasons[0].messageas is, for example "GPU service owners unknown; explicit sharing cannot skip the unknown-service check". It also hid the Local model card whenever no model was offered. The installer's setup report carried reasons as bare code strings plus a parallelreasonMessagesarray, so the counts that localmodels 0.1.0.dev40 adds (gpuIndex,freeBytes,requiredBytes) could not reach the page.linger-installerSetupReport.localModels.reasons): each reason is now{code, message, gpuIndex?, freeBytes?, requiredBytes?}.reasonMessagesis gone. The schema callsmessagediagnostic text for logs that is never shown or matched on.setup-plan.tskeeps only valid non-negative counts. It also drops the unusedassertLocalModelsEligible, the only other reader of the messages.local-server.ts): the page state gets{code, gpuIndex?, freeBytes?, requiredBytes?}only. The tool's words go to thelocal_server.inspectedlog.gpu-memory-required: "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." The held card reads "On hold: GPU 1 has 3.0 GB free, needs 9.0 GB".free-memory-required: the RAM figures come from the reason. A tool without them falls back tostack.memory.gpu-sharing-required,plan-unavailable(held: another AI app holds the memory; otherwise no model fits),facts-unavailable,unsupported-platform, and the dev39 codegpu-ownership-unknown(still mapped because main pins dev39). Any other code gets a generic sentence.white-space: nowrapand a wrapping action row. I renderedoffline.htmlin Chromium in the failed state at 1280×820:Not in this PR, per the coordinator's split:
pi-extensions-unavailable, a setup binding reason, is handled with the launch-failure page by BC2, which ownslocal-models.ts:404-417.GATEWAY_HOME_NOT_PRIVATE, a library error cause on the Local models page, goes to E2.gpu-sharing-requiredcannot appear in setup today, because the desktop's check always passes--share-gpu(DEFAULT_GPU_SHARING). It is mapped anyway.Critical path: no network round trip or file walk is added on the user message →
provider_readypath. The change only touches the setup check's output parsing and page copy.Tests
Each new or changed test failed before its fix:
packages/local-installation/src/setup-plan.test.ts: structured reasons with counts; invalid counts dropped.apps/desktop/src/main/local-server.test.ts: the page state holds codes and counts only, and the log keeps the tool's words.apps/desktop/src/shell/setup-page.test.ts:Fast checks:
make check BASE=origin/mainpassedcheck-repository,check-docs,check-contracts,check-teamhub-cliandcheck-voice-runtimein the parallel run.check-packages,check-scripts-fast,check-webandcheck-node-services(load timeouts, plusinstall.test.tsunder a fake HOME).check-installer,check-desktopandcheck-computerpassed in that one-at-a-time run.make check-repository-gate BASE=origin/mainpassed.Real-machine checks for the 0.1.4 RC round
Run these with the dev40 pin from BC2:
gpu-memory-requirednames GPU 0 with its free and needed memory, and the card stays visible and disabled with the reason. Permissions says "system tray".🤖 Generated with Claude Code