Fallback to free model for gated defaults (#208)

* Fallback to free model for gated defaults

Co-authored-by: OpenAI Codex <codex@openai.com>

* Cover explicit gated model access for HF users

Co-authored-by: OpenAI Codex <codex@openai.com>

* Seed model picker from created session

Co-authored-by: OpenAI Codex <codex@openai.com>

---------

Co-authored-by: OpenAI Codex <codex@openai.com>

backend/models.py

@@ -66,6 +66,7 @@ class SessionResponse(BaseModel):
 
     session_id: str
     ready: bool = True
+    model: str | None = None
 
 
 class PendingApprovalTool(BaseModel):

backend/routes/agent.py

@@ -44,6 +44,7 @@ router = APIRouter(prefix="/api", tags=["agent"])
 _background_teardown_tasks: set[asyncio.Task] = set()
 
 DEFAULT_CLAUDE_MODEL_ID = "bedrock/us.anthropic.claude-opus-4-6-v1"
+DEFAULT_FREE_MODEL_ID = "moonshotai/Kimi-K2.6"
 GATED_MODEL_IDS = {
     DEFAULT_CLAUDE_MODEL_ID,
     "openai/gpt-5.5",
@@ -113,6 +114,20 @@ def _is_gated_model(model_id: str) -> bool:
     return model_id in GATED_MODEL_IDS
 
 
+def _premium_model_restricted_error() -> HTTPException:
+    return HTTPException(
+        status_code=403,
+        detail={
+            "error": "premium_model_restricted",
+            "message": (
+                "Premium models are gated to HF staff. Pick a free model — "
+                "Kimi K2.6, MiniMax M2.7, GLM 5.1, or DeepSeek V4 Pro — "
+                "instead."
+            ),
+        },
+    )
+
+
 async def _require_hf_for_gated_model(request: Request, model_id: str) -> None:
     """403 if a non-``huggingface``-org user tries to select a gated model.
 
@@ -123,17 +138,35 @@ async def _require_hf_for_gated_model(request: Request, model_id: str) -> None:
     if not _is_gated_model(model_id):
         return
     if not await require_huggingface_org_member(request):
-        raise HTTPException(
-            status_code=403,
-            detail={
-                "error": "premium_model_restricted",
-                "message": (
-                    "Premium models are gated to HF staff. Pick a free model — "
-                    "Kimi K2.6, MiniMax M2.7, GLM 5.1, or DeepSeek V4 Pro — "
-                    "instead."
-                ),
-            },
-        )
+        raise _premium_model_restricted_error()
+
+
+async def _model_override_for_new_session(
+    request: Request,
+    requested_model: str | None,
+) -> str | None:
+    """Return the model override to use when creating a new session.
+
+    Explicit gated-model requests keep the hard membership gate. Implicit
+    default sessions are more forgiving: when the configured default is gated
+    and the user lacks access, start them on the first free model instead of
+    blocking session creation.
+    """
+    resolved_model = requested_model or session_manager.config.model_name
+    if not _is_gated_model(resolved_model):
+        return requested_model
+    if await require_huggingface_org_member(request):
+        return requested_model
+    if requested_model:
+        raise _premium_model_restricted_error()
+
+    logger.info(
+        "Default gated model %s is unavailable to this user; "
+        "creating session with free fallback %s",
+        resolved_model,
+        DEFAULT_FREE_MODEL_ID,
+    )
+    return DEFAULT_FREE_MODEL_ID
 
 
 async def _enforce_gated_model_quota(
@@ -365,9 +398,9 @@ async def create_session(
     if model and model not in valid_ids:
         raise HTTPException(status_code=400, detail=f"Unknown model: {model}")
 
-    # Deployed paid models are gated to HF staff; free and local-dev models pass through.
-    resolved_model = model or session_manager.config.model_name
-    await _require_hf_for_gated_model(request, resolved_model)
+    # Explicit premium selections remain gated. If the implicit configured
+    # default is unavailable, start the session on a free model instead.
+    model = await _model_override_for_new_session(request, model)
 
     try:
         session_id = await session_manager.create_session(
@@ -380,7 +413,11 @@ async def create_session(
     except SessionCapacityError as e:
         raise HTTPException(status_code=503, detail=str(e))
 
-    return SessionResponse(session_id=session_id, ready=True)
+    return SessionResponse(
+        session_id=session_id,
+        ready=True,
+        model=model or session_manager.config.model_name,
+    )
 
 
 @router.post("/session/restore-summary", response_model=SessionResponse)
@@ -406,8 +443,7 @@ async def restore_session_summary(
     if model and model not in valid_ids:
         raise HTTPException(status_code=400, detail=f"Unknown model: {model}")
 
-    resolved_model = model or session_manager.config.model_name
-    await _require_hf_for_gated_model(request, resolved_model)
+    model = await _model_override_for_new_session(request, model)
 
     try:
         session_id = await session_manager.create_session(
@@ -432,7 +468,11 @@ async def restore_session_summary(
         f"Seeded session {session_id} for {user.get('username', 'unknown')} "
         f"(summary of {summarized} messages)"
     )
-    return SessionResponse(session_id=session_id, ready=True)
+    return SessionResponse(
+        session_id=session_id,
+        ready=True,
+        model=model or session_manager.config.model_name,
+    )
 
 
 @router.get("/session/{session_id}", response_model=SessionInfo)

frontend/src/components/Chat/ChatInput.tsx

@@ -8,6 +8,7 @@ import { useUserQuota } from '@/hooks/useUserQuota';
 import ClaudeCapDialog from '@/components/ClaudeCapDialog';
 import JobsUpgradeDialog from '@/components/JobsUpgradeDialog';
 import { useAgentStore } from '@/store/agentStore';
+import { useSessionStore } from '@/store/sessionStore';
 import {
   CLAUDE_MODEL_PATH,
   FIRST_FREE_MODEL_PATH,
@@ -79,11 +80,16 @@ const DEFAULT_MODEL_OPTIONS: ModelOption[] = [
 ];
 
 const findModelByPath = (path: string, options: ModelOption[]): ModelOption | undefined => {
+  if (isClaudePath(path)) {
+    const claude = options.find(isClaudeModel);
+    if (claude) return claude;
+  }
   return options.find(m => m.modelPath === path || path?.includes(m.id));
 };
 
 interface ChatInputProps {
   sessionId?: string;
+  initialModelPath?: string | null;
   onSend: (text: string) => void;
   onStop?: () => void;
   isProcessing?: boolean;
@@ -95,13 +101,15 @@ const isClaudeModel = (m: ModelOption) => isClaudePath(m.modelPath);
 const isPremiumModel = (m: ModelOption) => isPremiumPath(m.modelPath);
 const firstFreeModel = (options: ModelOption[]) => options.find(m => !isPremiumModel(m)) ?? options[0];
 
-export default function ChatInput({ sessionId, onSend, onStop, isProcessing = false, disabled = false, placeholder = 'Ask anything...' }: ChatInputProps) {
+export default function ChatInput({ sessionId, initialModelPath, onSend, onStop, isProcessing = false, disabled = false, placeholder = 'Ask anything...' }: ChatInputProps) {
   const [input, setInput] = useState('');
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const [modelOptions, setModelOptions] = useState<ModelOption[]>(DEFAULT_MODEL_OPTIONS);
   const modelOptionsRef = useRef<ModelOption[]>(DEFAULT_MODEL_OPTIONS);
   const sessionIdRef = useRef<string | undefined>(sessionId);
-  const [selectedModelId, setSelectedModelId] = useState<string>(DEFAULT_MODEL_OPTIONS[0].id);
+  const [selectedModelId, setSelectedModelId] = useState<string>(
+    () => findModelByPath(initialModelPath ?? '', DEFAULT_MODEL_OPTIONS)?.id ?? DEFAULT_MODEL_OPTIONS[0].id,
+  );
   const [modelAnchorEl, setModelAnchorEl] = useState<null | HTMLElement>(null);
   const { quota, refresh: refreshQuota } = useUserQuota();
   // The daily-cap dialog is triggered from two places: (a) a 429 returned
@@ -113,6 +121,7 @@ export default function ChatInput({ sessionId, onSend, onStop, isProcessing = fa
   const setClaudeQuotaExhausted = useAgentStore((s) => s.setClaudeQuotaExhausted);
   const jobsUpgradeRequired = useAgentStore((s) => s.jobsUpgradeRequired);
   const setJobsUpgradeRequired = useAgentStore((s) => s.setJobsUpgradeRequired);
+  const updateSessionModel = useSessionStore((s) => s.updateSessionModel);
   const [awaitingTopUp, setAwaitingTopUp] = useState(false);
   const lastSentRef = useRef<string>('');
 
@@ -163,11 +172,12 @@ export default function ChatInput({ sessionId, onSend, onStop, isProcessing = fa
         if (data?.model) {
           const model = findModelByPath(data.model, modelOptionsRef.current);
           if (model) setSelectedModelId(model.id);
+          updateSessionModel(sessionId, data.model);
         }
       })
       .catch(() => { /* ignore */ });
     return () => { cancelled = true; };
-  }, [sessionId]);
+  }, [sessionId, updateSessionModel]);
 
   const selectedModel = modelOptions.find(m => m.id === selectedModelId) || modelOptions[0];
 
@@ -227,7 +237,10 @@ export default function ChatInput({ sessionId, onSend, onStop, isProcessing = fa
         method: 'POST',
         body: JSON.stringify({ model: model.modelPath }),
       });
-      if (res.ok) setSelectedModelId(model.id);
+      if (res.ok) {
+        setSelectedModelId(model.id);
+        updateSessionModel(sessionId, model.modelPath);
+      }
     } catch { /* ignore */ }
   };
 
@@ -250,6 +263,7 @@ export default function ChatInput({ sessionId, onSend, onStop, isProcessing = fa
       });
       if (res.ok) {
         setSelectedModelId(free.id);
+        updateSessionModel(sessionId, free.modelPath);
         const retryText = lastSentRef.current;
         if (retryText) {
           onSend(retryText);
@@ -258,7 +272,7 @@ export default function ChatInput({ sessionId, onSend, onStop, isProcessing = fa
         }
       }
     } catch { /* ignore */ }
-  }, [sessionId, onSend, setClaudeQuotaExhausted, modelOptions]);
+  }, [sessionId, onSend, setClaudeQuotaExhausted, modelOptions, updateSessionModel]);
 
   const handlePremiumUpgradeClick = useCallback(async () => {
     if (!sessionId) return;

frontend/src/components/Chat/ExpiredBanner.tsx

@@ -18,7 +18,7 @@ interface Props {
 }
 
 export default function ExpiredBanner({ sessionId }: Props) {
-  const { renameSession, deleteSession } = useSessionStore();
+  const { renameSession, deleteSession, updateSessionModel } = useSessionStore();
   const [busy, setBusy] = useState<'catch-up' | 'start-over' | null>(null);
   const [error, setError] = useState<string | null>(null);
 
@@ -50,12 +50,13 @@ export default function ExpiredBanner({ sessionId }: Props) {
 
       useAgentStore.getState().clearSessionState(sessionId);
       renameSession(sessionId, newId);
+      if (data.model) updateSessionModel(newId, data.model);
     } catch (e) {
       logger.warn('Catch-up failed:', e);
       setError("Couldn't catch up — try starting over.");
       setBusy(null);
     }
-  }, [sessionId, renameSession]);
+  }, [sessionId, renameSession, updateSessionModel]);
 
   const handleStartOver = useCallback(() => {
     setBusy('start-over');

frontend/src/components/SessionChat.tsx

@@ -24,7 +24,8 @@ interface SessionChatProps {
 export default function SessionChat({ sessionId, isActive, onSessionDead }: SessionChatProps) {
   const { isConnected, isProcessing, activityStatus, updateSession } = useAgentStore();
   const { updateSessionTitle, sessions } = useSessionStore();
-  const isExpired = sessions.find((s) => s.id === sessionId)?.expired === true;
+  const sessionMeta = sessions.find((s) => s.id === sessionId);
+  const isExpired = sessionMeta?.expired === true;
 
   const { messages, sendMessage, stop, status, undoLastTurn, editAndRegenerate, approveTools } = useAgentChat({
     sessionId,
@@ -112,6 +113,7 @@ export default function SessionChat({ sessionId, isActive, onSessionDead }: Sess
       ) : (
         <ChatInput
           sessionId={sessionId}
+          initialModelPath={sessionMeta?.model}
           onSend={handleSendMessage}
           onStop={handleStop}
           isProcessing={busy}

frontend/src/components/SessionSidebar/SessionSidebar.tsx

@@ -63,7 +63,7 @@ export default function SessionSidebar({ onClose }: SessionSidebarProps) {
         return;
       }
       const data = await response.json();
-      createSession(data.session_id);
+      createSession(data.session_id, data.model);
       setPlan([]);
       clearPanel();
       onClose?.();
@@ -107,7 +107,7 @@ export default function SessionSidebar({ onClose }: SessionSidebarProps) {
         const response = await apiFetch('/api/session', { method: 'POST' });
         if (response.ok) {
           const data = await response.json();
-          createSession(data.session_id);
+          createSession(data.session_id, data.model);
           setPlan([]);
           clearPanel();
         }

frontend/src/components/WelcomeScreen/WelcomeScreen.tsx

@@ -209,7 +209,7 @@ export default function WelcomeScreen() {
         return;
       }
       const data = await response.json();
-      createSession(data.session_id);
+      createSession(data.session_id, data.model);
       setPlan([]);
       clearPanel();
     } catch {

frontend/src/store/sessionStore.ts

@@ -9,11 +9,12 @@ interface SessionStore {
   activeSessionId: string | null;
 
   // Actions
-  createSession: (id: string) => void;
+  createSession: (id: string, model?: string | null) => void;
   deleteSession: (id: string) => void;
   switchSession: (id: string) => void;
   setSessionActive: (id: string, isActive: boolean) => void;
   updateSessionTitle: (id: string, title: string) => void;
+  updateSessionModel: (id: string, model: string | null) => void;
   setNeedsAttention: (id: string, needs: boolean) => void;
   /** Mark a session as expired (backend no longer has it). The UI shows a
    *  recovery banner and disables input. */
@@ -26,6 +27,7 @@ interface SessionStore {
     title?: string | null;
     created_at: string;
     is_active?: boolean;
+    model?: string | null;
     pending_approval?: unknown[] | null;
     auto_approval?: {
       enabled?: boolean;
@@ -52,13 +54,14 @@ export const useSessionStore = create<SessionStore>()(
       sessions: [],
       activeSessionId: null,
 
-      createSession: (id: string) => {
+      createSession: (id: string, model?: string | null) => {
         const newSession: SessionMeta = {
           id,
           title: `Chat ${get().sessions.length + 1}`,
           createdAt: new Date().toISOString(),
           isActive: true,
           needsAttention: false,
+          model: model ?? null,
           autoApprovalEnabled: false,
           autoApprovalCostCapUsd: null,
           autoApprovalEstimatedSpendUsd: 0,
@@ -114,6 +117,7 @@ export const useSessionStore = create<SessionStore>()(
                 ...existing,
                 title: server.title || existing.title,
                 isActive: server.is_active ?? existing.isActive,
+                model: server.model ?? existing.model ?? null,
                 needsAttention: Boolean(server.pending_approval?.length) || existing.needsAttention,
                 expired: false,
                 ...(auto
@@ -136,6 +140,7 @@ export const useSessionStore = create<SessionStore>()(
               createdAt: server.created_at || new Date().toISOString(),
               isActive: server.is_active ?? true,
               needsAttention: Boolean(server.pending_approval?.length),
+              model: server.model ?? null,
               expired: false,
               autoApprovalEnabled: Boolean(server.auto_approval?.enabled),
               autoApprovalCostCapUsd: server.auto_approval?.cost_cap_usd ?? null,
@@ -205,6 +210,14 @@ export const useSessionStore = create<SessionStore>()(
         }));
       },
 
+      updateSessionModel: (id: string, model: string | null) => {
+        set((state) => ({
+          sessions: state.sessions.map((s) =>
+            s.id === id ? { ...s, model } : s
+          ),
+        }));
+      },
+
       setNeedsAttention: (id: string, needs: boolean) => {
         set((state) => ({
           sessions: state.sessions.map((s) =>

frontend/src/types/agent.ts

@@ -16,6 +16,7 @@ export interface SessionMeta {
   createdAt: string;
   isActive: boolean;
   needsAttention: boolean;
+  model?: string | null;
   /** True when the backend no longer recognizes this session id (e.g.
    *  after a backend restart). The UI shows a recovery banner and
    *  disables input until the user chooses to restore-with-summary or

tests/unit/test_agent_model_gating.py

@@ -33,7 +33,11 @@ async def test_gated_model_gate_rejects_gpt55_for_non_hf_user(monkeypatch):
     async def fake_require_hf_org_member(_request):
         return False
 
-    monkeypatch.setattr(agent, "require_huggingface_org_member", fake_require_hf_org_member)
+    monkeypatch.setattr(
+        agent,
+        "require_huggingface_org_member",
+        fake_require_hf_org_member,
+    )
 
     with pytest.raises(HTTPException) as exc_info:
         await agent._require_hf_for_gated_model(None, "openai/gpt-5.5")
@@ -42,6 +46,83 @@ async def test_gated_model_gate_rejects_gpt55_for_non_hf_user(monkeypatch):
     assert exc_info.value.detail["error"] == "premium_model_restricted"
 
 
+@pytest.mark.asyncio
+async def test_default_gated_session_falls_back_to_free_model_for_non_hf_user(
+    monkeypatch,
+):
+    async def fake_require_hf_org_member(_request):
+        return False
+
+    monkeypatch.setattr(
+        agent,
+        "require_huggingface_org_member",
+        fake_require_hf_org_member,
+    )
+    monkeypatch.setattr(
+        agent.session_manager.config,
+        "model_name",
+        agent.DEFAULT_CLAUDE_MODEL_ID,
+    )
+
+    model = await agent._model_override_for_new_session(None, None)
+
+    assert model == agent.DEFAULT_FREE_MODEL_ID
+
+
+@pytest.mark.asyncio
+async def test_default_gated_session_stays_default_for_hf_user(monkeypatch):
+    async def fake_require_hf_org_member(_request):
+        return True
+
+    monkeypatch.setattr(
+        agent,
+        "require_huggingface_org_member",
+        fake_require_hf_org_member,
+    )
+    monkeypatch.setattr(
+        agent.session_manager.config,
+        "model_name",
+        agent.DEFAULT_CLAUDE_MODEL_ID,
+    )
+
+    model = await agent._model_override_for_new_session(None, None)
+
+    assert model is None
+
+
+@pytest.mark.asyncio
+async def test_explicit_gated_session_allowed_for_hf_user(monkeypatch):
+    async def fake_require_hf_org_member(_request):
+        return True
+
+    monkeypatch.setattr(
+        agent,
+        "require_huggingface_org_member",
+        fake_require_hf_org_member,
+    )
+
+    model = await agent._model_override_for_new_session(
+        None,
+        agent.DEFAULT_CLAUDE_MODEL_ID,
+    )
+
+    assert model == agent.DEFAULT_CLAUDE_MODEL_ID
+
+
+@pytest.mark.asyncio
+async def test_explicit_gated_session_request_still_rejects_non_hf_user(monkeypatch):
+    async def fake_require_hf_org_member(_request):
+        return False
+
+    monkeypatch.setattr(agent, "require_huggingface_org_member", fake_require_hf_org_member)
+
+    with pytest.raises(HTTPException) as exc_info:
+        await agent._model_override_for_new_session(None, agent.DEFAULT_CLAUDE_MODEL_ID)
+
+    assert exc_info.value.status_code == 403
+    assert exc_info.value.detail["error"] == "premium_model_restricted"
+
+
 @pytest.mark.asyncio
 async def test_ungated_models_skip_hf_membership_check(monkeypatch):
     async def fail_if_called(_request):