Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

perf(local-models): paint first from an on-disk snapshot, one overview query, idle prefetch

rubenluetke10-beep9fa27ee423ec
diff --git a/jarvis/ui/web/frontend/src/components/layout/MainView.tsx b/jarvis/ui/web/frontend/src/components/layout/MainView.tsx
index 07e0e6092f..5a6b59f941 100644
--- a/jarvis/ui/web/frontend/src/components/layout/MainView.tsx
+++ b/jarvis/ui/web/frontend/src/components/layout/MainView.tsx
@@ -1,12 +1,16 @@
import {
lazy,
Suspense,
+ useContext,
useEffect,
useState,
type ComponentType,
type LazyExoticComponent,
} from "react";
+import { QueryClientContext } from "@tanstack/react-query";
import { Loader2 } from "lucide-react";
+import { overviewQueryOptions } from "@/hooks/useLocalModels";
+import { readLocalModelsSeed } from "@/lib/localModelsSeed";
import { useEventStore } from "@/store/events";
import { useT } from "@/i18n";
import { cn } from "@/lib/utils";
@@ -204,14 +208,29 @@ function scheduleIdle(task: () => void): () => void {
* simply fetched again on navigation, where Suspense handles it.
*/
function useIdleViewPrefetch(): void {
+ // Optional on purpose: the shell renders without a QueryClient in some
+ // tests, and the data warm-up is a bonus, never a requirement.
+ const queryClient = useContext(QueryClientContext);
useEffect(() => {
let cancelled = false;
let cancelSlot: (() => void) | null = null;
let index = 0;
+ const queue = [...prefetchQueue];
+ if (queryClient) {
+ // After the chunks: the Local models overview, when a previous open
+ // left a seed — so the section paints with server truth, not just the
+ // on-disk snapshot, the moment it is opened.
+ queue.push(() => {
+ const seed = readLocalModelsSeed();
+ return seed
+ ? queryClient.prefetchQuery(overviewQueryOptions(seed))
+ : Promise.resolve();
+ });
+ }
const pump = () => {
- if (cancelled || index >= prefetchQueue.length) return;
- const loader = prefetchQueue[index++];
+ if (cancelled || index >= queue.length) return;
+ const loader = queue[index++];
void loader()
.catch(() => undefined)
.then(() => {
@@ -225,7 +244,7 @@ function useIdleViewPrefetch(): void {
cancelled = true;
cancelSlot?.();
};
- }, []);
+ }, [queryClient]);
}
/** Quiet time before a loading section admits it is loading. */
diff --git a/jarvis/ui/web/frontend/src/hooks/useLocalModels.test.ts b/jarvis/ui/web/frontend/src/hooks/useLocalModels.test.ts
index 34ea66039b..25c797088d 100644
--- a/jarvis/ui/web/frontend/src/hooks/useLocalModels.test.ts
+++ b/jarvis/ui/web/frontend/src/hooks/useLocalModels.test.ts
@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
import {
deleteModel,
getModelOptions,
+ getOverview,
hfPullName,
localModelsKeys,
searchCatalog,
@@ -23,6 +24,48 @@ afterEach(() => {
vi.unstubAllGlobals();
});
+describe("getOverview", () => {
+ it("returns the route's payload when the backend has it", async () => {
+ const body = {
+ server: {},
+ roles: {},
+ inventory: {},
+ recommended: {},
+ source: "cache",
+ fetched_at: 123,
+ };
+ const fetchMock = stubFetch(body);
+ const got = await getOverview("ollama", true);
+ expect(String(fetchMock.mock.calls[0][0])).toBe(
+ "/api/providers/ollama/local-models/overview?fresh=1",
+ );
+ expect(got).toEqual(body);
+ });
+
+ it("composes the four legacy reads on 404 and rethrows anything else", async () => {
+ const legacy: Record<string, unknown> = {
+ "/api/providers/ollama/local-models/server": { running: true },
+ "/api/providers/ollama/local-models/roles": { roles: [] },
+ "/api/providers/ollama/local-models/inventory": { models: [] },
+ "/api/providers/ollama/local-models/catalog/recommended": { models: [] },
+ };
+ const fetchMock = vi.fn(async (url: string) => {
+ if (url.endsWith("/overview"))
+ return { ok: false, status: 404, json: async () => ({}) };
+ return { ok: true, status: 200, json: async () => legacy[url] };
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ const got = await getOverview("ollama");
+ expect(got.source).toBe("live");
+ expect(got.server).toEqual({ running: true });
+ expect(got.fetched_at).toBeGreaterThan(1_700_000_000);
+ expect(fetchMock).toHaveBeenCalledTimes(5);
+
+ stubFetch({ detail: "boom" }, false, 500);
+ await expect(getOverview("ollama")).rejects.toThrow("boom");
+ });
+});
+
describe("useLocalModels fetch helpers", () => {
it("keeps the slashes of a Hugging Face model name in the path", async () => {
const fetchMock = stubFetch({
diff --git a/jarvis/ui/web/frontend/src/hooks/useLocalModels.ts b/jarvis/ui/web/frontend/src/hooks/useLocalModels.ts
index 49220d622e..f06592bf14 100644
--- a/jarvis/ui/web/frontend/src/hooks/useLocalModels.ts
+++ b/jarvis/ui/web/frontend/src/hooks/useLocalModels.ts
@@ -9,8 +9,18 @@
* The pull helpers (`startModelPull`, `modelPullStatus`) stay in
* `useProviders.ts` and are re-exported here so a panel imports one module.
*/
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-
+import {
+ keepPreviousData,
+ useMutation,
+ useQuery,
+ useQueryClient,
+} from "@tanstack/react-query";
+import { useEffect, useMemo } from "react";
+
+import {
+ readOverviewSnapshot,
+ writeOverviewSnapshot,
+} from "../lib/localModelsSnapshot";
import type { OllamaModelOptions } from "../lib/ollamaModelOptions";
import type {
LibraryModel,
@@ -331,10 +341,40 @@ export interface EnvGuideResponse {
rows: EnvGuideRow[];
}
+// ---------------------------------------------------------------------------
+// Wire types — overview (one round-trip for the whole Simple page)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mirror of `OverviewResponse` in `jarvis/ui/web/local_models_routes.py`
+ * (`GET …/local-models/overview`). A Python parity test reads these six
+ * field names — keep them verbatim.
+ */
+export interface OverviewResponse {
+ server: ServerResponse;
+ roles: RolesResponse;
+ inventory: InventoryResponse;
+ recommended: CatalogRecommendedResponse;
+ /** "live" = built for this request; "cache" = a stored snapshot, refresh underway. */
+ source: "live" | "cache";
+ /** Epoch seconds the payload was built. */
+ fetched_at: number;
+}
+
// ---------------------------------------------------------------------------
// Fetch helpers
// ---------------------------------------------------------------------------
+/** A non-2xx answer, with the status kept so callers can branch on it. */
+export class HttpError extends Error {
+ readonly status: number;
+ constructor(status: number, message: string) {
+ super(message);
+ this.name = "HttpError";
+ this.status = status;
+ }
+}
+
/** Long enough for a cold /api/show sweep over a big inventory or a registry read. */
const READ_TIMEOUT_MS = 20_000;
/** Config writes and server actions answer within a few seconds or not at all. */
@@ -360,7 +400,8 @@ async function request<T>(
const res = await fetch(url, { ...init, signal: controller.signal });
const body = await res.json().catch(() => ({}));
if (!res.ok) {
- throw new Error(
+ throw new HttpError(
+ res.status,
(body as { detail?: string }).detail ?? `HTTP ${res.status}`,
);
}
@@ -636,12 +677,48 @@ export async function getEnvGuide(
return request(`${base(providerId)}/server/env-guide${qs}`);
}
+// overview
+
+/**
+ * The whole Simple page in one round-trip. A backend that predates the route
+ * (a CLI-only install that lags the UI bundle) answers 404: then the four
+ * legacy reads are composed here so the page still paints — that fallback is
+ * permanent, not a migration shim.
+ */
+export async function getOverview(
+ providerId: string,
+ fresh = false,
+): Promise<OverviewResponse> {
+ try {
+ return await request<OverviewResponse>(
+ `${base(providerId)}/overview${fresh ? "?fresh=1" : ""}`,
+ );
+ } catch (err) {
+ if (!(err instanceof HttpError) || err.status !== 404) throw err;
+ }
+ const [server, roles, inventory, recommended] = await Promise.all([
+ getServer(providerId),
+ getRoles(providerId),
+ getInventory(providerId),
+ getCatalogRecommended(providerId),
+ ]);
+ return {
+ server,
+ roles,
+ inventory,
+ recommended,
+ source: "live",
+ fetched_at: Math.floor(Date.now() / 1000),
+ };
+}
+
// ---------------------------------------------------------------------------
// Query keys
// ---------------------------------------------------------------------------
export const localModelsKeys = {
all: ["local-models"] as const,
+ overview: (p: string) => ["local-models", p, "overview"] as const,
inventory: (p: string) => ["local-models", p, "inventory"] as const,
model: (p: string, name: string) =>
["local-models", p, "inventory", name] as const,
@@ -681,6 +758,72 @@ export const localModelsKeys = {
// Query hooks
// ---------------------------------------------------------------------------
+/**
+ * How long an unused section query stays in memory. A tab switch inside the
+ * section, or leaving and coming back within half an hour, must reopen warm
+ * instead of re-sweeping the server.
+ */
+export const SECTION_GC_MS = 30 * 60_000;
+
+/** Options for the overview query — shared by `useOverview` and the idle prefetch. */
+export function overviewQueryOptions(providerId: string) {
+ return {
+ queryKey: localModelsKeys.overview(providerId),
+ queryFn: () => getOverview(providerId),
+ staleTime: 5_000,
+ gcTime: SECTION_GC_MS,
+ };
+}
+
+/**
+ * The Simple page's data, painted first from the on-disk snapshot and
+ * refreshed at once. While the snapshot is on screen and the refresh runs,
+ * `data.source === "cache"` and `isFetching` is true — the panel shows
+ * "Checking…". Every fresh payload is written back to the snapshot and
+ * seeds the legacy per-section queries so Catalogue / Models / Tune open warm.
+ */
+export function useOverview(providerId: string | undefined, enabled = true) {
+ const qc = useQueryClient();
+ const id = providerId ?? "";
+ const snapshot = useMemo(
+ () => (providerId ? readOverviewSnapshot(providerId) : null),
+ [providerId],
+ );
+ const query = useQuery({
+ ...overviewQueryOptions(id),
+ enabled: enabled && !!providerId,
+ initialData: snapshot ?? undefined,
+ initialDataUpdatedAt: snapshot ? snapshot.fetched_at * 1000 : undefined,
+ placeholderData: keepPreviousData,
+ refetchInterval: 15_000,
+ });
+
+ const data = query.data;
+ useEffect(() => {
+ if (!providerId || !data) return;
+ const updatedAt = data.fetched_at * 1000;
+ qc.setQueryData(localModelsKeys.server(providerId), data.server, {
+ updatedAt,
+ });
+ qc.setQueryData(localModelsKeys.roles(providerId), data.roles, {
+ updatedAt,
+ });
+ qc.setQueryData(localModelsKeys.inventory(providerId), data.inventory, {
+ updatedAt,
+ });
+ qc.setQueryData(
+ localModelsKeys.recommended(providerId),
+ data.recommended,
+ { updatedAt },
+ );
+ // The snapshot we painted from is already on disk.
+ if (data !== snapshot && data.source === "live")
+ writeOverviewSnapshot(providerId, data);
+ }, [data, providerId, qc, snapshot]);
+
+ return query;
+}
+
/** Every download with facts, loaded state and the roles using it. Polls slowly. */
export function useInventory(providerId: string | undefined, enabled = true) {
return useQuery({
@@ -689,6 +832,7 @@ export function useInventory(providerId: string | undefined, enabled = true) {
enabled: enabled && !!providerId,
refetchInterval: 15_000,
staleTime: 5_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -701,6 +845,7 @@ export function useInventoryModel(
queryFn: () => getInventoryModel(providerId as string, name as string),
enabled: !!providerId && !!name,
staleTime: 30_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -710,6 +855,7 @@ export function useRoles(providerId: string | undefined, enabled = true) {
queryFn: () => getRoles(providerId as string),
enabled: enabled && !!providerId,
staleTime: 10_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -722,6 +868,7 @@ export function useModelOptions(
queryFn: () => getModelOptions(providerId as string, name as string),
enabled: !!providerId && !!name,
staleTime: 30_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -734,6 +881,7 @@ export function useSuggestedOptions(
queryFn: () => getSuggestedOptions(providerId as string, name as string),
enabled: !!providerId && !!name,
staleTime: 5 * 60_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -748,6 +896,7 @@ export function useCatalog(
queryFn: () => searchCatalog(providerId as string, query),
enabled: enabled && !!providerId,
staleTime: 10 * 60_000,
+ gcTime: SECTION_GC_MS,
placeholderData: (prev) => prev,
});
}
@@ -761,6 +910,7 @@ export function useCatalogTags(
queryFn: () => getCatalogTags(providerId as string, name as string),
enabled: !!providerId && !!name,
staleTime: 10 * 60_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -773,6 +923,7 @@ export function useCatalogRecommended(
queryFn: () => getCatalogRecommended(providerId as string),
enabled: enabled && !!providerId,
staleTime: 60_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -782,6 +933,7 @@ export function useHfEnabled(providerId: string | undefined) {
queryFn: () => getHfEnabled(providerId as string),
enabled: !!providerId,
staleTime: 60_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -797,6 +949,7 @@ export function useHfSearch(
queryFn: () => searchHf(providerId as string, q, sort),
enabled: enabled && !!providerId && q.trim().length > 0,
staleTime: 10 * 60_000,
+ gcTime: SECTION_GC_MS,
placeholderData: (prev) => prev,
});
}
@@ -812,6 +965,7 @@ export function useHfFiles(
getHfFiles(providerId as string, user as string, repo as string),
enabled: !!providerId && !!user && !!repo,
staleTime: 10 * 60_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -822,6 +976,7 @@ export function useServer(providerId: string | undefined, enabled = true) {
enabled: enabled && !!providerId,
refetchInterval: 15_000,
staleTime: 5_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -835,6 +990,7 @@ export function useServerLog(
queryFn: () => getServerLog(providerId as string, lines),
enabled: enabled && !!providerId,
refetchInterval: 10_000,
+ gcTime: SECTION_GC_MS,
});
}
@@ -844,6 +1000,7 @@ export function useEnvGuide(providerId: string | undefined, os?: EnvGuideOs) {
queryFn: () => getEnvGuide(providerId as string, os),
enabled: !!providerId,
staleTime: Infinity,
+ gcTime: SECTION_GC_MS,
});
}
@@ -870,6 +1027,9 @@ export function useSetRole(providerId: string | undefined) {
void qc.invalidateQueries({
queryKey: localModelsKeys.inventory(providerId ?? ""),
});
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.overview(providerId ?? ""),
+ });
},
});
}
@@ -915,6 +1075,9 @@ export function useUnloadModel(providerId: string | undefined) {
void qc.invalidateQueries({
queryKey: localModelsKeys.server(providerId ?? ""),
});
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.overview(providerId ?? ""),
+ });
},
});
}
@@ -962,6 +1125,9 @@ export function useStopServer(providerId: string | undefined) {
void qc.invalidateQueries({
queryKey: localModelsKeys.inventory(providerId ?? ""),
});
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.overview(providerId ?? ""),
+ });
},
});
}
@@ -971,6 +1137,7 @@ export function useIdleRelease(providerId: string | undefined) {
queryKey: localModelsKeys.idleRelease(providerId ?? ""),
queryFn: () => getIdleRelease(providerId as string),
enabled: !!providerId,
+ gcTime: SECTION_GC_MS,
});
}
diff --git a/jarvis/ui/web/frontend/src/lib/localModelsPerf.ts b/jarvis/ui/web/frontend/src/lib/localModelsPerf.ts
new file mode 100644
index 0000000000..963781ea90
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/lib/localModelsPerf.ts
@@ -0,0 +1,18 @@
+/**
+ * User Timing marks for the Local models section, so "instant paint" is a
+ * number in DevTools (Performance → Timings) rather than an impression:
+ * `local-models:mount` when the view mounts, `local-models:first-data` the
+ * first time the overview has data on screen (snapshot or live).
+ */
+export const LOCAL_MODELS_MARK_MOUNT = "local-models:mount";
+export const LOCAL_MODELS_MARK_FIRST_DATA = "local-models:first-data";
+
+/** `performance.mark` guarded for environments without User Timing. */
+export function markLocalModels(name: string): void {
+ try {
+ if (typeof performance !== "undefined" && typeof performance.mark === "function")
+ performance.mark(name);
+ } catch {
+ // A mark is a measurement aid; never let it break the paint it measures.
+ }
+}
diff --git a/jarvis/ui/web/frontend/src/lib/localModelsSnapshot.test.ts b/jarvis/ui/web/frontend/src/lib/localModelsSnapshot.test.ts
new file mode 100644
index 0000000000..32a5d596d2
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/lib/localModelsSnapshot.test.ts
@@ -0,0 +1,70 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import type { OverviewResponse } from "@/hooks/useLocalModels";
+
+import {
+ SNAPSHOT_MAX_BYTES,
+ SNAPSHOT_VERSION,
+ clearOverviewSnapshot,
+ readOverviewSnapshot,
+ snapshotKey,
+ writeOverviewSnapshot,
+} from "./localModelsSnapshot";
+
+function payload(extra: Partial<OverviewResponse> = {}): OverviewResponse {
+ return {
+ server: { running: true } as OverviewResponse["server"],
+ roles: { roles: [] } as unknown as OverviewResponse["roles"],
+ inventory: { models: [] } as unknown as OverviewResponse["inventory"],
+ recommended: { models: [] } as unknown as OverviewResponse["recommended"],
+ source: "live",
+ fetched_at: 1_700_000_000,
+ ...extra,
+ };
+}
+
+afterEach(() => {
+ clearOverviewSnapshot("ollama");
+});
+
+describe("localModelsSnapshot", () => {
+ it("round-trips a payload and marks the read copy as cache", () => {
+ expect(writeOverviewSnapshot("ollama", payload())).toBe(true);
+ const back = readOverviewSnapshot("ollama");
+ expect(back?.source).toBe("cache");
+ expect(back?.fetched_at).toBe(1_700_000_000);
+ expect(back?.server.running).toBe(true);
+ });
+
+ it("ignores another version, broken JSON and incomplete payloads", () => {
+ window.localStorage.setItem(
+ snapshotKey("ollama"),
+ JSON.stringify({ v: SNAPSHOT_VERSION + 1, data: payload() }),
+ );
+ expect(readOverviewSnapshot("ollama")).toBeNull();
+ window.localStorage.setItem(snapshotKey("ollama"), "{not json");
+ expect(readOverviewSnapshot("ollama")).toBeNull();
+ window.localStorage.setItem(
+ snapshotKey("ollama"),
+ JSON.stringify({ v: SNAPSHOT_VERSION, data: { fetched_at: 1 } }),
+ );
+ expect(readOverviewSnapshot("ollama")).toBeNull();
+ });
+
+ it("refuses to store an oversized payload", () => {
+ const big = payload({
+ inventory: {
+ models: [{ name: "x".repeat(SNAPSHOT_MAX_BYTES) }],
+ } as unknown as OverviewResponse["inventory"],
+ });
+ expect(writeOverviewSnapshot("ollama", big)).toBe(false);
+ expect(readOverviewSnapshot("ollama")).toBeNull();
+ });
+
+ it("keeps one entry per provider", () => {
+ writeOverviewSnapshot("ollama", payload());
+ expect(readOverviewSnapshot("other")).toBeNull();
+ clearOverviewSnapshot("ollama");
+ expect(readOverviewSnapshot("ollama")).toBeNull();
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/lib/localModelsSnapshot.ts b/jarvis/ui/web/frontend/src/lib/localModelsSnapshot.ts
new file mode 100644
index 0000000000..6320469b48
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/lib/localModelsSnapshot.ts
@@ -0,0 +1,88 @@
+/**
+ * Paint-first snapshot of the Local models overview.
+ *
+ * The last `GET …/local-models/overview` payload is mirrored into
+ * `localStorage` (one entry per provider id) so the next open paints the
+ * tiles and the role checklist synchronously from it, while react-query
+ * refetches in the background. The entry is versioned: a shape change bumps
+ * `SNAPSHOT_VERSION` and older entries are simply ignored. Entries above
+ * ~200 KB are not written (a huge inventory would otherwise crowd the
+ * origin's storage quota out for the other caches).
+ *
+ * The payload type is imported from the hook module as a type only — this
+ * file stays free of React and react-query so the idle prefetch can read it.
+ */
+import type { OverviewResponse } from "@/hooks/useLocalModels";
+
+/** Bump when `OverviewResponse` changes shape in a way old paints would lie. */
+export const SNAPSHOT_VERSION = 1;
+/** Largest JSON we are willing to keep per provider (bytes, roughly). */
+export const SNAPSHOT_MAX_BYTES = 200_000;
+
+const KEY_PREFIX = "jarvis.localModels.overview.";
+
+interface Envelope {
+ v: number;
+ data: OverviewResponse;
+}
+
+export function snapshotKey(providerId: string): string {
+ return `${KEY_PREFIX}${providerId}`;
+}
+
+/**
+ * Synchronously read the last overview for `providerId`; `null` when there
+ * is none, the version does not match, the JSON is broken or storage is
+ * unavailable. The returned payload carries `source: "cache"` so a panel can
+ * tell a painted snapshot from server truth.
+ */
+export function readOverviewSnapshot(
+ providerId: string,
+): OverviewResponse | null {
+ try {
+ const raw = window.localStorage.getItem(snapshotKey(providerId));
+ if (!raw) return null;
+ const env = JSON.parse(raw) as Partial<Envelope> | null;
+ if (!env || env.v !== SNAPSHOT_VERSION || !env.data) return null;
+ const data = env.data;
+ if (
+ typeof data.fetched_at !== "number" ||
+ !data.server ||
+ !data.roles ||
+ !data.inventory ||
+ !data.recommended
+ )
+ return null;
+ return { ...data, source: "cache" };
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Persist an overview for the next paint. Oversized payloads and blocked
+ * storage are silent no-ops — the section still works, it just paints a
+ * beat later next time.
+ */
+export function writeOverviewSnapshot(
+ providerId: string,
+ data: OverviewResponse,
+): boolean {
+ try {
+ const env: Envelope = { v: SNAPSHOT_VERSION, data };
+ const json = JSON.stringify(env);
+ if (json.length > SNAPSHOT_MAX_BYTES) return false;
+ window.localStorage.setItem(snapshotKey(providerId), json);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+export function clearOverviewSnapshot(providerId: string): void {
+ try {
+ window.localStorage.removeItem(snapshotKey(providerId));
+ } catch {
+ // Nothing to recover.
+ }
+}
diff --git a/jarvis/ui/web/frontend/src/views/LocalModelsView.tsx b/jarvis/ui/web/frontend/src/views/LocalModelsView.tsx
index 3cf2d9a537..e67195a138 100644
--- a/jarvis/ui/web/frontend/src/views/LocalModelsView.tsx
+++ b/jarvis/ui/web/frontend/src/views/LocalModelsView.tsx
@@ -26,6 +26,10 @@ import {
} from "@/components/extensions/primitives";
import { useInventory } from "@/hooks/useLocalModels";
import { useProviders } from "@/hooks/useProviders";
+import {
+ LOCAL_MODELS_MARK_MOUNT,
+ markLocalModels,
+} from "@/lib/localModelsPerf";
import {
clearLocalModelsSeed,
readLocalModelsSeed,
@@ -111,6 +115,9 @@ export function LocalModelsView() {
useLocaleChunk("local_models");
const setActiveSection = useEventStore((s) => s.setActiveSection);
const { providers, loading } = useProviders();
+ useEffect(() => {
+ markLocalModels(LOCAL_MODELS_MARK_MOUNT);
+ }, []);
// The one server that can download models. Capability, not provider id.
const descriptor = useMemo(
diff --git a/jarvis/ui/web/frontend/src/views/local-models/OverviewPanel.test.tsx b/jarvis/ui/web/frontend/src/views/local-models/OverviewPanel.test.tsx
index 986a2e0d0b..a9f5fc89f9 100644
--- a/jarvis/ui/web/frontend/src/views/local-models/OverviewPanel.test.tsx
+++ b/jarvis/ui/web/frontend/src/views/local-models/OverviewPanel.test.tsx
@@ -35,6 +35,11 @@ import {
OverviewPanel,
formatGigabytes,
} from "@/views/local-models/OverviewPanel";
+import type { OverviewResponse } from "@/hooks/useLocalModels";
+import {
+ snapshotKey,
+ writeOverviewSnapshot,
+} from "@/lib/localModelsSnapshot";
const BASE = "/api/providers/ollama/local-models";
@@ -122,6 +127,9 @@ interface Fixture {
models?: Array<{ name: string }>;
server?: Record<string, unknown>;
accelerator_gb?: number;
+ /** "404" = a backend without the route (the four legacy reads compose);
+ * "live" = the route answers with the composed payload. */
+ overview?: "404" | "live";
}
function installFetchMock(fx: Fixture = {}) {
@@ -145,40 +153,57 @@ function installFetchMock(fx: Fixture = {}) {
}));
const ok = (body: unknown) =>
({ ok: true, status: 200, json: async () => body }) as Response;
+ const rolesBody = {
+ provider: "ollama",
+ server: "",
+ roles: fx.roles ?? ROLES,
+ error: null,
+ };
+ const inventoryBody = {
+ provider: "ollama",
+ server: "",
+ models,
+ running: [],
+ disk_bytes: 0,
+ loaded_vram_bytes: 0,
+ error: null,
+ };
+ const serverBody = fx.server ?? SERVER;
+ const recommendedBody = {
+ server: "",
+ server_reachable: true,
+ message: "",
+ memory_gb: 32,
+ accelerator_gb: fx.accelerator_gb ?? 16,
+ accelerator_source: "nvidia-smi",
+ models: [],
+ installed: [],
+ curated_reviewed_on: "2026-08-24",
+ };
const fetchMock = vi.fn(
async (input: RequestInfo | URL, init?: RequestInit) => {
const url = String(input);
const method = init?.method ?? "GET";
- if (url === `${BASE}/roles`)
- return ok({
- provider: "ollama",
- server: "",
- roles: fx.roles ?? ROLES,
- error: null,
- });
- if (url === `${BASE}/inventory`)
+ if (url.startsWith(`${BASE}/overview`)) {
+ if ((fx.overview ?? "404") === "404")
+ return {
+ ok: false,
+ status: 404,
+ json: async () => ({ detail: "Not Found" }),
+ } as Response;
return ok({
- provider: "ollama",
- server: "",
- models,
- running: [],
- disk_bytes: 0,
- loaded_vram_bytes: 0,
- error: null,
- });
- if (url === `${BASE}/server`) return ok(fx.server ?? SERVER);
- if (url === `${BASE}/catalog/recommended`)
- return ok({
- server: "",
- server_reachable: true,
- message: "",
- memory_gb: 32,
- accelerator_gb: fx.accelerator_gb ?? 16,
- accelerator_source: "nvidia-smi",
- models: [],
- installed: [],
- curated_reviewed_on: "2026-08-24",
+ server: serverBody,
+ roles: rolesBody,
+ inventory: inventoryBody,
+ recommended: recommendedBody,
+ source: "live",
+ fetched_at: 1_700_000_000,
});
+ }
+ if (url === `${BASE}/roles`) return ok(rolesBody);
+ if (url === `${BASE}/inventory`) return ok(inventoryBody);
+ if (url === `${BASE}/server`) return ok(serverBody);
+ if (url === `${BASE}/catalog/recommended`) return ok(recommendedBody);
if (url.startsWith(`${BASE}/roles/`) && method === "PUT")
return ok({
ok: true,
@@ -229,7 +254,37 @@ function renderPanel(props: Partial<Parameters<typeof OverviewPanel>[0]> = {}) {
);
}
+function snapshotPayload(): OverviewResponse {
+ return {
+ server: { ...SERVER, host_kind: "local", disk_bytes: 80 * 1024 ** 3 },
+ roles: { provider: "ollama", server: "", roles: ROLES, error: null },
+ inventory: {
+ provider: "ollama",
+ server: "",
+ models: [],
+ running: [],
+ disk_bytes: 0,
+ loaded_vram_bytes: 0,
+ error: null,
+ },
+ recommended: {
+ server: "",
+ server_reachable: true,
+ message: "",
+ memory_gb: 32,
+ accelerator_gb: 15.9,
+ accelerator_source: "nvidia-smi",
+ models: [],
+ installed: [],
+ curated_reviewed_on: "2026-08-24",
+ } as OverviewResponse["recommended"],
+ source: "live",
+ fetched_at: 1_700_000_000,
+ } as OverviewResponse;
+}
+
beforeEach(() => {
+ window.localStorage.removeItem(snapshotKey("ollama"));
mockProviders.providers = [
{ id: "ollama", label: "Ollama", tier: "brain", active: true },
];
@@ -250,6 +305,71 @@ describe("formatGigabytes", () => {
});
});
+describe("OverviewPanel paint-first", () => {
+ it("paints the tiles synchronously from the snapshot while the fetch never answers", () => {
+ writeOverviewSnapshot("ollama", snapshotPayload());
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(() => new Promise<Response>(() => undefined)),
+ );
+ renderPanel();
+
+ // No await: the snapshot is on screen in the first render.
+ const disk = screen.getByRole("group", {
+ name: "local_models.overview.disk",
+ });
+ expect(disk.textContent).toContain("80 GB");
+ expect(screen.getByTestId("overview-status").textContent).toContain(
+ "local_models.overview.status_runningOllama|0.32.15",
+ );
+ expect(screen.getByTestId("role-row-chat")).toBeDefined();
+ // The refresh is underway, the snapshot is what is shown -> "Checking…".
+ expect(screen.getByTestId("overview-checking")).toBeDefined();
+ });
+
+ it("drops 'Checking…' and writes the snapshot once live data arrives", async () => {
+ writeOverviewSnapshot("ollama", snapshotPayload());
+ installFetchMock({ overview: "live" });
+ renderPanel();
+
+ await waitFor(() =>
+ expect(screen.queryByTestId("overview-checking")).toBeNull(),
+ );
+ const disk = screen.getByRole("group", {
+ name: "local_models.overview.disk",
+ });
+ expect(disk.textContent).toContain("12 GB");
+ const stored = JSON.parse(
+ String(window.localStorage.getItem(snapshotKey("ollama"))),
+ );
+ expect(stored.data.server.disk_bytes).toBe(12 * 1024 ** 3);
+ });
+
+ it("reads the overview route when the backend has it", async () => {
+ const fetchMock = installFetchMock({ overview: "live" });
+ renderPanel();
+
+ await screen.findByTestId("role-row-chat");
+ const urls = fetchMock.mock.calls.map(([u]) => String(u));
+ expect(urls).toContain(`${BASE}/overview`);
+ expect(urls).not.toContain(`${BASE}/roles`);
+ expect(urls).not.toContain(`${BASE}/server`);
+ });
+
+ it("composes the four legacy reads when the route answers 404", async () => {
+ const fetchMock = installFetchMock({ overview: "404" });
+ renderPanel();
+
+ await screen.findByTestId("role-row-chat");
+ const urls = fetchMock.mock.calls.map(([u]) => String(u));
+ expect(urls).toContain(`${BASE}/overview`);
+ expect(urls).toContain(`${BASE}/roles`);
+ expect(urls).toContain(`${BASE}/inventory`);
+ expect(urls).toContain(`${BASE}/server`);
+ expect(urls).toContain(`${BASE}/catalog/recommended`);
+ });
+});
+
describe("OverviewPanel", () => {
it("opens with one status sentence: server, graphics memory, active brain", async () => {
installFetchMock();
diff --git a/jarvis/ui/web/frontend/src/views/local-models/OverviewPanel.tsx b/jarvis/ui/web/frontend/src/views/local-models/OverviewPanel.tsx
index 8bf8da1762..dd610fe847 100644
--- a/jarvis/ui/web/frontend/src/views/local-models/OverviewPanel.tsx
+++ b/jarvis/ui/web/frontend/src/views/local-models/OverviewPanel.tsx
@@ -16,7 +16,7 @@
* Props take `providerId` — the id of the card that declares
* `supports_model_pull` — never a provider name.
*/
-import type { ReactNode } from "react";
+import { useEffect, useRef, type ReactNode } from "react";
import {
AlertCircle,
Cpu,
@@ -26,14 +26,18 @@ import {
Sparkles,
} from "lucide-react";
-import { SoftButton, StatTile } from "@/components/extensions/primitives";
import {
- useCatalogRecommended,
- useInventory,
- useServer,
-} from "@/hooks/useLocalModels";
+ SoftButton,
+ StatTile,
+ StatusDot,
+} from "@/components/extensions/primitives";
+import { useOverview } from "@/hooks/useLocalModels";
import { useProviders } from "@/hooks/useProviders";
import { fill, useT } from "@/i18n";
+import {
+ LOCAL_MODELS_MARK_FIRST_DATA,
+ markLocalModels,
+} from "@/lib/localModelsPerf";
import { cn } from "@/lib/utils";
import { formatExpiry } from "./localModelsFormat";
@@ -68,12 +72,22 @@ export function OverviewPanel({
onReportProblem,
}: OverviewPanelProps) {
const t = useT();
- const server = useServer(providerId);
- const shortlist = useCatalogRecommended(providerId);
- const inventory = useInventory(providerId);
+ const overview = useOverview(providerId);
const { providers } = useProviders();
- const s = server.data;
+ // One round-trip (or the painted snapshot) feeds every tile.
+ const s = overview.data?.server;
+ const shortlist = { data: overview.data?.recommended };
+ const inventory = { data: overview.data?.inventory };
+ const server = { isLoading: overview.isLoading, isError: overview.isError };
+ const checking = overview.isFetching && overview.data?.source === "cache";
+
+ const marked = useRef(false);
+ useEffect(() => {
+ if (marked.current || !overview.data) return;
+ marked.current = true;
+ markLocalModels(LOCAL_MODELS_MARK_FIRST_DATA);
+ }, [overview.data]);
const remote = s?.host_kind === "remote";
const serverLabel =
providers.find((p) => p.id === providerId)?.label ||
@@ -229,6 +243,15 @@ export function OverviewPanel({
</span>
</>
)}
+ {checking && (
+ <span className="ml-1" data-testid="overview-checking">
+ <StatusDot
+ tone="busy"
+ pulse
+ label={t("local_models.overview.checking")}
+ />
+ </span>
+ )}
</p>
{(onBrowse || onOpenAssistant || onReportProblem) && (
@@ -284,7 +307,7 @@ export function OverviewPanel({
value={gpuValue}
hint={gpuHint}
tone="primary"
- loading={shortlist.isLoading}
+ loading={server.isLoading}
/>
<StatTile
icon={<Layers className="h-3.5 w-3.5" />}
diff --git a/jarvis/ui/web/frontend/src/views/local-models/RolesPanel.tsx b/jarvis/ui/web/frontend/src/views/local-models/RolesPanel.tsx
index 018c2b378a..d5ca95038d 100644
--- a/jarvis/ui/web/frontend/src/views/local-models/RolesPanel.tsx
+++ b/jarvis/ui/web/frontend/src/views/local-models/RolesPanel.tsx
@@ -43,8 +43,7 @@ import {
setRole,
startModelPull,
useInvalidateLocalModels,
- useInventory,
- useRoles,
+ useOverview,
useSetRole,
type LocalModelRole,
type RoleRow,
@@ -120,8 +119,17 @@ export function RolesPanel({
variant = "ledger",
}: RolesPanelProps) {
const t = useT();
- const roles = useRoles(providerId);
- const inventory = useInventory(providerId);
+ // Roles and inventory come from the one overview round-trip (painted
+ // first from the snapshot); the shapes below keep the rest of the panel
+ // reading as before.
+ const overview = useOverview(providerId);
+ const roles = {
+ data: overview.data?.roles,
+ isLoading: overview.isLoading,
+ isError: overview.isError,
+ error: overview.error,
+ };
+ const inventory = { data: overview.data?.inventory };
const { providers } = useProviders();
const setRoleMutation = useSetRole(providerId);
const invalidate = useInvalidateLocalModels(providerId);