Skip to content

fix(desktop): word localmodels setup reasons by code in the setup window - #235

Closed
oldwinter53 wants to merge 1 commit into
mainfrom
oldwinter/014-e1
Closed

oldwinter53 wants to merge 1 commit into
mainfrom
oldwinter/014-e1

Conversation

@oldwinter53

Copy link
Copy Markdown

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 inspect reason into its own English words, chosen by reason code. It never shows the tool's message.

  • Root cause (P2-5). setup.html printed models.reasons[0].message as 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 parallel reasonMessages array, so the counts that localmodels 0.1.0.dev40 adds (gpuIndex, freeBytes, requiredBytes) could not reach the page.
  • Contract (linger-installer SetupReport.localModels.reasons): each reason is now {code, message, gpuIndex?, freeBytes?, requiredBytes?}. reasonMessages is gone. The schema calls message diagnostic text for logs that is never shown or matched on. setup-plan.ts keeps only valid non-negative counts. It also drops the unused assertLocalModelsEligible, the only other reader of the messages.
  • Desktop main (local-server.ts): the page state gets {code, gpuIndex?, freeBytes?, requiredBytes?} only. The tool's words go to the local_server.inspected log.
  • Setup page copy, by code:
    • 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 to stack.memory.
    • gpu-sharing-required, plan-unavailable (held: another AI app holds the memory; otherwise no model fits), facts-unavailable, unsupported-platform, and the dev39 code gpu-ownership-unknown (still mapped because main pins dev39). Any other code gets a generic sentence.
  • Local model card (P2-5): under Customize, once the check ends the card stays visible. It is disabled and reads "Not available on this computer" with the reason, instead of being hidden.
  • P2-8: "menu bar" now shows only on macOS. Windows and Linux say "system tray".
  • P2-14 (Linger part): the card's memory figure is the whole stack's budget, so it now reads "12 GB memory with its services". That makes clear why it is larger than the model-only figure on the Local models page. The recommendation policy itself is GitLab chore: rename Simplex and Co-Workspace identifiers to Linger #17.
  • P2-22: no code change. Commit 5f945e0 (in 0.1.3) added white-space: nowrap and a wrapping action row. I rendered offline.html in Chromium in the failed state at 1280×820:
    • Before that commit, Try Again wrapped and was clipped (scrollHeight 43 in a 36 px button), matching the verify-mac screenshot.
    • Now it fits on one line (scrollHeight 36) and the action row wraps instead.

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 owns local-models.ts:404-417.
  • GATEWAY_HOME_NOT_PRIVATE, a library error cause on the Local models page, goes to E2.
  • The dev40 pin bump also goes to BC2.

gpu-sharing-required cannot 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_ready path. 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:
    • GPU and RAM counts.
    • Copy for every code, with a check that the tool's message never shows on the page.
    • The disabled card with its reason.
    • "with its services".
    • menu bar or system tray per platform.

Fast checks:

  • make check BASE=origin/main passed check-repository, check-docs, check-contracts, check-teamhub-cli and check-voice-runtime in the parallel run.
  • The following lanes failed in the parallel run and passed when re-run one at a time with mise shims off PATH: check-packages, check-scripts-fast, check-web and check-node-services (load timeouts, plus install.test.ts under a fake HOME). check-installer, check-desktop and check-computer passed in that one-at-a-time run.
  • make check-repository-gate BASE=origin/main passed.

Real-machine checks for the 0.1.4 RC round

Run these with the dev40 pin from BC2:

  • Windows (homewin, display GPU in use by dwm and browsers): the Quick Install line and Customize > Local model show the page's words, never the tool's message. With dev40, gpu-memory-required names GPU 0 with its free and needed memory, and the card stays visible and disabled with the reason. Permissions says "system tray".
  • macOS (macmini, 24 GB): fill memory as in SET-06. The line shows "Other programs are using the memory it needs (X free, Y needed)", the held card shows the same figures, and Check again clears it. Customize shows "… memory with its services". The start-failure page shows Try Again on one line.
  • Linux (shared GPU host): the reason is worded, never printed raw. Permissions says "system tray".

🤖 Generated with Claude Code

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>

@linger-review linger-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 no gpu-memory-required and puts no counts on reasons, so on that tool the VRAM figures exist only in stack.memory (freeMemory.vramFreeBytes / vramRequiredBytes). local-server.ts:815 still 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-required without 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* in reasonText/heldLine, as the old code did. Keep the test case with vramFreeBytes in freeMemory.

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

  • SetupReason is documented as "when eligible, for what could still stop the install" (shared/setup.ts:162). Before this PR the eligible line appended reasons[0].message. Now the model ? 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) when models.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-why is hidden while customizing, so the reason exists only in #local-model-needs inside <button disabled>. Keyboard users can't Tab to a disabled button.
  • The Pi-runtime gating described in apps/desktop/AGENTS.md uses aria-disabled so 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 reasons items are objects, reasonMessages is removed, and the generated types.ts matches the YAML edit. check (contracts) will confirm.
  • assertLocalModelsEligible had 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: ok in setup-plan.ts and bytes() in local-server.ts drop negative and non-finite counts, and this is tested.
  • No tool text reaches the page: local-server.ts builds SetupReason from code plus counts only, and the tool's message goes to local_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.platform and is tested for darwin, win32 and linux.
  • apps/desktop/AGENTS.md is 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_ready path.

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). changes passed. 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.

@oldwinter53

Copy link
Copy Markdown
Author

Consolidated into #244 with #235, #236 and #238 (same commits, replayed on the newest main; the body carries this PR's description, tests and real-machine checks). Please review there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants