feat(providers): generalize account UI and per-provider fallback

Collapse Codex-only auth nav into Providers, add configurable
per-provider fallback hops, and keep runtime failover on the
existing combo engine so sofie patches stay reproducible.

Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>

Author: OnlineChef

gui/src/App.tsx

@@ -8,13 +8,12 @@ import Subagents from "./pages/Subagents";
 import Logs from "./pages/Logs";
 import Usage from "./pages/Usage";
 import Storage from "./pages/Storage";
-import CodexAuth from "./pages/CodexAuth";
 import ApiKeys from "./pages/ApiKeys";
 import Claude from "./pages/Claude";
 import Grok from "./pages/Grok";
 import Startup from "./pages/Startup";
 import ErrorBoundary from "./components/ErrorBoundary";
-import { IconGrid, IconServer, IconBoxes, IconBot, IconList, IconActivity, IconHardDrive, IconKey, IconGithub, IconMenu, IconSun, IconMoon, IconMonitor, IconGlobe, IconPower, IconSparkle, IconX } from "./icons";
+import { IconGrid, IconServer, IconBoxes, IconBot, IconList, IconActivity, IconHardDrive, IconGithub, IconMenu, IconSun, IconMoon, IconMonitor, IconGlobe, IconPower, IconSparkle, IconX } from "./icons";
 import { useI18n, useT, LOCALES, type Locale, type TKey } from "./i18n/shared";
 import { Select, Switch } from "./ui";
 import { installApiAuthFetch } from "./api";
