fix: allow manual fallback models when provider catalog fails

Author: prplx

README.md

@@ -3,12 +3,19 @@
 <p align="center">
   <img width="1439" height="854" alt="image" src="https://github.com/user-attachments/assets/b4f68d1a-1c12-4abc-b810-1280f3ef49cb" />
 </p>
-<p align="center"><strong>Desktop AI chat, RP, writing, lorebook, RAG, and plugin workbench.</strong></p>
+<p align="center"><strong>Desktop AI chat, RP, writing, RAG, agent, and plugin workbench.</strong></p>
 
 Desktop app built with Electron, React, a local Express API, and SQLite.
 
 <img width="1440" height="857" alt="image" src="https://github.com/user-attachments/assets/03e75de3-5b39-4012-98f8-4c959eb1fc80" />
 
+## Current Release
+
+- Latest release: [`v0.9.7`](https://github.com/tg-prplx/vellium/releases/tag/v0.9.7)
+- Desktop builds: macOS (`arm64`, `x64`), Windows (`x64`), Linux (`x64` AppImage).
+- Release builds are unsigned. macOS and Windows may require manual confirmation on first launch.
+- The app is usable day to day, but still moving quickly. Expect active iteration around Agents, tool calling, and provider compatibility.
+
 ## User Documentation
 
 - Detailed user guide: [`docs/vellium/README.md`](./docs/vellium/README.md)
@@ -17,9 +24,9 @@ Desktop app built with Electron, React, a local Express API, and SQLite.
 ## Important
 - Use `npm run dev` for day-to-day development.
 - Use `npm run dev:electron` when testing the real desktop shell.
-- Use `npm run dist:mac` / `npm run dist:win` for desktop bundles.
-- CI desktop builds are unsigned. macOS and Windows may require manual confirmation.
-- Desktop packaging works, but it still has rough edges. It is usable, not polished.
+- Use `npm run dist:mac`, `npm run dist:win`, or `npm run dist:linux` for platform bundles.
+- CI publishes GitHub Release assets when a `v*` tag is pushed.
+- Local data is stored in `data/` during development and in the Electron user-data directory in packaged builds.
 
 ## Stack
 - Electron
@@ -30,14 +37,23 @@ Desktop app built with Electron, React, a local Express API, and SQLite.
 
 ## Core Features
 
+### Agents
+- Dedicated `Agents` workspace with ask, build, and research modes.
+- Workspace tools for listing, reading, searching, editing, moving, deleting, and diffing files.
+- Optional command execution for tests/builds, with separate security gates for shell-like commands, network commands, destructive file operations, and git writes.
+- OpenAI-compatible structured planning with JSON-schema responses when supported.
+- Mid-run corrections, abort/resume/retry, event traces, reasoning traces, and partial-response recovery.
+- Context management for long agent threads, including auto-compaction, continuation cues, duplicate read-only call guards, and stale-run cleanup after edits/deletes.
+
 ### Chat / RP
 - Branching chat history.
 - Edit, delete, resend, regenerate.
 - Multi-character chats with auto-turns.
 - RP controls: prompt stack, author note, scene state, presets, personas.
 - LoreBook / World Info support, including SillyTavern-compatible world info import/export.
-- Reasoning support, including `<think>...</think>` parsing.
+- Reasoning support, including streamed reasoning fields and `<think>...</think>` parsing.
 - Vision attachments and chat attachments.
+- MCP tool calling for OpenAI-compatible chat/completions providers, with text-tool-call fallback parsing for providers that do not emit native tool calls cleanly.
 
 ### Writing
 - Projects, chapters, scenes, outlines.
@@ -56,7 +72,10 @@ Desktop app built with Electron, React, a local Express API, and SQLite.
 - OpenAI-compatible providers.
 - KoboldCpp support.
 - Custom endpoint adapters for non-OpenAI / non-Kobold backends.
+- Presets for OpenAI, LM Studio, Ollama, KoboldCpp, OpenRouter, and custom OpenAI-compatible endpoints.
+- Manual fallback models for providers whose `/models` endpoint is missing, empty, or provider-specific.
 - Separate models for translate / compress / TTS / RAG.
+- API parameter forwarding controls for providers that reject unsupported sampling fields.
 
 ### Plugins / Extensions
 - Toolbar tabs from plugins.
@@ -72,7 +91,7 @@ Desktop app built with Electron, React, a local Express API, and SQLite.
 
 
 ## Requirements
-- Node.js + npm.
+- Node.js + npm. Node.js 20+ is recommended because CI builds with Node 20.
 - Python 3 + Pillow for icon generation:
 
 ```bash
@@ -148,6 +167,12 @@ Windows only:
 npm run dist:win
 ```
 
+Linux AppImage only:
+
+```bash
+npm run dist:linux
+```
+
 Build output goes to `release/`.
 
 ## GitHub Actions
@@ -156,8 +181,8 @@ Workflow:
 - `.github/workflows/build-desktop.yml`
 
 What it does:
-- builds macOS (`x64`, `arm64`) and Windows (`x64`) bundles,
-- uploads artifacts,
+- builds macOS (`x64`, `arm64`), Windows (`x64`), and Linux (`x64` AppImage) bundles,
+- uploads workflow artifacts,
 - publishes GitHub Release assets on `v*` tag pushes.
 
 ## Plugins
@@ -174,11 +199,11 @@ Plugin capabilities:
 - `Pluginfile` import/export.
 
 Useful docs:
-- `/Users/prplx/Documents/slv/docs/plugins/README.md`
+- [`docs/plugins/README.md`](./docs/plugins/README.md)
 
 Runtime plugin locations:
-- user plugins: `/Users/prplx/Documents/slv/data/plugins`
-- bundled plugins: `/Users/prplx/Documents/slv/data/bundled-plugins`
+- user plugins: `data/plugins`
+- bundled plugins: `data/bundled-plugins`
 
 Important:
 - plugins are local extensions, not a trusted public plugin marketplace model,
@@ -251,6 +276,8 @@ Generated files:
 - `npm run build` — frontend production build.
 - `npm run build:server` — bundled server build.
 - `npm run build:desktop` — full desktop build pipeline without publishing.
+- `npm run dist` — package all desktop targets supported by the current host/CI runner.
+- `npm run dist:mac` / `npm run dist:win` / `npm run dist:linux` — package a specific desktop target.
 - `npm run rebuild:native` — rebuild `better-sqlite3`.
 - `npm run test` — Vitest.
 

docs/vellium/README.md

@@ -8,10 +8,11 @@ Vellium is a local-first desktop/workbench app for:
 - long-form writing workflows
 - characters and LoreBooks
 - knowledge collections and RAG
+- autonomous agent workflows over a selected workspace
 - MCP / tool calling
 - local plugins and themes
 
-This guide documents the current UI and is based on the real app areas: `Welcome`, `Chat`, `Writing`, `Characters`, `LoreBooks`, `Knowledge`, `Settings`, and plugin-powered surfaces.
+This guide documents the current UI and is based on the real app areas: `Welcome`, `Chat`, `Writing`, `Agents`, `Characters`, `LoreBooks`, `Knowledge`, `Settings`, and plugin-powered surfaces.
 
 The screenshots in this guide are local captures from the current app build. Where it makes onboarding clearer, they use `Simple Mode` so the first-run flow matches what many users will actually see.
 
@@ -41,9 +42,11 @@ flowchart LR
   F["LoreBooks"] --> C
   G["Knowledge"] --> C
   G --> D
+  B --> I["Agents"]
   B --> H["Plugins / Themes / MCP"]
   H --> C
   H --> D
+  H --> I
 ```
 
 ## Workspaces
@@ -52,6 +55,7 @@ flowchart LR
 | --- | --- | --- |
 | `Chat` | Dialogues, RP, tool calling, translation, TTS | `Characters`, `LoreBooks`, `Knowledge`, `Settings` |
 | `Writing` | Books, chapters, scenes, drafts, summaries, lenses | `Characters`, `Knowledge`, `Settings` |
+| `Agents` | Ask/build/research workflows over a workspace with tools, traces, and resumable runs | `Settings`, provider profiles, workspace/tool security |
 | `Characters` | Importing and editing character cards | `Chat`, `Writing` |
 | `LoreBooks` | World facts, trigger keys, scripted prompt injections | `Chat` |
 | `Knowledge` | Retrieval collections for RAG | `Chat`, `Writing`, `Settings` |
@@ -66,13 +70,15 @@ flowchart LR
 4. Add or import a character in `Characters`.
 5. If your workflow needs world facts, create a LoreBook.
 6. If your workflow needs retrieval, create a knowledge collection in `Knowledge`.
-7. Only after that move on to multi-character scenes, writer workflows, plugins, and MCP.
+7. For workspace automation, create an `Agents` thread after providers and tool/security settings are configured.
+8. Only after that move on to multi-character scenes, writer workflows, plugins, and MCP.
 
 ## Important Things to Know Up Front
 
 - Vellium is not tied to a single backend. Chat, translation, compression, TTS, and RAG can all use different models.
 - `Local-only mode` limits the app to localhost or private-network endpoints.
 - Tool calling through MCP only works with OpenAI-compatible chat/completions providers, not with KoboldCpp.
+- Agents can use first-party workspace tools when enabled. Command execution, network commands, destructive file operations, and git writes are separately gated in settings.
 - `Knowledge` and `LoreBooks` solve different problems: one is retrieval-based, the other is trigger-based scripted context.
 - Plugins in Vellium are local extensions. Treat their permissions the same way you would treat shell tools or third-party scripts.
 

server/app/createApp.integration.test.ts

@@ -3287,6 +3287,42 @@ process.stdin.on("data", (chunk) => {
     });
   });
 
+  it("uses manual fallback models when a provider model endpoint cannot be loaded", async () => {
+    const fallbackPayload = {
+      baseUrl: `${mockProviderBaseUrl}/missing-catalog`,
+      apiKey: "test-key",
+      fullLocalOnly: false,
+      providerType: "openai",
+      adapterId: null,
+      manualModels: ["featherless/manual-model"]
+    };
+
+    const previewModels = await postJson("/api/providers/preview/models", fallbackPayload);
+    expect(previewModels).toEqual([{ id: "featherless/manual-model" }]);
+
+    const previewTest = await postJson("/api/providers/preview/test", fallbackPayload);
+    expect(previewTest).toEqual({ ok: true });
+
+    const savedProvider = await postJson("/api/providers", {
+      id: "manual-fallback-provider",
+      name: "Manual Fallback Provider",
+      baseUrl: fallbackPayload.baseUrl,
+      apiKey: fallbackPayload.apiKey,
+      proxyUrl: null,
+      fullLocalOnly: false,
+      providerType: "openai",
+      adapterId: null,
+      manualModels: fallbackPayload.manualModels
+    });
+    expect(savedProvider.manualModels).toEqual(["featherless/manual-model"]);
+
+    const savedModels = await parseJsonResponse(
+      "/api/providers/manual-fallback-provider/models",
+      await fetch(`${baseUrl}/api/providers/manual-fallback-provider/models`)
+    );
+    expect(savedModels).toEqual([{ id: "featherless/manual-model" }]);
+  });
+
   it("streams tool-calling turns through an MCP server and persists tool traces", async () => {
     await updateSettings({
       activeProviderId: "mock-openai",

server/routes/providers.ts

@@ -78,7 +78,10 @@ async function fetchOpenAiCompatibleModels(baseUrlRaw: string, apiKeyRaw: string
 
   const apiKey = String(apiKeyRaw || "").trim();
   const response = await fetch(`${baseUrl}/models`, {
-    headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined
+    headers: {
+      Accept: "application/json",
+      ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {})
+    }
   });
   if (!response.ok) {
     const text = await response.text().catch(() => "");
@@ -109,6 +112,26 @@ async function fetchOpenAiCompatibleModels(baseUrlRaw: string, apiKeyRaw: string
   return Array.from(uniq.values());
 }
 
+function mergeManualModels(models: Array<{ id: string }>, manualModels: Array<{ id: string }>) {
+  if (models.length === 0) return manualModels;
+  return [
+    ...models,
+    ...manualModels.filter((item) => !models.some((model) => model.id === item.id))
+  ];
+}
+
+async function resolveWithManualFallback(
+  manualModels: Array<{ id: string }>,
+  fetchModels: () => Promise<Array<{ id: string }>>
+) {
+  try {
+    return mergeManualModels(await fetchModels(), manualModels);
+  } catch (error) {
+    if (manualModels.length > 0) return manualModels;
+    throw error;
+  }
+}
+
 function assertProviderAllowed(baseUrl: string, fullLocalOnly: boolean) {
   const settings = getSettings();
   if (settings.fullLocalMode && !isLocalhostUrl(baseUrl)) {
@@ -141,25 +164,23 @@ async function resolveProviderModels(row: Pick<ProviderRow, "base_url" | "api_ke
 
   const providerType = normalizeProviderType(row.provider_type);
   if (providerType === "koboldcpp") {
-    const koboldModels = await fetchKoboldModels(row);
-    const fetched = koboldModels.map((id) => ({ id }));
-    return fetched.length > 0
-      ? [...fetched, ...manualModels.filter((item) => !fetched.some((model) => model.id === item.id))]
-      : manualModels;
+    return resolveWithManualFallback(manualModels, async () => {
+      const koboldModels = await fetchKoboldModels(row);
+      return koboldModels.map((id) => ({ id }));
+    });
   }
 
   if (providerType === "custom") {
-    const customModels = await fetchCustomAdapterModels(row);
-    const fetched = customModels.map((id) => ({ id }));
-    return fetched.length > 0
-      ? [...fetched, ...manualModels.filter((item) => !fetched.some((model) => model.id === item.id))]
-      : manualModels;
+    return resolveWithManualFallback(manualModels, async () => {
+      const customModels = await fetchCustomAdapterModels(row);
+      return customModels.map((id) => ({ id }));
+    });
   }
 
-  const models = await fetchOpenAiCompatibleModels(row.base_url, row.api_key_cipher);
-  return models.length > 0
-    ? [...models, ...manualModels.filter((item) => !models.some((model) => model.id === item.id))]
-    : manualModels;
+  return resolveWithManualFallback(
+    manualModels,
+    () => fetchOpenAiCompatibleModels(row.base_url, row.api_key_cipher)
+  );
 }
 
 router.post("/", (req, res) => {