@circuitwall/jarela 2.4.0 → 2.5.0

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circuitwall/jarela",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Jarela — local chat interface for LangGraph agents (multi-provider, single-process, SQLite-backed).",
   "license": "Apache-2.0",
   "author": "Andrew Ge Wu",

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-10-18
+
+### Added
+
+- Add appearance presets and accent-color choices, and reorganize configuration
+  panels for a more consistent workspace.
+
+### Fixed
+
+- Let assistant replies use the available chat width and keep long tool names,
+  status indicators, expanded tool details, and the composer within narrow screens.
+- Align configuration panel widths on desktop and mobile.
+- Refresh provider model catalogs and capability metadata.
+- Resolve optional tool packages from the workspace when their package entry
+  point is unavailable.
+
+### Changed
+
+- Reuse short-lived startup reads between the agent picker and chat so the
+  first agent load warms profile, configuration, and conversation data without
+  duplicate requests. Writes and run submissions invalidate the handoff.
+- Speed up chat pagination, dashboard date windows, and thread lists with
+  automatically created SQLite indexes. The first startup after upgrading a
+  large database may take longer while indexes build.
+- Index latest usage, memory ordering, signal cleanup, background retention,
+  and expired leases; find the next embedding wakeup with indexed lookups
+  instead of scanning the active queue.
+- Reduce chat refresh work with metadata-only, visibility-aware polling and
+  reuse historical message rows during streaming updates.
+- Reuse unchanged dashboard computations briefly, avoid loading snapshotted
+  message bodies for token estimates, and skip rereading unchanged pricing
+  snapshots. Database writes and pricing changes invalidate server-side metrics.
+
 ## [2.4.0] - 2026-10-16
 
 ### Added

package/api/client.models.test.ts

@@ -77,4 +77,14 @@ describe("api request HTTP cache mode", () => {
 
     expect((fetchMock.mock.calls[0][1] as RequestInit).cache).toBe("default");
   });
+
+  it("fetches live thread metadata without loading a message page", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse({ thread_id: "t1" }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await api.threads.metadata("t1");
+
+    expect(fetchMock.mock.calls[0][0]).toBe("/api/v1/threads/t1?view=metadata");
+    expect((fetchMock.mock.calls[0][1] as RequestInit).cache).toBe("no-store");
+  });
 });

package/api/client.startup.test.ts

