Skip to content

feat(local-models): upgrade UX, agent setup, and model telemetry - #240

Closed
oldwinter53 wants to merge 1 commit into
mainfrom
ws/20261118-local-models-experience-upgrade
Closed

oldwinter53 wants to merge 1 commit into
mainfrom
ws/20261118-local-models-experience-upgrade

Conversation

@oldwinter53

@oldwinter53 oldwinter53 commented Nov 19, 2026 •

Copy link
Copy Markdown

What and why

End-to-end UX, runtime setup, and telemetry improvements for Local Models:

  • Local Computer Daemon & TeamHub:
    • Align PI_CODING_AGENT_DIR with the managed Pi environment (workspace.PiSourceEnvironment).
    • Automatically provision managed Pi off the critical path via background singleflight (localmodels harness status/plan/apply) when a local model reaches loaded.
    • Forward LINGER_LOCALMODELS_CACHE_DIR / LINGER_LOCALMODELS_REUSE_DIRS to simplex-localmodels (LOCALMODELS_CACHE_DIR / LOCALMODELS_REUSE_DIRS) for cross-container weight reuse.
    • Validate and project optional download.source (huggingface | modelscope | custom | cache), download.connections, and load (prepare | start | load | warm, done_steps, total_steps) across Runner Gateway and OpenAPI contracts.
  • Settings > Local models:
    • Smart multi-computer default selection & localStorage persistence with · N loaded / · Offline picker hints.
    • Segmented GPU memory breakdown with explicit free memory and legend, semantic card hierarchy, AutoHeight expand transitions, and skeleton loading states.
    • 1-click Use with <Agent>, Open chat, Use when ready queued auto-switch, Make Room handoff option, top-pinned diagnostic callouts, and 2-column ModelFacts (Switch Agent…, pre-filled + New Agent).
    • Download Transfer transparency (ModelScope mirror / Hugging Face / Local cache · parallel connections · binary MB/s (MiB/s)) and determinate Loading step progress (Loading weights to GPU 0 · 57%).
  • Settings > Computers & Rooms:
    • Inline local-model count and loaded-model summary on Computers derived strictly from computer.runtimes (zero /local-models HTTP requests).
    • Human-readable localmodels-library/* model names across Room profiles and dialogs, direct Local models links when Pi has no loaded models, and a 1-click Local models (Pi) quick-switcher menu (role="menu") in the Chat composer.

How it was verified

  • Focused tests for the changed behavior (go test -race ./internal/localmodels/..., go test -race ./internal/app -run 'Test.*LocalModels', Vitest suites across local-models, local-computer, and rooms, and headless Chromium end-to-end visual verification)
  • make check BASE=origin/main or the fast checks of every touched app (make check BASE=origin/main exited 0, 531.9s; make check-packages, lint-go, lint-go-daemon 0 issues; pnpm --filter @linger/web run build:assets passed initial JS budgets at 546.26 kB minified / 184.86 kB gzip / 160.97 kB Brotli)
  • Contracts regenerated if contracts/openapi/ changed (make contracts-generate && make contracts-verify exited 0)

Boundary

  • Documentation updated in apps/computer/local-daemon/README.md and apps/web/AGENTS.md.
  • user message -> provider_ready critical path: adds no network round trip or file walk while the user waits (managed Pi provisioning runs asynchronously in a background singleflight when the library snapshot observes a loaded model).
  • Producer/consumer compatibility: download.source, download.connections, and load are optional in Runner Gateway and OpenAPI schemas, so Linger remains backward-compatible with older simplex-localmodels builds and surfaces transfer/load progress automatically when paired with an updated simplex-localmodels release.

Task: 20261118-local-models-experience-upgrade

@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.

Request changes (1 P1, 4 P2, 1 P3)

Scope: base main at merge base fb2e1537, 1 commit, 43 files (+7482/−418) reviewed at 320f96a. Loaded skills: coderbook, ponytail-review, karpathy-guidelines. This review ran in a separate session.

Findings

P1

1. LINGER_LOCALMODELS_CACHE_DIR / LINGER_LOCALMODELS_REUSE_DIRS forwarding never works in production — apps/computer/local-daemon/internal/localmodels/tool.go:94

  • commandArgs maps the LINGER_LOCALMODELS_* keys to LOCALMODELS_*, but the only environment that reaches it is providerEnvironment (cmd/linger-computer-daemon/main.go:318, and InspectPi). That map is built by computerconfig.RuntimeEnvironment, which drops every LINGER_-prefixed key (internal/computerconfig/environment.go:34).
  • Failure scenario: an operator sets LINGER_LOCALMODELS_CACHE_DIR=/shared/cache in the Daemon environment, as the README and the PR body say to. The key is stripped before Library/Tool see it, so localmodels gets no LOCALMODELS_CACHE_DIR and downloads the weights again. The tests in pi_runtime_test.go:67-110 call commandArgs directly with LINGER_ keys, so they pass even though the production path is broken.
  • Fix: delete the LINGER_ aliasing (lingerCacheDir, lingerReuseDirs, and keyPreference/firstNonEmpty if nothing else uses them). Document setting LOCALMODELS_CACHE_DIR / LOCALMODELS_REUSE_DIRS directly; RuntimeEnvironment already passes those through. Update the README paragraph to match. If the alias has to stay, it must be read in the config module and listed in scripts/env-inventory.json, and a test must go through runtimeProviderEnvironment.

P2

2. PI_CODING_AGENT_DIR is resolved in two places — apps/computer/local-daemon/internal/localmodels/tool.go:85-106

  • runtimeProviderEnvironment (main.go:804) already sets PI_CODING_AGENT_DIR from workspace.PiSourceEnvironment, and that map is the only one passed to Library/Tool. commandArgs then re-records it with case-preference logic and calls PiSourceEnvironment again. Two copies of the same rule can drift apart.
  • Fix: drop the piAgentDir handling and the PiSourceEnvironment call from commandArgs, and keep the single alignment in runtimeProviderEnvironment.

3. buildLoadProgress invents step counts from magic numbers, so progress can go backwards — apps/computer/local-daemon/internal/localmodels/library.go:828

  • load uses total = min(100, rawTotal+2), but warm is hard-coded to 5+done out of 7. The step is guessed from done < 3 / == 3. The PR's own test case (load, Total: 150) produces x/100.
  • Failure scenario: a model loads with Total: 150 and reaches 98/100, then the first warm event reports 5/7. The UI's "Loading … · N%" drops from 98% to 71%.
  • Fix: pass through what localmodels reports (load_step, done, total) and validate it. If a field is missing, leave load unset instead of making up a step model inside the Daemon.

4. The workspace-grant selection rule now exists three times, and the copies disagree — apps/web/src/features/local-models/local-model-agents.ts:170-182

  • buildLocalModelRuntimeUpdate keeps any grant the Agent already holds (even a read-only one), and otherwise falls back to workspace_grants[0], which may also be read-only.
  • The existing rule, findWritableGrant / isMoveTargetComputer in apps/web/src/features/rooms/members/agent-move-target.ts:55-67, treats a Computer without a writable grant as an invalid target. direct-agent-model-switch.tsx:85-96 adds a third copy that requires a writable retained grant.
  • Failure scenario: on a Computer that has only a read-only grant, "Use with " PATCHes the Agent onto a read-only workspace. The Room's switch menu hides that same Computer.
  • Fix: use findWritableGrant (plus a "keep the current grant if it is writable" check) in both new call sites.

5. The quick-switch menu re-implements ActionMenu — apps/web/src/features/rooms/chat/direct-agent-model-switch.tsx:326-480

  • QuickLocalModelMenu hand-rolls about 150 lines: portal, positioning with scroll/resize/ResizeObserver, outside-click on both pointerdown and mousedown, Escape, focus of the first item, and Arrow/Home/End navigation, plus computePopoverPosition.
  • apps/web/src/components/ui/action-menu.tsx already provides header, placement="top-start", items with disabled/separatorBefore, and keyboard handling, and it is used by account-menu.tsx and others.
  • Fix: render the options as ActionMenu items, with the Computer name and the "Local models" link in header or in items. Then delete the custom position and keyboard code and direct-agent-model-switch.css if nothing else needs it.

P3

6. The localmodels-library/ prefix constant has four new copies — apps/web/src/features/rooms/members/use-agent-model-selection.ts:13, rooms/chat/direct-agent-model-switch.tsx:43, local-computer/computer-detail.tsx:63, local-computer/computer-directory.tsx:23

  • local-models-rules.ts:13 already defines piLibraryModelPrefix. Export it, or export a small isLocalLibraryModel(id) helper, and reuse it everywhere.

Verified as fine

  • The background Pi provisioning in Library is single-flight (piEnsuring), backs off exponentially up to 5 min, cancels its retry timer when no model is loaded, and Close() cancels the context and waits on piWg. It runs after refreshMu is released, so it is off the user message → provider_ready path, as the PR states. go test -race -count=1 ./internal/localmodels/ passes locally (114 s).
  • The harness plan is checked against the schema, the runtime and the 64-hex ID before apply --approve. The temporary plan dir is removed. Harness output reads are bounded (4 MiB).
  • withManagedPiPath/withManagedPiEnvironment never override a user-configured runtime_paths.pi. Provisioning is skipped when Pi is already discovered externally.
  • Contracts: the new download.source/connections and load fields are optional in both envelope.schema.json and local-models.yaml. The generated Go and TS files are consistent with them. TeamHub's validLocalModelsSnapshot enforces the same bounds as the Daemon's checkModel. Note that the TeamHub internal decode is strict (DisallowUnknownFields) and the envelope has additionalProperties: false, so TeamHub and the Agent Service must be deployed before Daemons that emit load.
  • The Computers page summary is derived from computer.runtimes only, with no /local-models request. "Use when ready" clears on failed/available/unavailable/missing, and skips busy Agents and Agents already on the model.
  • apps/web/AGENTS.md and the daemon README are updated (apart from the cache-dir claim in finding 1).
  • git merge-tree against current origin/main shows no conflicts.

Process notes

  • The whole feature (Daemon Pi provisioning, contract telemetry fields, and a large Web UX rework) lands as one 7.5k-line commit. Since main takes rebase merges, consider splitting it along those three boundaries so each can be understood and reverted on its own.
  • No merge commits or fixup commits.

CI

Only Analyze (actions) and CodeQL ran on 320f96a, and both pass. The main CI workflow (fast checks, Go/TS tests, contracts verify) has no run on this head, so it needs to run and pass before merge.

I ran go test -race -count=1 -p 4 ./internal/localmodels/ in apps/computer/local-daemon and it passed. I did not run the Web Vitest suites locally.

Automated review by Claude Code


Automated review of 320f96a by Claude Code.

@oldwinter53

Copy link
Copy Markdown
Author

Closing before the 0.1.4 release (decided by the author). Reasons: rebasing onto main conflicts in 11 files / 47 hunks (daemon main.go and the web local-models files rewritten by #222, #223 and #242); it changes contracts and TeamHub without a green CI run; its background Pi provisioning installs Pi under state/local-models/harness instead of the runtime/harness root the installer manages (two Pis on one Computer), reads only harness-error/v1 lines so RUNTIME_EXTENSIONS_FAILED, RUNTIME_ACTION_FAILED and pi-extensions-unavailable (localmodels dev40) are never recognized, and without PI_CODING_AGENT_DIR it would use the personal ~/.pi/agent profile. #245 re-does part of the same feature. A smaller follow-up built on the model source work (#222, #242) is planned after 0.1.4.

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