feat: migrate legacy mux-gateway model format to canonical form

Add forward compatibility for users who have directly specified
mux-gateway models in their config:

- migrateGatewayModel(): converts 'mux-gateway:provider/model' to
  'provider:model' and auto-enables gateway toggle for that model
- Applied in useSendMessageOptions, getSendOptionsFromStorage
- useModelLRU: migrates LRU list and default model on load
- Malformed gateway entries are filtered out

Example: 'mux-gateway:anthropic/claude-opus-4-5' becomes
'anthropic:claude-opus-4-5' with gateway toggle enabled

Author: ammar-agent

src/browser/hooks/useGatewayModels.ts

@@ -30,6 +30,50 @@ export function isGatewayEnabled(modelId: string): boolean {
   return gatewayModels.includes(modelId);
 }
 
+/**
+ * Check if a model string is in mux-gateway format.
+ * @param modelId Model string to check
+ * @returns true if model is "mux-gateway:provider/model" format
+ */
+export function isGatewayFormat(modelId: string): boolean {
+  return modelId.startsWith("mux-gateway:");
+}
+
+/**
+ * Migrate a mux-gateway model to canonical format and enable gateway toggle.
+ * Converts "mux-gateway:provider/model" to "provider:model" and marks it for gateway routing.
+ *
+ * This provides forward compatibility for users who have directly specified
+ * mux-gateway models in their config.
+ *
+ * @param modelId Model string that may be in gateway format
+ * @returns Canonical model ID (e.g., "anthropic:claude-opus-4-5")
+ */
+export function migrateGatewayModel(modelId: string): string {
+  if (!isGatewayFormat(modelId)) {
+    return modelId;
+  }
+
+  // mux-gateway:anthropic/claude-opus-4-5 → anthropic:claude-opus-4-5
+  const inner = modelId.slice("mux-gateway:".length);
+  const slashIndex = inner.indexOf("/");
+  if (slashIndex === -1) {
+    return modelId; // Malformed, return as-is
+  }
+
+  const provider = inner.slice(0, slashIndex);
+  const model = inner.slice(slashIndex + 1);
+  const canonicalId = `${provider}:${model}`;
+
+  // Auto-enable gateway for this model (one-time migration)
+  const gatewayModels = readPersistedState<string[]>(GATEWAY_MODELS_KEY, []);
+  if (!gatewayModels.includes(canonicalId)) {
+    updatePersistedState(GATEWAY_MODELS_KEY, [...gatewayModels, canonicalId]);
+  }
+
+  return canonicalId;
+}
+
 /**
  * Check if the gateway provider is available (has coupon code configured)
  */

src/browser/hooks/useModelLRU.ts

@@ -4,6 +4,7 @@ import { MODEL_ABBREVIATIONS } from "@/browser/utils/slashCommands/registry";
 import { defaultModel } from "@/common/utils/ai/models";
 import { WORKSPACE_DEFAULTS } from "@/constants/workspaceDefaults";
 import { useAPI } from "@/browser/contexts/API";
+import { migrateGatewayModel, isGatewayFormat } from "./useGatewayModels";
 
 const MAX_LRU_SIZE = 12;
 const LRU_KEY = "model-lru";
@@ -36,7 +37,9 @@ export function evictModelFromLRU(model: string): void {
 
 export function getDefaultModel(): string {
   const persisted = readPersistedState<string | null>(DEFAULT_MODEL_KEY, null);
-  return persisted ?? FALLBACK_MODEL;
+  if (!persisted) return FALLBACK_MODEL;
+  // Migrate legacy mux-gateway format to canonical form
+  return migrateGatewayModel(persisted);
 }
 
 /**
@@ -60,10 +63,18 @@ export function useModelLRU() {
     { listener: true }
   );
 
-  // Merge any new defaults from MODEL_ABBREVIATIONS (only once on mount)
+  // Merge any new defaults from MODEL_ABBREVIATIONS and migrate legacy gateway models (only once on mount)
   useEffect(() => {
     setRecentModels((prev) => {
-      const merged = [...prev];
+      // Migrate any mux-gateway:provider/model entries to canonical form
+      const migrated = prev.map((m) => migrateGatewayModel(m));
+      // Remove any remaining mux-gateway entries that couldn't be migrated
+      const filtered = migrated.filter((m) => !isGatewayFormat(m));
+      // Deduplicate (migration might create duplicates)
+      const deduped = [...new Set(filtered)];
+
+      // Merge defaults
+      const merged = [...deduped];
       for (const defaultModel of DEFAULT_MODELS) {
         if (!merged.includes(defaultModel)) {
           merged.push(defaultModel);

src/browser/hooks/useSendMessageOptions.ts

@@ -2,7 +2,7 @@ import { useThinkingLevel } from "./useThinkingLevel";
 import { useMode } from "@/browser/contexts/ModeContext";
 import { usePersistedState } from "./usePersistedState";
 import { getDefaultModel } from "./useModelLRU";
-import { toGatewayModel } from "./useGatewayModels";
+import { toGatewayModel, migrateGatewayModel } from "./useGatewayModels";
 import { modeToToolPolicy, PLAN_MODE_INSTRUCTION } from "@/common/utils/ui/modeUtils";
 import { getModelKey } from "@/common/constants/storage";
 import type { SendMessageOptions } from "@/common/orpc/types";
@@ -27,9 +27,12 @@ function constructSendMessageOptions(
   const additionalSystemInstructions = mode === "plan" ? PLAN_MODE_INSTRUCTION : undefined;
 
   // Ensure model is always a valid string (defensive against corrupted localStorage)
-  const baseModel =
+  const rawModel =
     typeof preferredModel === "string" && preferredModel ? preferredModel : fallbackModel;
 
+  // Migrate any legacy mux-gateway:provider/model format to canonical form
+  const baseModel = migrateGatewayModel(rawModel);
+
   // Transform to gateway format if gateway is enabled for this model
   const model = toGatewayModel(baseModel);
 

src/browser/utils/messages/sendOptions.ts

@@ -2,7 +2,7 @@ import { getModelKey, getThinkingLevelKey, getModeKey } from "@/common/constants
 import { modeToToolPolicy, PLAN_MODE_INSTRUCTION } from "@/common/utils/ui/modeUtils";
 import { readPersistedState } from "@/browser/hooks/usePersistedState";
 import { getDefaultModel } from "@/browser/hooks/useModelLRU";
-import { toGatewayModel } from "@/browser/hooks/useGatewayModels";
+import { toGatewayModel, migrateGatewayModel } from "@/browser/hooks/useGatewayModels";
 import type { SendMessageOptions } from "@/common/orpc/types";
 import type { UIMode } from "@/common/types/mode";
 import type { ThinkingLevel } from "@/common/types/thinking";
@@ -39,7 +39,9 @@ function getProviderOptions(): MuxProviderOptions {
  */
 export function getSendOptionsFromStorage(workspaceId: string): SendMessageOptions {
   // Read model preference (workspace-specific), fallback to LRU default
-  const baseModel = readPersistedState<string>(getModelKey(workspaceId), getDefaultModel());
+  const rawModel = readPersistedState<string>(getModelKey(workspaceId), getDefaultModel());
+  // Migrate any legacy mux-gateway:provider/model format to canonical form
+  const baseModel = migrateGatewayModel(rawModel);
   // Transform to gateway format if gateway is enabled for this model
   const model = toGatewayModel(baseModel);