@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./runtime-config", () => ({
+  runtimeConfig: () => ({ httpMaxAttempts: 1, httpRequestTimeoutMs: 30_000 }),
+}));
+
+function json(body: unknown): Response {
+  return new Response(JSON.stringify(body), { headers: { "Content-Type": "application/json" } });
+}
+
+describe("agent startup handoff", () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("shares all four startup reads between boot and chat without sharing mutable objects", async () => {
+    const { api } = await import("./client");
+    const fetch = vi.fn().mockImplementation(() => Promise.resolve(json({ nested: { value: "original" } })));
+    vi.stubGlobal("fetch", fetch);
+    const load = () => Promise.all([
+      api.profile.get({ startup: true }),
+      api.agents.get("agent", { startup: true }),
+      api.agents.getThread("agent", { startup: true }),
+      api.threads.get("thread", { startup: true }),
+    ]);
+    const [boot, chat] = await Promise.all([load(), load()]);
+    expect(fetch).toHaveBeenCalledTimes(4);
+    expect(chat).toEqual(boot);
+    expect(chat[0]).not.toBe(boot[0]);
+    await load();
+    expect(fetch).toHaveBeenCalledTimes(4);
+    for (const [, init] of fetch.mock.calls) {
+      expect(init.cache).toBe("no-store");
+      expect(init).not.toHaveProperty("startup");
+    }
+  });
+
+  it("expires startup reads after five seconds and keeps ordinary reads fresh", async () => {
+    const { api } = await import("./client");
+    let now = 1_000;
+    vi.spyOn(Date, "now").mockImplementation(() => now);
+    const fetch = vi.fn().mockImplementation(() => Promise.resolve(json({ name: "profile" })));
+    vi.stubGlobal("fetch", fetch);
+    await api.profile.get({ startup: true });
+    now += 4_999;
+    await api.profile.get({ startup: true });
+    expect(fetch).toHaveBeenCalledTimes(1);
+    now += 1;
+    await api.profile.get({ startup: true });
+    expect(fetch).toHaveBeenCalledTimes(2);
+    await api.profile.get();
+    await api.profile.get({ startup: true });
+    expect(fetch).toHaveBeenCalledTimes(4);
+  });
+
+  it("isolates nested transcript data between consumers", async () => {
+    const { api } = await import("./client");
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(json({ messages: [{ id: "message" }] })));
+    const first = await api.threads.get("thread", { startup: true });
+    first.messages.length = 0;
+    const second = await api.threads.get("thread", { startup: true });
+    expect(second.messages).toEqual([{ id: "message" }]);
+  });
+
+  it("invalidates pending warmups before writes and never caches failed reads", async () => {
+    const { api } = await import("./client");
+    let resolveOld!: (response: Response) => void;
+    const fetch = vi.fn()
+      .mockImplementationOnce(() => new Promise<Response>((resolve) => { resolveOld = resolve; }))
+      .mockResolvedValueOnce(json({ name: "updated" }))
+      .mockResolvedValueOnce(json({ name: "updated" }))
+      .mockResolvedValueOnce(new Response("failed", { status: 400 }))
+      .mockResolvedValueOnce(json({ name: "recovered" }));
+    vi.stubGlobal("fetch", fetch);
+    const old = api.profile.get({ startup: true });
+    await api.profile.update({ name: "updated" });
+    resolveOld(json({ name: "old" }));
+    await old;
+    expect(await api.profile.get({ startup: true })).toEqual({ name: "updated" });
+    await expect(api.agents.get("retry", { startup: true })).rejects.toThrow("400");
+    await expect(api.agents.get("retry", { startup: true })).resolves.toEqual({ name: "recovered" });
+    expect(fetch).toHaveBeenCalledTimes(5);
+  });
+
+  it("clears the startup page before submitting a run", async () => {
+    const { api, submitRun } = await import("./client");
+    const fetch = vi.fn()
+      .mockResolvedValueOnce(json({ messages: [] }))
+      .mockResolvedValueOnce(new Response(null, { status: 202 }))
+      .mockResolvedValueOnce(json({ messages: [{ id: "new" }] }));
+    vi.stubGlobal("fetch", fetch);
+    await api.threads.get("thread", { startup: true });
+    await submitRun("thread", "hello", new AbortController().signal);
+    await expect(api.threads.get("thread", { startup: true })).resolves.toEqual({ messages: [{ id: "new" }] });
+    expect(fetch).toHaveBeenCalledTimes(3);
+  });
+
+  it("discards startup data read while a write was still in flight", async () => {
+    const { api } = await import("./client");
+    let finishWrite!: (response: Response) => void;
+    const fetch = vi.fn()
+      .mockImplementationOnce(() => new Promise<Response>((resolve) => { finishWrite = resolve; }))
+      .mockResolvedValueOnce(json({ name: "old" }))
+      .mockResolvedValueOnce(json({ name: "new" }));
+    vi.stubGlobal("fetch", fetch);
+    const write = api.profile.update({ name: "new" });
+    await expect(api.profile.get({ startup: true })).resolves.toEqual({ name: "old" });
+    finishWrite(json({ name: "new" }));
+    await write;
+    await expect(api.profile.get({ startup: true })).resolves.toEqual({ name: "new" });
+    expect(fetch).toHaveBeenCalledTimes(3);
+  });
+
+  it("bounds retained data and separates thread cursor requests", async () => {
+    const { api } = await import("./client");
+    const fetch = vi.fn().mockImplementation(() => Promise.resolve(json({ messages: [] })));
+    vi.stubGlobal("fetch", fetch);
+    for (let i = 0; i < 17; i++) await api.threads.get(`thread-${i}`, { startup: true });
+    await api.threads.get("thread-0", { startup: true });
+    expect(fetch).toHaveBeenCalledTimes(18);
+    await api.threads.get("thread-0", { after: 10 });
+    expect(fetch.mock.calls[18][0]).toBe("/api/v1/threads/thread-0?after=10");
+  });
+});

package/api/client.ts

