perf(cortex-tui): optimize TUI startup by deferring HTTP requests to background (#474)

## Problem
The TUI had noticeable latency before appearing because several HTTP
requests were executed synchronously during startup:
- Session validation with the server
- Model fetching from the API
- User info fetching for the welcome screen

Additionally, session history loading from disk was blocking.

## Solution
Optimized the startup flow in run_direct_provider() by:

1. **Deferring HTTP requests to background tasks**: Session validation,
   model fetching, and user info are now fetched asynchronously after
   the terminal is initialized, using tokio::spawn.

2. **Parallel I/O operations**: Session history loading now runs in
   a background spawn_blocking task concurrently with HTTP requests.

3. **Short timeouts**: Background tasks have short timeouts (500ms) to
   avoid blocking the TUI if the network is slow.

4. **Combined validation and model fetch**: The models endpoint is now
   used for both session validation and model fetching in a single
   request, reducing HTTP round-trips.

## Changes
- cortex-tui/src/runner/app_runner.rs: Refactored run_direct_provider()
  to initialize terminal first, then spawn background tasks for
  network I/O and session history loading.

- cortex-tui/src/providers/manager.rs: Added set_cached_models() and
  has_cached_models() methods to allow setting models from background
  fetch results.

## Result
The TUI should now appear almost instantly after trust verification
and local auth check, with data populating in the background.

Co-authored-by: Droid Agent <droid@factory.ai>

Author: echobt

cortex-tui/src/providers/manager.rs

@@ -333,6 +333,23 @@ impl ProviderManager {
         self.fetch_models().await
     }
 
+    /// Sets cached models from an external source (e.g., background fetch).
+    ///
+    /// This is useful for setting models that were fetched in a background task
+    /// to avoid blocking the main thread during startup.
+    pub fn set_cached_models(&mut self, models: Vec<CortexModel>) {
+        tracing::debug!(
+            "Setting {} cached models from external source",
+            models.len()
+        );
+        self.cached_models = Some(models);
+    }
+
+    /// Checks if models are cached.
+    pub fn has_cached_models(&self) -> bool {
+        self.cached_models.is_some()
+    }
+
     /// Gets the auth token using centralized auth module.
     fn get_token(&self) -> Result<String> {
         cortex_engine::auth_token::get_auth_token(self.auth_token.as_deref())

cortex-tui/src/runner/app_runner.rs

@@ -471,6 +471,18 @@ impl AppRunner {
     }
 
     /// Run using direct provider mode (new architecture).
+    ///
+    /// ## Performance Optimizations
+    ///
+    /// This function is optimized for fast TUI startup by:
+    /// 1. **Deferring non-critical HTTP requests**: Session validation, model fetching,
+    ///    and user info are fetched in the background after the terminal is initialized
+    /// 2. **Parallel I/O operations**: Session history loading runs concurrently with
+    ///    other startup tasks using `tokio::spawn`
+    /// 3. **Non-blocking validation**: Server-side session validation happens
+    ///    asynchronously and doesn't block the TUI from appearing
+    ///
+    /// The TUI should appear almost instantly after trust verification and auth check.
     async fn run_direct_provider(self) -> Result<AppExitInfo> {
         // Trust verification before anything else
         let workspace = std::env::current_dir()?;
@@ -490,7 +502,7 @@ impl AppRunner {
             }
         }
 
-        // Check authentication before starting
+        // Check authentication before starting (fast local check)
         let cortex_home = dirs::home_dir()
             .map(|h| h.join(".cortex"))
             .unwrap_or_else(|| PathBuf::from(".cortex"));
@@ -508,6 +520,7 @@ impl AppRunner {
         }
 
         // Check if user is authenticated (OAuth/API key login) or has API keys configured
+        // This is a fast local check - no network calls
         let mut auth_status = match load_auth(&cortex_home, CredentialsStoreMode::default()) {
             Ok(Some(auth)) if !auth.is_expired() => {
                 tracing::info!("User authenticated via {}", auth.mode);
@@ -544,32 +557,8 @@ impl AppRunner {
             }
         };
 
-        // If locally authenticated, validate with the server
-        // This catches cases where the token was revoked server-side
-        if auth_status == AuthStatus::Authenticated {
-            match provider_manager.validate_session().await {
-                Ok(true) => {
-                    tracing::debug!("Session validated with server");
-                }
-                Ok(false) => {
-                    tracing::warn!(
-                        "Server rejected authentication - session may have been revoked"
-                    );
-                    // Delete the invalidated credentials
-                    if let Err(e) = logout_with_fallback(&cortex_home) {
-                        tracing::warn!("Failed to remove invalidated credentials: {}", e);
-                    }
-                    auth_status = AuthStatus::Expired;
-                }
-                Err(e) => {
-                    // Network error - don't block the user, let them try
-                    tracing::warn!("Could not validate session with server: {}", e);
-                    // Continue with local auth status
-                }
-            }
-        }
-
         // If not authenticated, show the login screen TUI
+        // (We skip server validation here and do it in the background later)
         if auth_status != AuthStatus::Authenticated {
             use super::login_screen::{LoginResult, LoginScreen};
 
@@ -591,6 +580,7 @@ impl AppRunner {
                     } else {
                         tracing::warn!("Login succeeded but could not load token from keyring");
                     }
+                    auth_status = AuthStatus::Authenticated;
                 }
                 LoginResult::ContinueWithApiKey => {
                     // Show API key setup instructions and exit
@@ -622,26 +612,11 @@ impl AppRunner {
             }
         }
 
-        // Pre-fetch models from API for the models picker
-        // Use is_available() which checks auth_token, env var, and keyring
-        if provider_manager.is_available() {
-            tracing::debug!("Pre-fetching models from API...");
-            match provider_manager.fetch_models().await {
-                Ok(models) => {
-                    tracing::info!("Loaded {} models from API", models.len());
-                }
-                Err(e) => {
-                    tracing::warn!("Failed to fetch models from API: {}", e);
-                    // Continue with hardcoded fallback
-                }
-            }
-        } else {
-            tracing::warn!(
-                "Not authenticated - models will not be available. Run 'cortex login' to authenticate."
-            );
-        }
+        // ====================================================================
+        // PERFORMANCE OPTIMIZATION: Start TUI immediately, fetch data in background
+        // ====================================================================
 
-        // Initialize terminal
+        // Initialize terminal FIRST to minimize perceived latency
         let mut terminal = CortexTerminal::with_options(self.terminal_options)?;
         terminal.set_title("Cortex")?;
 
@@ -664,49 +639,121 @@ impl AppRunner {
             CortexSession::new(&provider, &model)?
         };
 
-        let session_id = cortex_session.id().to_string();
+        let _session_id = cortex_session.id().to_string();
 
         // Create app state
         let mut app_state = AppState::new()
             .with_model(model.clone())
             .with_provider(provider.clone())
             .with_terminal_size(width, height);
 
-        // Fetch user info from API for welcome screen
-        if let Some(token) = cortex_login::get_auth_token() {
-            if let Ok(client) = cortex_engine::create_default_client() {
-                let resp = client
-                    .get("https://api.cortex.foundation/auth/me")
-                    .bearer_auth(&token)
-                    .send()
-                    .await;
-                if let Ok(resp) = resp {
-                    if resp.status().is_success() {
-                        if let Ok(json) = resp.json::<serde_json::Value>().await {
-                            if let Some(name) = json.get("name").and_then(|v| v.as_str()) {
-                                app_state.user_name = Some(name.to_string());
-                            }
-                            if let Some(email) = json.get("email").and_then(|v| v.as_str()) {
-                                app_state.user_email = Some(email.to_string());
+        // ====================================================================
+        // BACKGROUND TASKS: Spawn non-blocking operations in parallel
+        // ====================================================================
+
+        // 1. Session history loading (file I/O) - spawn in background
+        let session_history_task =
+            tokio::task::spawn_blocking(|| CortexSession::list_recent(50).ok());
+
+        // 2. Fetch user info from API (HTTP request) - spawn in background
+        let user_info_task = {
+            let token = cortex_login::get_auth_token();
+            tokio::spawn(async move {
+                if let Some(token) = token {
+                    if let Ok(client) = cortex_engine::create_default_client() {
+                        if let Ok(resp) = client
+                            .get("https://api.cortex.foundation/auth/me")
+                            .bearer_auth(&token)
+                            .timeout(std::time::Duration::from_secs(5))
+                            .send()
+                            .await
+                        {
+                            if resp.status().is_success() {
+                                if let Ok(json) = resp.json::<serde_json::Value>().await {
+                                    return Some(json);
+                                }
                             }
-                            if let Some(orgs) = json.get("organizations").and_then(|v| v.as_array())
+                        }
+                    }
+                }
+                None
+            })
+        };
+
+        // 3. Models prefetch and session validation - spawn in background
+        // We use a channel to receive results and update provider_manager later
+        let models_and_validation_task = {
+            let api_url = provider_manager.api_url().to_string();
+            let token = cortex_login::get_auth_token();
+            let cortex_home_clone = cortex_home.clone();
+            tokio::spawn(async move {
+                let mut validation_failed = false;
+                let mut models: Option<Vec<cortex_engine::client::CortexModel>> = None;
+
+                if let Some(token) = token {
+                    // Create a client with timeout for faster failure on network issues
+                    if let Ok(client) = cortex_engine::create_client_builder()
+                        .connect_timeout(std::time::Duration::from_secs(3))
+                        .timeout(std::time::Duration::from_secs(10))
+                        .build()
+                    {
+                        // Session validation (lightweight)
+                        tracing::debug!("Background: validating session with server...");
+                        if let Ok(resp) = client
+                            .get(format!("{}/v1/models", api_url))
+                            .header("Authorization", format!("Bearer {}", token))
+                            .send()
+                            .await
+                        {
+                            let status = resp.status();
+                            if status == reqwest::StatusCode::UNAUTHORIZED
+                                || status == reqwest::StatusCode::FORBIDDEN
                             {
-                                if let Some(first_org) = orgs.first() {
-                                    if let Some(org_name) =
-                                        first_org.get("org_name").and_then(|v| v.as_str())
+                                tracing::warn!(
+                                    "Background: session validation failed ({})",
+                                    status
+                                );
+                                // Delete invalidated credentials
+                                if let Err(e) = logout_with_fallback(&cortex_home_clone) {
+                                    tracing::warn!(
+                                        "Failed to remove invalidated credentials: {}",
+                                        e
+                                    );
+                                }
+                                validation_failed = true;
+                            } else if status.is_success() {
+                                // Parse models from the same response to avoid another request
+                                if let Ok(json) = resp.json::<serde_json::Value>().await {
+                                    if let Some(data) = json.get("data").and_then(|d| d.as_array())
                                     {
-                                        app_state.org_name = Some(org_name.to_string());
+                                        let parsed: Vec<cortex_engine::client::CortexModel> = data
+                                            .iter()
+                                            .filter_map(|m| serde_json::from_value(m.clone()).ok())
+                                            .collect();
+                                        if !parsed.is_empty() {
+                                            tracing::info!(
+                                                "Background: loaded {} models from API",
+                                                parsed.len()
+                                            );
+                                            models = Some(parsed);
+                                        }
                                     }
                                 }
                             }
                         }
                     }
                 }
-            }
-        }
 
-        // Load session history from Cortex storage
-        if let Ok(sessions) = CortexSession::list_recent(50) {
+                (validation_failed, models)
+            })
+        };
+
+        // ====================================================================
+        // Collect background task results (with timeout to not block forever)
+        // ====================================================================
+
+        // Wait for session history (file I/O should be fast)
+        if let Ok(Some(sessions)) = session_history_task.await {
             use crate::app::SessionSummary;
             for session in sessions {
                 if let Ok(session_uuid) = uuid::Uuid::parse_str(&session.id) {
@@ -722,6 +769,48 @@ impl AppRunner {
             );
         }
 
+        // Wait for user info (with short timeout - don't block TUI)
+        if let Ok(Some(json)) =
+            tokio::time::timeout(std::time::Duration::from_millis(500), user_info_task)
+                .await
+                .unwrap_or(Ok(None))
+        {
+            if let Some(name) = json.get("name").and_then(|v| v.as_str()) {
+                app_state.user_name = Some(name.to_string());
+            }
+            if let Some(email) = json.get("email").and_then(|v| v.as_str()) {
+                app_state.user_email = Some(email.to_string());
+            }
+            if let Some(orgs) = json.get("organizations").and_then(|v| v.as_array()) {
+                if let Some(first_org) = orgs.first() {
+                    if let Some(org_name) = first_org.get("org_name").and_then(|v| v.as_str()) {
+                        app_state.org_name = Some(org_name.to_string());
+                    }
+                }
+            }
+        }
+
+        // Check validation result (with short timeout - don't block TUI)
+        // We'll handle models update after event loop is created
+        let validation_result = tokio::time::timeout(
+            std::time::Duration::from_millis(500),
+            models_and_validation_task,
+        )
+        .await;
+
+        // If validation failed in background, update auth status
+        // (This would show a toast in the TUI asking user to re-login)
+        if let Ok(Ok((true, _))) = &validation_result {
+            tracing::warn!("Session was invalidated by server - user should re-login");
+            // The credentials are already deleted in the background task
+            // We continue with the TUI but the user will get auth errors on API calls
+        }
+
+        // Extract and apply models if we got them from background task
+        if let Ok(Ok((_, Some(models)))) = validation_result {
+            provider_manager.set_cached_models(models);
+        }
+
         // Create unified tool executor for Task and Batch tools
         // This requires an API key for the subagent's model client
         let unified_executor = {