@@ -37,7 +36,6 @@ const PAGE_TKEY: Record<Page, TKey> = {
   logs: "nav.logs",
   usage: "nav.usage",
   storage: "nav.storage",
-  "codex-auth": "nav.codexAuth",
   api: "nav.api",
   claude: "nav.claude",
   grok: "nav.grok",
@@ -48,7 +46,6 @@ const THEME_KEY = "ocx-theme";
 
 const NAV: { id: Page; tkey: TKey; Icon: typeof IconGrid }[] = [
   { id: "dashboard", tkey: "nav.dashboard", Icon: IconGrid },
-  { id: "codex-auth", tkey: "nav.codexAuth", Icon: IconKey },
   { id: "providers", tkey: "nav.providers", Icon: IconServer },
   { id: "models", tkey: "nav.models", Icon: IconBoxes },
   { id: "subagents", tkey: "nav.subagents", Icon: IconBot },
@@ -305,7 +302,6 @@ export default function App() {
             {page === "logs" && <Logs apiBase={API_BASE} />}
             {page === "usage" && <Usage apiBase={API_BASE} />}
             {page === "storage" && <Storage apiBase={API_BASE} />}
-            {page === "codex-auth" && <CodexAuth apiBase={API_BASE} />}
             {page === "api" && <ApiKeys apiBase={API_BASE} />}
             {page === "claude" && <Claude apiBase={API_BASE} />}
             {page === "grok" && <Grok apiBase={API_BASE} />}

gui/src/app-routing.ts

@@ -12,7 +12,6 @@ export type Page =
   | "logs"
   | "usage"
   | "storage"
-  | "codex-auth"
   | "api"
   | "claude"
   | "grok";
@@ -27,7 +26,6 @@ export const VALID_PAGES = new Set<Page>([
   "logs",
   "usage",
   "storage",
-  "codex-auth",
   "api",
   "claude",
   "grok",
@@ -83,6 +81,12 @@ export function resolveAppHashChange(rawHash: string): AppHashChangeAction {
     return { page: "providers", replaceTo: "providers" };
   }
 
+  // Account management used to be a Codex-only destination. Providers now owns
+  // OAuth accounts, API-key pools and the OpenAI/Codex pool in one place.
+  if (rawHash === "codex-auth" || rawHash.startsWith("codex-auth/")) {
+    return { page: "providers", replaceTo: "providers" };
+  }
+
   // An unrecognised sub-hash is normalised away rather than left in the URL.
   if (!hashBelongsToPage(rawHash, nextPage)) {
     return { page: nextPage, replaceTo: nextPage };

gui/src/components/provider-workspace/ProviderDetails.tsx

@@ -30,6 +30,7 @@ export default function ProviderDetails({
   modelUsage,
   quotaReport,
   availableModels,
+  peerProviders,
   hasLiveModels,
   selectedModels,
   modelsLoading,
@@ -58,6 +59,7 @@ export default function ProviderDetails({
   modelUsage?: ProviderModelUsageRow[];
   quotaReport?: ProviderQuotaReportView;
   availableModels: string[];
+  peerProviders?: import("./ProviderSettings").ProviderPeerOption[];
   /** Server-reported live-catalog provenance; see filterModels(). */
   hasLiveModels: boolean;
   selectedModels: string[];
@@ -291,6 +293,7 @@ export default function ProviderDetails({
             item={item}
             apiBase={apiBase}
             availableModels={availableModels}
+            peerProviders={peerProviders}
             onUpdateProvider={onUpdateProvider}
             onDirtyChange={setSettingsDirty}
             onRegisterSave={registerSettingsSave}

gui/src/components/provider-workspace/ProviderSettings.tsx

@@ -11,22 +11,56 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import { baseUrlForChoice, matchChoiceId, resolvedBaseUrlForChoice } from "../../base-url-choice";
 import { readJsonIfOk } from "../../fetch-json";
 import { useT } from "../../i18n/shared";
-import { IconLock } from "../../icons";
+import { IconLock, IconPlus, IconTrash } from "../../icons";
 import { isCatalogProviderId } from "../../provider-icons";
 import type { CatalogPreset } from "../provider-catalog/provider-presets";
 import { authModeLabel } from "./ProviderRail";
-import type { WorkspaceItem, ProviderUpdatePatch } from "./types";
+import type { ProviderFallbackTarget, WorkspaceItem, ProviderUpdatePatch } from "./types";
 
 const ADAPTERS = ["openai-responses", "openai-chat", "anthropic", "google", "azure-openai", "cursor"] as const;
 const EMPTY_MODELS: string[] = [];
+const EMPTY_PEERS: ProviderPeerOption[] = [];
+
+export type ProviderPeerOption = {
+  name: string;
+  disabled?: boolean;
+  models?: string[];
+  defaultModel?: string;
+};
 
 type ChoicesStatus = "idle" | "loading" | "ready" | "error";
 
+function normalizeFallback(raw: ProviderFallbackTarget[] | undefined): ProviderFallbackTarget[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map(row => ({
+      provider: typeof row.provider === "string" ? row.provider.trim() : "",
+      model: typeof row.model === "string" ? row.model.trim() : "",
+    }))
+    .filter(row => row.provider && row.model);
+}
+
+function fallbackFingerprint(rows: ProviderFallbackTarget[] | undefined): string {
+  return JSON.stringify(normalizeFallback(rows));
+}
+
+function modelsForPeer(peer: ProviderPeerOption | undefined, currentModel: string): string[] {
+  const set = new Set<string>();
+  for (const id of peer?.models ?? []) {
+    if (id.trim()) set.add(id.trim());
+  }
+  if (peer?.defaultModel?.trim()) set.add(peer.defaultModel.trim());
+  if (currentModel.trim()) set.add(currentModel.trim());
+  return [...set].sort((a, b) => a.localeCompare(b));
+}
+
 export default function ProviderSettings({
-  item, availableModels = EMPTY_MODELS, apiBase, onUpdateProvider, onDirtyChange, onRegisterSave,
+  item, availableModels = EMPTY_MODELS, peerProviders = EMPTY_PEERS, apiBase, onUpdateProvider, onDirtyChange, onRegisterSave,
 }: {
   item: WorkspaceItem;
   availableModels?: string[];
+  /** Other configured providers (and their known models) for the fallback picker. */
+  peerProviders?: ProviderPeerOption[];
   /** When set, load endpoint choices for catalog providers that expose baseUrlChoices. */
   apiBase?: string;
   onUpdateProvider?: (name: string, patch: ProviderUpdatePatch) => Promise<{ ok: boolean; error?: string }>;
@@ -44,6 +78,7 @@ export default function ProviderSettings({
   const [note, setNote] = useState(item.note ?? "");
   const [allowPrivateNetwork, setAllowPrivateNetwork] = useState(item.allowPrivateNetwork ?? false);
   const [liveModels, setLiveModels] = useState(item.liveModels !== false);
+  const [fallback, setFallback] = useState<ProviderFallbackTarget[]>(() => normalizeFallback(item.fallback));
   const [saving, setSaving] = useState(false);
   const [msg, setMsg] = useState<{ ok: boolean; text: string } | null>(null);
   const [baseUrlChoices, setBaseUrlChoices] = useState<CatalogPreset["baseUrlChoices"]>();
@@ -60,9 +95,10 @@ export default function ProviderSettings({
     setNote(item.note ?? "");
     setAllowPrivateNetwork(item.allowPrivateNetwork ?? false);
     setLiveModels(item.liveModels !== false);
+    setFallback(normalizeFallback(item.fallback));
     setMsg(null);
     queueMicrotask(() => setEndpointChoice(matchChoiceId(baseUrlChoices, item.baseUrl)));
-  }, [item.adapter, item.baseUrl, item.defaultModel, item.authMode, item.apiKeyTransport, item.keyOptional, item.note, item.allowPrivateNetwork, item.liveModels, baseUrlChoices]);
+  }, [item.adapter, item.baseUrl, item.defaultModel, item.authMode, item.apiKeyTransport, item.keyOptional, item.note, item.allowPrivateNetwork, item.liveModels, item.fallback, baseUrlChoices]);
   /* eslint-enable react-hooks/set-state-in-effect */
 
   useEffect(() => {
@@ -102,7 +138,8 @@ export default function ProviderSettings({
     || (adapter.trim() === "anthropic" && authMode === "key" && apiKeyTransport !== (item.apiKeyTransport ?? "x-api-key"))
     || note.trim() !== (item.note ?? "")
     || allowPrivateNetwork !== (item.allowPrivateNetwork ?? false)
-    || liveModels !== (item.liveModels !== false);
+    || liveModels !== (item.liveModels !== false)
+    || fallbackFingerprint(fallback) !== fallbackFingerprint(item.fallback);
 
   useEffect(() => { onDirtyChange?.(dirty); return () => onDirtyChange?.(false); }, [dirty, onDirtyChange]);
 
@@ -119,6 +156,11 @@ export default function ProviderSettings({
     return list;
   }, [adapter]);
 
+  const fallbackPeers = useMemo(
+    () => peerProviders.filter(p => p.name !== item.name),
+    [peerProviders, item.name],
+  );
+
   const isPreset = isCatalogProviderId(item.name);
   const hasEndpointPicker = choicesStatus === "ready" && !!(baseUrlChoices && baseUrlChoices.length > 0);
   const supportsApiKeyTransport = adapter.trim() === "anthropic" && authMode === "key";
@@ -132,10 +174,24 @@ export default function ProviderSettings({
       ? resolvedBaseUrlForChoice(baseUrlChoices, endpointChoice, baseUrl)
       : baseUrl.trim();
     if (!adapter.trim() || !nextBaseUrl) { setMsg({ ok: false, text: t("pws.adapterBaseRequired") }); return false; }
+    const nextFallback = normalizeFallback(fallback);
+    if (fallback.some(row => (row.provider.trim() && !row.model.trim()) || (!row.provider.trim() && row.model.trim()))) {
+      setMsg({ ok: false, text: t("pws.fallbackIncomplete") });
+      return false;
+    }
     setSaving(true);
     setMsg(null);
     try {
-      const patch: ProviderUpdatePatch = { adapter: adapter.trim(), baseUrl: nextBaseUrl, defaultModel: defaultModel.trim(), authMode, note: note.trim(), allowPrivateNetwork, liveModels };
+      const patch: ProviderUpdatePatch = {
+        adapter: adapter.trim(),
+        baseUrl: nextBaseUrl,
+        defaultModel: defaultModel.trim(),
+        authMode,
+        note: note.trim(),
+        allowPrivateNetwork,
+        liveModels,
+        fallback: nextFallback,
+      };
       if (supportsApiKeyTransport) patch.apiKeyTransport = apiKeyTransport;
       else if (item.apiKeyTransport !== undefined) patch.apiKeyTransport = "";
       const res = await onUpdateProvider(item.name, patch);
@@ -160,19 +216,25 @@ export default function ProviderSettings({
     setAdapter(item.adapter); setBaseUrl(item.baseUrl);
     setDefaultModel(item.defaultModel ?? ""); setAuthMode(initialAuth);
     setApiKeyTransport(item.apiKeyTransport ?? "x-api-key");
-    setNote(item.note ?? ""); setAllowPrivateNetwork(item.allowPrivateNetwork ?? false); setLiveModels(item.liveModels !== false); setMsg(null);
+    setNote(item.note ?? ""); setAllowPrivateNetwork(item.allowPrivateNetwork ?? false); setLiveModels(item.liveModels !== false);
+    setFallback(normalizeFallback(item.fallback));
+    setMsg(null);
     setEndpointChoice(matchChoiceId(baseUrlChoices, item.baseUrl));
   };
 
-  const endpointLabel = (id: string, fallback: string) => {
+  const endpointLabel = (id: string, fallbackLabel: string) => {
     switch (id) {
       case "token-plan": return t("modal.endpoint.tokenPlan");
       case "payg": return t("modal.endpoint.payAsYouGo");
       case "custom": return t("modal.endpoint.custom");
-      default: return fallback;
+      default: return fallbackLabel;
     }
   };
 
+  const updateFallbackRow = (index: number, patch: Partial<ProviderFallbackTarget>) => {
+    setFallback(rows => rows.map((row, i) => i === index ? { ...row, ...patch } : row));
+  };
+
   return (
     <div className="pwi-settings-form">
       <label className="pwi-settings-field">
@@ -264,6 +326,77 @@ export default function ProviderSettings({
           <span className="muted text-label" style={{ display: "block", marginTop: 2 }}>{t("pws.liveModelsDesc")}</span>
         </span>
       </label>
+
+      <div className="pwi-settings-field">
+        <span className="pwi-settings-label">{t("pws.fallback")}</span>
+        <span className="pwi-settings-hint">{t("pws.fallbackDesc")}</span>
+        <div className="pwi-fallback-list">
+          {fallback.map((row, index) => {
+            const peer = fallbackPeers.find(p => p.name === row.provider);
+            const modelIds = modelsForPeer(peer, row.model);
+            return (
+              <div key={index} className="pwi-fallback-row">
+                <select
+                  className="input"
+                  value={row.provider}
+                  aria-label={t("pws.fallback.provider")}
+                  onChange={e => {
+                    const provider = e.target.value;
+                    const first = modelsForPeer(fallbackPeers.find(p => p.name === provider), "")[0] ?? "";
+                    updateFallbackRow(index, { provider, model: first });
+                  }}
+                >
+                  <option value="">{t("pws.fallback.pickProvider")}</option>
+                  {fallbackPeers.map(p => (
+                    <option key={p.name} value={p.name}>
+                      {p.disabled ? t("pws.fallback.disabled", { name: p.name }) : p.name}
+                    </option>
+                  ))}
+                </select>
+                {modelIds.length > 0 ? (
+                  <select
+                    className="input"
+                    value={row.model}
+                    disabled={!row.provider}
+                    aria-label={t("pws.fallback.model")}
+                    onChange={e => updateFallbackRow(index, { model: e.target.value })}
+                  >
+                    <option value="">{t("pws.fallback.pickModel")}</option>
+                    {modelIds.map(id => <option key={id} value={id}>{id}</option>)}
+                  </select>
+                ) : (
+                  <input
+                    className="input"
+                    value={row.model}
+                    disabled={!row.provider}
+                    placeholder={t("pws.fallback.modelPlaceholder")}
+                    aria-label={t("pws.fallback.model")}
+                    onChange={e => updateFallbackRow(index, { model: e.target.value })}
+                  />
+                )}
+                <button
+                  type="button"
+                  className="btn btn-ghost btn-sm"
+                  aria-label={t("common.remove")}
+                  onClick={() => setFallback(rows => rows.filter((_, i) => i !== index))}
+                >
+                  <IconTrash width={14} height={14} />
+                </button>
+              </div>
+            );
+          })}
+          <button
+            type="button"
+            className="btn btn-ghost btn-sm"
+            style={{ alignSelf: "flex-start" }}
+            disabled={fallbackPeers.length === 0}
+            onClick={() => setFallback(rows => [...rows, { provider: "", model: "" }])}
+          >
+            <IconPlus width={14} height={14} /> {t("pws.fallback.add")}
+          </button>
+        </div>
+      </div>
+
       {dirty && (
         <div className="pwi-settings-sticky-bar">
           <span className="muted">{t("pws.settingsUnsavedBar")}</span>

gui/src/components/provider-workspace/types.ts

@@ -85,6 +85,11 @@ export interface ProviderAuthHandlers {
   onEditAlias: (provider: string, type: "oauth" | "api-key", id: string, current?: string) => void | Promise<void>;
 }
 
+export type ProviderFallbackTarget = {
+  provider: string;
+  model: string;
+};
+
 export type ProviderUpdatePatch = {
   adapter?: string;
   baseUrl?: string;
@@ -96,4 +101,6 @@ export type ProviderUpdatePatch = {
   disabled?: boolean;
   allowPrivateNetwork?: boolean;
   liveModels?: boolean;
+  /** Ordered failover chain; `[]` clears. */
+  fallback?: ProviderFallbackTarget[];
 };

gui/src/i18n/de.ts

@@ -4,7 +4,7 @@ import type { TKey } from "./en";
 export const de: Record<TKey, string> = {
   "nav.dashboard": "Übersicht",
   "nav.startup": "Startsicherheit",
-  "nav.providers": "Anbieter",
+  "nav.providers": "Anbieter & Konten",
   "nav.models": "Modelle",
   "nav.combos": "Combos",
   "nav.subagents": "Sub-Agenten",
@@ -1262,6 +1262,16 @@ export const de: Record<TKey, string> = {
   "pws.allowPrivateNetwork": "Lokales/privates Netzwerk erlauben",
   "pws.liveModels": "Modelle beim Anbieter erkennen",
   "pws.liveModelsDesc": "Lädt den Live-Modellkatalog des Anbieters. Ausschalten, um nur konfigurierte statische Modelle zu verwenden.",
+  "pws.fallback": "Fallback-Anbieter",
+  "pws.fallbackDesc": "Bei wiederholbaren Fehlern (429, 5xx, Stream-Abbruch) werden diese Ziele der Reihe nach versucht. Leer lassen, um den Fehler an den Client zurückzugeben.",
+  "pws.fallback.add": "Fallback hinzufügen",
+  "pws.fallback.provider": "Fallback-Anbieter",
+  "pws.fallback.model": "Fallback-Modell",
+  "pws.fallback.pickProvider": "Anbieter wählen",
+  "pws.fallback.pickModel": "Modell wählen",
+  "pws.fallback.modelPlaceholder": "Modell-ID",
+  "pws.fallback.disabled": "{name} (deaktiviert)",
+  "pws.fallbackIncomplete": "Jede Fallback-Zeile braucht Anbieter und Modell.",
   "pws.optionalPlaceholder": "Optional",
   "pws.providerId": "Anbieter-ID",
   "pws.reauth": "Erneute Anmeldung erforderlich",

gui/src/i18n/en.ts

@@ -4,7 +4,7 @@ export const en = {
   // sidebar / nav / common
   "nav.dashboard": "Dashboard",
   "nav.startup": "Startup",
-  "nav.providers": "Providers",
+  "nav.providers": "Providers & accounts",
   "nav.models": "Models",
   "nav.combos": "Combos",
   "nav.subagents": "Subagents",
@@ -982,6 +982,16 @@ export const en = {
   "pws.allowPrivateNetwork": "Allow local/private network",
   "pws.liveModels": "Discover models from provider",
   "pws.liveModelsDesc": "Fetch the provider's live model catalog. Turn this off to use only configured/static models.",
+  "pws.fallback": "Fallback providers",
+  "pws.fallbackDesc": "On retryable failures (429, 5xx, stream drop), hop to these targets in order. Leave empty to return the error to the client.",
+  "pws.fallback.add": "Add fallback",
+  "pws.fallback.provider": "Fallback provider",
+  "pws.fallback.model": "Fallback model",
+  "pws.fallback.pickProvider": "Pick provider",
+  "pws.fallback.pickModel": "Pick model",
+  "pws.fallback.modelPlaceholder": "model id",
+  "pws.fallback.disabled": "{name} (disabled)",
+  "pws.fallbackIncomplete": "Each fallback row needs both a provider and a model.",
   "pws.optionalPlaceholder": "Optional",
   "pws.providerId": "Provider ID",
   "pws.reauth": "Needs re-auth",