@@ -61,6 +61,7 @@ import type {
   ToolConfigSlotInfo,
   TaskAssignment,
   ThreadDetail,
+  ThreadMetadata,
   ThreadSummary,
   UserProfile,
   BuiltinToolCategoryInfo,
@@ -369,11 +370,41 @@ async function parseJsonResponse<T>(res: Response): Promise<T> {
   return JSON.parse(await new Response(stream).text()) as T;
 }
 
-async function request<T>(path: string, init?: RequestInit & { timeoutMs?: number }): Promise<T> {
+const STARTUP_TTL_MS = 5_000;
+const startupReads = new Map<string, { promise: Promise<unknown>; settledAt: number | null }>();
+
+function startupRead<T>(path: string): Promise<T> {
+  const now = Date.now();
+  for (const [key, entry] of startupReads) {
+    if (entry.settledAt !== null && (now < entry.settledAt || now - entry.settledAt >= STARTUP_TTL_MS)) {
+      startupReads.delete(key);
+    }
+  }
+  const cached = startupReads.get(path);
+  if (cached) return cached.promise.then((value) => structuredClone(value as T));
+  // Bound retained startup data when agents are switched rapidly.
+  const oldestKey = startupReads.keys().next().value;
+  if (startupReads.size >= 16 && oldestKey !== undefined) startupReads.delete(oldestKey);
+  const entry = { promise: Promise.resolve<unknown>(undefined), settledAt: null as number | null };
+  entry.promise = request<T>(path, { startup: true }).then((value) => {
+    entry.settledAt = Date.now();
+    return value;
+  }).catch((error: unknown) => {
+    if (startupReads.get(path) === entry) startupReads.delete(path);
+    throw error;
+  });
+  startupReads.set(path, entry);
+  return entry.promise.then((value) => structuredClone(value as T));
+}
+
+async function request<T>(path: string, init?: RequestInit & { timeoutMs?: number; startup?: boolean }): Promise<T> {
+  const mutation = !!init?.method && init.method !== "GET";
+  if (mutation) startupReads.clear();
+  else if (!init?.startup) startupReads.delete(path);
   const cfg = runtimeConfig();
   const maxAttempts = Math.max(1, cfg.httpMaxAttempts);
   const timeoutMs = init?.timeoutMs ?? cfg.httpRequestTimeoutMs;
-  const { timeoutMs: _ignoreTimeoutMs, ...fetchInit } = init ?? {};
+  const { timeoutMs: _ignoreTimeoutMs, startup: _ignoreStartup, ...fetchInit } = init ?? {};
   const callerSignal = fetchInit.signal ?? null;
 
   let lastErr: unknown = null;
@@ -434,6 +465,7 @@ async function request<T>(path: string, init?: RequestInit & { timeoutMs?: numbe
       if (attempt < maxAttempts && isRetryable(err)) continue;
       throw err;
     } finally {
+      if (mutation) startupReads.clear();
       clearTimeout(timer);
       callerSignal?.removeEventListener("abort", onCallerAbort);
     }
@@ -446,7 +478,10 @@ export const api = {
   agents: {
     list: (opts?: { force?: boolean }) =>
       cachedList(agentListCache, () => request<AgentConfig[]>("/agents"), setAgentListCache, opts?.force === true),
-    get: (id: string) => request<AgentConfig>(`/agents/${encodeURIComponent(id)}`),
+    get: (id: string, opts?: { startup?: boolean }) => {
+      const path = `/agents/${encodeURIComponent(id)}`;
+      return opts?.startup ? startupRead<AgentConfig>(path) : request<AgentConfig>(path);
+    },
     create: async (data: AgentConfigIn) => {
       const created = await request<AgentConfig>("/agents", { method: "POST", body: JSON.stringify(data) });
       if (agentListCache.data) setAgentListCache([...agentListCache.data, created]);
@@ -467,8 +502,10 @@ export const api = {
       }
       return res;
     },
-    getThread: (id: string) =>
-      request<ThreadSummary>(`/agents/${encodeURIComponent(id)}/thread`),
+    getThread: (id: string, opts?: { startup?: boolean }) => {
+      const path = `/agents/${encodeURIComponent(id)}/thread`;
+      return opts?.startup ? startupRead<ThreadSummary>(path) : request<ThreadSummary>(path);
+    },
     compact: (id: string, options?: { resetContext?: boolean }) =>
       request<{
         compacted: boolean;
@@ -705,7 +742,7 @@ export const api = {
     list: (limit = 50, offset = 0) => request<ThreadSummary[]>(`/threads?limit=${limit}&offset=${offset}`),
     create: (agent_id: string, title?: string) =>
       request<ThreadSummary>("/threads", { method: "POST", body: JSON.stringify({ agent_id, title }) }),
-    get: (thread_id: string, opts?: { limit?: number; before?: number; after?: number }) => {
+    get: (thread_id: string, opts?: { limit?: number; before?: number; after?: number; startup?: boolean }) => {
       const p = new URLSearchParams();
       if (opts?.limit) p.set("limit", String(opts.limit));
       if (opts?.before !== undefined) p.set("before", String(opts.before));
@@ -714,8 +751,11 @@ export const api = {
       // user+assistant pair instead of re-pulling the whole most-recent page.
       if (opts?.after !== undefined) p.set("after", String(opts.after));
       const qs = p.toString() ? `?${p}` : "";
-      return request<ThreadDetail>(`/threads/${thread_id}${qs}`);
+      const path = `/threads/${thread_id}${qs}`;
+      return opts?.startup ? startupRead<ThreadDetail>(path) : request<ThreadDetail>(path);
     },
+    metadata: (thread_id: string, signal?: AbortSignal) =>
+      request<ThreadMetadata>(`/threads/${thread_id}?view=metadata`, { signal }),
     delete: (thread_id: string) =>
       request<{ deleted: boolean }>(`/threads/${thread_id}`, { method: "DELETE" }),
     // What the thread is doing now (run phase, queued turns, compaction).
@@ -893,7 +933,8 @@ export const api = {
   },
 
   profile: {
-    get: () => request<UserProfile>("/profile"),
+    get: (opts?: { startup?: boolean }) =>
+      opts?.startup ? startupRead<UserProfile>("/profile") : request<UserProfile>("/profile"),
     update: (data: Partial<Pick<UserProfile, "name" | "icon" | "about" | "preset">>) =>
       request<UserProfile>("/profile", { method: "PUT", body: JSON.stringify(data) }),
     setLocationConsent: (consent: boolean) =>
@@ -1397,6 +1438,7 @@ export async function submitRun(
   channels?: string[],
   hot_since_seq?: number | null,
 ): Promise<SubmitResult> {
+  startupReads.clear();
   const payload: {
     message: string;
     stream_options?: StreamOptions;
@@ -1413,7 +1455,7 @@ export async function submitRun(
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(runPayload),
     signal,
-  });
+  }).finally(() => startupReads.clear());
   // 2xx = accepted (currently always 202); 409 = already running. We treat
   // every other status as a hard error so the consumer's catch fires.
   if (res.status === 202) {

package/api/thread-metadata.test.ts

@@ -0,0 +1,72 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { NextRequest } from "next/server";
+
+const mocks = vi.hoisted(() => ({
+  getThread: vi.fn(), getMessagesPage: vi.fn(), getMessagesAfter: vi.fn(),
+  getMessageUsageByIds: vi.fn(), getAgentConfig: vi.fn(),
+}));
+vi.mock("@/lib/stores/threads", () => ({ ...mocks, deleteThread: vi.fn() }));
+vi.mock("@/lib/stores/message-usage", () => ({ getMessageUsageByIds: mocks.getMessageUsageByIds }));
+vi.mock("@/lib/stores/agent-configs", () => ({ getAgentConfig: mocks.getAgentConfig }));
+vi.mock("@/lib/stores/model-config", () => ({ getModelConfig: vi.fn(), getModelParams: vi.fn() }));
+vi.mock("@/lib/agents/warm-summary-background", () => ({
+  currentChannelSummaries: () => [], isManualCompactionRunning: () => true,
+  pendingCompactionBoundary: () => null, pendingCompactionBoundarySeq: () => 10,
+}));
+vi.mock("@/lib/agents/conversation-summary", () => ({ parseStoredTopics: () => null }));
+vi.mock("@/lib/agents/thread-activity", () => ({ getThreadActivity: () => ({ busy: true }) }));
+vi.mock("@/lib/agents/checkpointer", () => ({ getCheckpointer: vi.fn() }));
+
+const { GET } = await import("@/app/api/v1/threads/[thread_id]/route");
+function get(query = "") {
+  return GET(new NextRequest(`http://localhost/api/v1/threads/t1${query}`),
+    { params: Promise.resolve({ thread_id: "t1" }) });
+}
+
+describe("thread metadata view", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getThread.mockReturnValue({ thread_id: "t1", agent_id: "a1", hot_since_seq: 4 });
+    mocks.getMessagesPage.mockReturnValue({ messages: [], has_more: true });
+    mocks.getMessagesAfter.mockReturnValue([]);
+    mocks.getMessageUsageByIds.mockReturnValue(new Map());
+    mocks.getAgentConfig.mockReturnValue(null);
+  });
+
+  it("returns live metadata without reading messages or usage", async () => {
+    const response = await get("?view=metadata");
+    const data = await response.json();
+    expect(data).toMatchObject({
+      thread_id: "t1", hot_since_seq: 4, pending_hot_since_seq: 10,
+      manual_compaction_pending: true, activity: { busy: true }, context_window_tokens: 8192,
+    });
+    expect(data).not.toHaveProperty("messages");
+    expect(data).not.toHaveProperty("has_more");
+    expect(response.headers.get("Cache-Control")).toBe("no-store");
+    expect(mocks.getMessagesPage).not.toHaveBeenCalled();
+    expect(mocks.getMessagesAfter).not.toHaveBeenCalled();
+    expect(mocks.getMessageUsageByIds).not.toHaveBeenCalled();
+  });
+
+  it("preserves the default paged response and before cursor", async () => {
+    const response = await get("?before=42&limit=10");
+    expect(await response.json()).toMatchObject({ messages: [], has_more: true });
+    expect(mocks.getMessagesPage).toHaveBeenCalledWith("t1", 10, 42);
+    expect(mocks.getMessageUsageByIds).toHaveBeenCalledWith([]);
+  });
+
+  it("preserves forward message reads", async () => {
+    expect(await (await get("?after=42&limit=10")).json()).toMatchObject({ messages: [], has_more: false });
+    expect(mocks.getMessagesAfter).toHaveBeenCalledWith("t1", 42, 10);
+  });
+
+  it("rejects unknown views", async () => {
+    expect((await get("?view=unknown")).status).toBe(400);
+    expect(mocks.getMessagesPage).not.toHaveBeenCalled();
+  });
+
+  it("preserves missing-thread responses", async () => {
+    mocks.getThread.mockReturnValue(null);
+    expect((await get("?view=metadata")).status).toBe(404);
+  });
+});

package/api/types.ts

@@ -378,9 +378,7 @@ export interface MessageUsage {
   cost_usd: number | null;
 }
 
-export interface ThreadDetail extends ThreadSummary {
-  messages: Message[];
-  has_more: boolean;
+export interface ThreadMetadata extends ThreadSummary {
   // Effective context-window size (in tokens) for this thread's current
   // agent + model config. Used by the chat UI to scale the per-turn
   // context-usage bar against the same cap the agent applies at run time.
@@ -416,6 +414,11 @@ export interface ThreadDetail extends ThreadSummary {
   warm_channel_summaries?: WarmChannelSummary[];
 }
 
+export interface ThreadDetail extends ThreadMetadata {
+  messages: Message[];
+  has_more: boolean;
+}
+
 /** What a thread is doing right now — GET /threads/:id/activity. */
 export interface ThreadActivity {
   run: { phase: string; label: string; started_at: number; agent_id: string | null } | null;

package/app/api/v1/providers/[provider]/models/route.test.ts

@@ -8,13 +8,16 @@ const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-test-provider-models-"));
 process.env.JARELA_DB_DIR = tmpRoot;
 
 const { upsertModelConfig, deleteModelConfig } = await import("@/lib/stores/model-config");
-const { GET } = await import("./route");
+const { GET, POST } = await import("./route");
 
-const params = { params: Promise.resolve({ provider: "github-copilot" }) };
-const request = () => new NextRequest("http://localhost/api/v1/providers/github-copilot/models?fresh=1");
+const routeParams = (provider: string) => ({ params: Promise.resolve({ provider }) });
+const request = (provider: string, fresh = true) =>
+  new NextRequest(`http://localhost/api/v1/providers/${provider}/models${fresh ? "?fresh=1" : ""}`);
 
 afterEach(() => {
-  deleteModelConfig("copilot-config");
+  for (const name of ["copilot-config", "anthropic-config", "gemini-config", "deepseek-config"]) {
+    deleteModelConfig(name);
+  }
   vi.unstubAllEnvs();
   vi.unstubAllGlobals();
 });
@@ -29,7 +32,7 @@ describe("provider model catalogs", () => {
       api_key: "github_pat_synthetic",
     }, true);
 
-    const response = await GET(request(), params);
+    const response = await GET(request("github-copilot"), routeParams("github-copilot"));
 
     expect(response.status).toBe(400);
     await expect(response.json()).resolves.toMatchObject({
@@ -43,11 +46,218 @@ describe("provider model catalogs", () => {
     const fetch = vi.fn();
     vi.stubGlobal("fetch", fetch);
 
-    const response = await GET(request(), params);
+    const response = await GET(request("github-copilot"), routeParams("github-copilot"));
 
     expect(response.status).toBe(200);
     const models = await response.json() as Array<{ id: string }>;
     expect(models.length).toBeGreaterThan(0);
     expect(fetch).not.toHaveBeenCalled();
   });
+
+  it("loads the Anthropic catalog and follows its pagination cursor", async () => {
+    upsertModelConfig("anthropic-config", "anthropic", "claude-sonnet-4-6", {
+      api_key: "synthetic-anthropic-key",
+    }, true);
+    const fetch = vi.fn()
+      .mockResolvedValueOnce(new Response(JSON.stringify({
+        data: [{
+          id: "claude-first",
+          max_input_tokens: 500000,
+          max_tokens: 64000,
+          capabilities: {
+            image_input: { supported: true },
+            structured_outputs: { supported: true },
+          },
+        }],
+        has_more: true,
+        last_id: "claude-first",
+      })))
+      .mockResolvedValueOnce(new Response(JSON.stringify({
+        data: [{ id: "claude-second" }],
+        has_more: false,
+        last_id: "claude-second",
+      })));
+    vi.stubGlobal("fetch", fetch);
+
+    const response = await GET(request("anthropic"), routeParams("anthropic"));
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject([
+      {
+        id: "claude-first",
+        hosted_on: "anthropic",
+        context_length: 500000,
+        max_output_tokens: 64000,
+        capabilities: { vision: true, files: false, json_mode: true, web_search: false },
+      },
+      { id: "claude-second", hosted_on: "anthropic", capabilities: { vision: false, files: false, web_search: false } },
+    ]);
+    expect(fetch).toHaveBeenCalledTimes(2);
+    expect(String(fetch.mock.calls[0][0])).toBe("https://api.anthropic.com/v1/models?limit=1000");
+    expect(String(fetch.mock.calls[1][0])).toContain("after_id=claude-first");
+    expect(fetch.mock.calls[0][1]?.headers).toMatchObject({
+      "x-api-key": "synthetic-anthropic-key",
+      "anthropic-version": "2023-06-01",
+    });
+  });
+
+  it("loads Gemini generation models with live limits and skips embedding-only models", async () => {
+    upsertModelConfig("gemini-config", "gemini", "gemini-2.5-flash", {
+      api_key: "synthetic-gemini-key",
+    }, true);
+    const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      models: [
+        {
+          name: "models/gemini-current",
+          inputTokenLimit: 131072,
+          outputTokenLimit: 16384,
+          supportedGenerationMethods: ["generateContent"],
+        },
+        {
+          name: "models/text-embedding-current",
+          supportedGenerationMethods: ["embedContent"],
+        },
+      ],
+    })));
+    vi.stubGlobal("fetch", fetch);
+
+    const response = await GET(request("gemini"), routeParams("gemini"));
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject([
+      {
+        id: "gemini-current",
+        context_length: 131072,
+        max_output_tokens: 16384,
+        capabilities: { vision: false, files: false, audio: false, web_search: false },
+      },
+    ]);
+    expect(fetch.mock.calls[0][1]?.headers).toMatchObject({
+      "x-goog-api-key": "synthetic-gemini-key",
+    });
+  });
+
+  it("uses a configured Gemini native base URL for catalog discovery", async () => {
+    upsertModelConfig("gemini-config", "gemini", "gemini-2.5-flash", {
+      api_key: "synthetic-gemini-key",
+      gemini_native_base_url: "https://gemini-proxy.example/v1beta",
+    }, true);
+    const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ models: [] })));
+    vi.stubGlobal("fetch", fetch);
+
+    const response = await GET(request("gemini"), routeParams("gemini"));
+
+    expect(response.status).toBe(200);
+    expect(String(fetch.mock.calls[0][0])).toBe("https://gemini-proxy.example/v1beta/models?pageSize=1000");
+    expect(fetch.mock.calls[0][1]?.headers).toMatchObject({
+      "x-goog-api-key": "synthetic-gemini-key",
+    });
+  });
+
+  it("loads DeepSeek models with live limits and modality capabilities", async () => {
+    upsertModelConfig("deepseek-config", "deepseek", "deepseek-flash", {
+      api_key: "synthetic-deepseek-key",
+    }, true);
+    const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      data: [{
+        id: "deepseek-new",
+        context_window: 900000,
+        max_output_tokens: 120000,
+        input_modalities: ["text", "image"],
+      }],
+    })));
+    vi.stubGlobal("fetch", fetch);
+
+    const response = await GET(request("deepseek"), routeParams("deepseek"));
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject([
+      {
+        id: "deepseek-new",
+        context_length: 900000,
+        max_output_tokens: 120000,
+        capabilities: { vision: true, files: false },
+      },
+    ]);
+    expect(String(fetch.mock.calls[0][0])).toBe("https://api.deepseek.com/models");
+    expect(fetch.mock.calls[0][1]?.headers).toMatchObject({
+      Authorization: "Bearer synthetic-deepseek-key",
+    });
+  });
+
+  it("uses unsaved credentials and base URLs for OpenAI catalog discovery", async () => {
+    const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      data: [{ id: "gpt-live-catalog-model" }],
+    })));
+    vi.stubGlobal("fetch", fetch);
+    const req = new NextRequest("http://localhost/api/v1/providers/openai/models", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        params: {
+          api_key: "synthetic-openai-key",
+          base_url: "https://openai.example/v1",
+        },
+      }),
+    });
+
+    const response = await POST(req, routeParams("openai"));
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject([
+      { id: "gpt-live-catalog-model" },
+    ]);
+    expect(String(fetch.mock.calls[0][0])).toBe("https://openai.example/v1/models");
+    expect(fetch.mock.calls[0][1]?.headers).toMatchObject({
+      Authorization: "Bearer synthetic-openai-key",
+    });
+  });
+
+  it("rejects malformed catalog request bodies", async () => {
+    const fetch = vi.fn();
+    vi.stubGlobal("fetch", fetch);
+    const req = new NextRequest("http://localhost/api/v1/providers/openai/models", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{",
+    });
+
+    const response = await POST(req, routeParams("openai"));
+
+    expect(response.status).toBe(400);
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("invalidates the cached fallback after credentialed catalog discovery", async () => {
+    vi.stubEnv("ANTHROPIC_API_KEY", "");
+    const fetch = vi.fn().mockImplementation(() => new Response(JSON.stringify({
+      data: [{ id: "claude-live-after-save" }],
+      has_more: false,
+      last_id: "claude-live-after-save",
+    })));
+    vi.stubGlobal("fetch", fetch);
+
+    const fallbackResponse = await GET(request("anthropic"), routeParams("anthropic"));
+    expect(fallbackResponse.status).toBe(200);
+    expect(fetch).not.toHaveBeenCalled();
+
+    const postRequest = new NextRequest("http://localhost/api/v1/providers/anthropic/models", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ params: { api_key: "synthetic-anthropic-key" } }),
+    });
+    const liveResponse = await POST(postRequest, routeParams("anthropic"));
+    expect(liveResponse.status).toBe(200);
+
+    upsertModelConfig("anthropic-config", "anthropic", "claude-live-after-save", {
+      api_key: "synthetic-anthropic-key",
+    }, true);
+    const nextResponse = await GET(request("anthropic", false), routeParams("anthropic"));
+
+    expect(nextResponse.status).toBe(200);
+    await expect(nextResponse.json()).resolves.toMatchObject([
+      { id: "claude-live-after-save" },
+    ]);
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
 });