Merge PR #37: Add Gemini OAuth and Messages Compat Support

backend/internal/repository/geminicli_codeassist_client.go

+package repository
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/geminicli"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/imroc/req/v3"
+)
+
+type geminiCliCodeAssistClient struct {
+	baseURL string
+}
+
+func NewGeminiCliCodeAssistClient() service.GeminiCliCodeAssistClient {
+	return &geminiCliCodeAssistClient{baseURL: geminicli.GeminiCliBaseURL}
+}
+
+func (c *geminiCliCodeAssistClient) LoadCodeAssist(ctx context.Context, accessToken, proxyURL string, reqBody *geminicli.LoadCodeAssistRequest) (*geminicli.LoadCodeAssistResponse, error) {
+	if reqBody == nil {
+		reqBody = defaultLoadCodeAssistRequest()
+	}
+
+	var out geminicli.LoadCodeAssistResponse
+	resp, err := createGeminiCliReqClient(proxyURL).R().
+		SetContext(ctx).
+		SetHeader("Authorization", "Bearer "+accessToken).
+		SetHeader("Content-Type", "application/json").
+		SetHeader("User-Agent", geminicli.GeminiCLIUserAgent).
+		SetBody(reqBody).
+		SetSuccessResult(&out).
+		Post(c.baseURL + "/v1internal:loadCodeAssist")
+	if err != nil {
+		fmt.Printf("[CodeAssist] LoadCodeAssist request error: %v\n", err)
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	if !resp.IsSuccessState() {
+		body := geminicli.SanitizeBodyForLogs(resp.String())
+		fmt.Printf("[CodeAssist] LoadCodeAssist failed: status %d, body: %s\n", resp.StatusCode, body)
+		return nil, fmt.Errorf("loadCodeAssist failed: status %d, body: %s", resp.StatusCode, body)
+	}
+	fmt.Printf("[CodeAssist] LoadCodeAssist success: status %d, response: %+v\n", resp.StatusCode, out)
+	return &out, nil
+}
+
+func (c *geminiCliCodeAssistClient) OnboardUser(ctx context.Context, accessToken, proxyURL string, reqBody *geminicli.OnboardUserRequest) (*geminicli.OnboardUserResponse, error) {
+	if reqBody == nil {
+		reqBody = defaultOnboardUserRequest()
+	}
+
+	fmt.Printf("[CodeAssist] OnboardUser request body: %+v\n", reqBody)
+
+	var out geminicli.OnboardUserResponse
+	resp, err := createGeminiCliReqClient(proxyURL).R().
+		SetContext(ctx).
+		SetHeader("Authorization", "Bearer "+accessToken).
+		SetHeader("Content-Type", "application/json").
+		SetHeader("User-Agent", geminicli.GeminiCLIUserAgent).
+		SetBody(reqBody).
+		SetSuccessResult(&out).
+		Post(c.baseURL + "/v1internal:onboardUser")
+	if err != nil {
+		fmt.Printf("[CodeAssist] OnboardUser request error: %v\n", err)
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	if !resp.IsSuccessState() {
+		body := geminicli.SanitizeBodyForLogs(resp.String())
+		fmt.Printf("[CodeAssist] OnboardUser failed: status %d, body: %s\n", resp.StatusCode, body)
+		return nil, fmt.Errorf("onboardUser failed: status %d, body: %s", resp.StatusCode, body)
+	}
+	fmt.Printf("[CodeAssist] OnboardUser success: status %d, response: %+v\n", resp.StatusCode, out)
+	return &out, nil
+}
+
+func createGeminiCliReqClient(proxyURL string) *req.Client {
+	client := req.C().SetTimeout(30 * time.Second)
+	if proxyURL != "" {
+		client.SetProxyURL(proxyURL)
+	}
+	return client
+}
+
+func defaultLoadCodeAssistRequest() *geminicli.LoadCodeAssistRequest {
+	return &geminicli.LoadCodeAssistRequest{
+		Metadata: geminicli.LoadCodeAssistMetadata{
+			IDEType:    "ANTIGRAVITY",
+			Platform:   "PLATFORM_UNSPECIFIED",
+			PluginType: "GEMINI",
+		},
+	}
+}
+
+func defaultOnboardUserRequest() *geminicli.OnboardUserRequest {
+	return &geminicli.OnboardUserRequest{
+		TierID: "LEGACY",
+		Metadata: geminicli.LoadCodeAssistMetadata{
+			IDEType:    "ANTIGRAVITY",
+			Platform:   "PLATFORM_UNSPECIFIED",
+			PluginType: "GEMINI",
+		},
+	}
+}

backend/internal/repository/pricing_service_test.go

@@ -120,10 +120,9 @@ func (s *PricingServiceSuite) TestFetchHashText_WhitespaceOnly() {
 
 func (s *PricingServiceSuite) TestFetchPricingJSON_ContextCancel() {
 	started := make(chan struct{})
-	block := make(chan struct{})
 	s.setupServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		close(started)
-		<-block
+		<-r.Context().Done()
 	}))
 
 	ctx, cancel := context.WithCancel(s.ctx)
@@ -136,7 +135,6 @@ func (s *PricingServiceSuite) TestFetchPricingJSON_ContextCancel() {
 
 	<-started
 	cancel()
-	close(block)
 
 	err := <-done
 	require.Error(s.T(), err)

backend/internal/repository/wire.go

@@ -25,6 +25,7 @@ var ProviderSet = wire.NewSet(
 	NewIdentityCache,
 	NewRedeemCache,
 	NewUpdateCache,
+	NewGeminiTokenCache,
 
 	// HTTP service ports (DI Strategy A: return interface directly)
 	NewTurnstileVerifier,
@@ -35,4 +36,6 @@ var ProviderSet = wire.NewSet(
 	NewClaudeOAuthClient,
 	NewHTTPUpstream,
 	NewOpenAIOAuthClient,
+	NewGeminiOAuthClient,
+	NewGeminiCliCodeAssistClient,
 )

backend/internal/server/http.go

@@ -7,6 +7,7 @@ import (
 	"github.com/Wei-Shaw/sub2api/internal/config"
 	"github.com/Wei-Shaw/sub2api/internal/handler"
 	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/wire"
@@ -25,6 +26,8 @@ func ProvideRouter(
 	jwtAuth middleware2.JWTAuthMiddleware,
 	adminAuth middleware2.AdminAuthMiddleware,
 	apiKeyAuth middleware2.ApiKeyAuthMiddleware,
+	apiKeyService *service.ApiKeyService,
+	subscriptionService *service.SubscriptionService,
 ) *gin.Engine {
 	if cfg.Server.Mode == "release" {
 		gin.SetMode(gin.ReleaseMode)
@@ -33,7 +36,7 @@ func ProvideRouter(
 	r := gin.New()
 	r.Use(middleware2.Recovery())
 
-	return SetupRouter(r, handlers, jwtAuth, adminAuth, apiKeyAuth)
+	return SetupRouter(r, handlers, jwtAuth, adminAuth, apiKeyAuth, apiKeyService, subscriptionService)
 }
 
 // ProvideHTTPServer 提供 HTTP 服务器

backend/internal/server/middleware/api_key_auth.go

@@ -35,9 +35,24 @@ func apiKeyAuthWithSubscription(apiKeyService *service.ApiKeyService, subscripti
 			apiKeyString = c.GetHeader("x-api-key")
 		}
 
-		// 如果两个header都没有API key
+		// 如果x-api-key header中没有，尝试从x-goog-api-key header中提取（Gemini CLI兼容）
 		if apiKeyString == "" {
-			AbortWithError(c, 401, "API_KEY_REQUIRED", "API key is required in Authorization header (Bearer scheme) or x-api-key header")
+			apiKeyString = c.GetHeader("x-goog-api-key")
+		}
+
+		// 如果header中没有，尝试从query参数中提取（Google API key风格）
+		if apiKeyString == "" {
+			apiKeyString = c.Query("key")
+		}
+
+		// 兼容常见别名
+		if apiKeyString == "" {
+			apiKeyString = c.Query("api_key")
+		}
+
+		// 如果所有header都没有API key
+		if apiKeyString == "" {
+			AbortWithError(c, 401, "API_KEY_REQUIRED", "API key is required in Authorization header (Bearer scheme), x-api-key header, x-goog-api-key header, or key/api_key query parameter")
 			return
 		}
 

backend/internal/server/middleware/api_key_auth_google.go

+package middleware
+
+import (
+	"errors"
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/googleapi"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+// ApiKeyAuthGoogle is a Google-style error wrapper for API key auth.
+func ApiKeyAuthGoogle(apiKeyService *service.ApiKeyService) gin.HandlerFunc {
+	return ApiKeyAuthWithSubscriptionGoogle(apiKeyService, nil)
+}
+
+// ApiKeyAuthWithSubscriptionGoogle behaves like ApiKeyAuthWithSubscription but returns Google-style errors:
+// {"error":{"code":401,"message":"...","status":"UNAUTHENTICATED"}}
+//
+// It is intended for Gemini native endpoints (/v1beta) to match Gemini SDK expectations.
+func ApiKeyAuthWithSubscriptionGoogle(apiKeyService *service.ApiKeyService, subscriptionService *service.SubscriptionService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		apiKeyString := extractAPIKeyFromRequest(c)
+		if apiKeyString == "" {
+			abortWithGoogleError(c, 401, "API key is required")
+			return
+		}
+
+		apiKey, err := apiKeyService.GetByKey(c.Request.Context(), apiKeyString)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				abortWithGoogleError(c, 401, "Invalid API key")
+				return
+			}
+			abortWithGoogleError(c, 500, "Failed to validate API key")
+			return
+		}
+
+		if !apiKey.IsActive() {
+			abortWithGoogleError(c, 401, "API key is disabled")
+			return
+		}
+		if apiKey.User == nil {
+			abortWithGoogleError(c, 401, "User associated with API key not found")
+			return
+		}
+		if !apiKey.User.IsActive() {
+			abortWithGoogleError(c, 401, "User account is not active")
+			return
+		}
+
+		isSubscriptionType := apiKey.Group != nil && apiKey.Group.IsSubscriptionType()
+		if isSubscriptionType && subscriptionService != nil {
+			subscription, err := subscriptionService.GetActiveSubscription(
+				c.Request.Context(),
+				apiKey.User.ID,
+				apiKey.Group.ID,
+			)
+			if err != nil {
+				abortWithGoogleError(c, 403, "No active subscription found for this group")
+				return
+			}
+			if err := subscriptionService.ValidateSubscription(c.Request.Context(), subscription); err != nil {
+				abortWithGoogleError(c, 403, err.Error())
+				return
+			}
+			_ = subscriptionService.CheckAndActivateWindow(c.Request.Context(), subscription)
+			_ = subscriptionService.CheckAndResetWindows(c.Request.Context(), subscription)
+			if err := subscriptionService.CheckUsageLimits(c.Request.Context(), subscription, apiKey.Group, 0); err != nil {
+				abortWithGoogleError(c, 429, err.Error())
+				return
+			}
+			c.Set(string(ContextKeySubscription), subscription)
+		} else {
+			if apiKey.User.Balance <= 0 {
+				abortWithGoogleError(c, 403, "Insufficient account balance")
+				return
+			}
+		}
+
+		c.Set(string(ContextKeyApiKey), apiKey)
+		c.Set(string(ContextKeyUser), apiKey.User)
+		c.Next()
+	}
+}
+
+func extractAPIKeyFromRequest(c *gin.Context) string {
+	authHeader := c.GetHeader("Authorization")
+	if authHeader != "" {
+		parts := strings.SplitN(authHeader, " ", 2)
+		if len(parts) == 2 && parts[0] == "Bearer" && strings.TrimSpace(parts[1]) != "" {
+			return strings.TrimSpace(parts[1])
+		}
+	}
+	if v := strings.TrimSpace(c.GetHeader("x-api-key")); v != "" {
+		return v
+	}
+	if v := strings.TrimSpace(c.GetHeader("x-goog-api-key")); v != "" {
+		return v
+	}
+	if v := strings.TrimSpace(c.Query("key")); v != "" {
+		return v
+	}
+	if v := strings.TrimSpace(c.Query("api_key")); v != "" {
+		return v
+	}
+	return ""
+}
+
+func abortWithGoogleError(c *gin.Context, status int, message string) {
+	c.JSON(status, gin.H{
+		"error": gin.H{
+			"code":    status,
+			"message": message,
+			"status":  googleapi.HTTPStatusToGoogleStatus(status),
+		},
+	})
+	c.Abort()
+}

backend/internal/server/router.go

@@ -4,6 +4,7 @@ import (
 	"github.com/Wei-Shaw/sub2api/internal/handler"
 	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
 	"github.com/Wei-Shaw/sub2api/internal/server/routes"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 	"github.com/Wei-Shaw/sub2api/internal/web"
 
 	"github.com/gin-gonic/gin"
@@ -16,6 +17,8 @@ func SetupRouter(
 	jwtAuth middleware2.JWTAuthMiddleware,
 	adminAuth middleware2.AdminAuthMiddleware,
 	apiKeyAuth middleware2.ApiKeyAuthMiddleware,
+	apiKeyService *service.ApiKeyService,
+	subscriptionService *service.SubscriptionService,
 ) *gin.Engine {
 	// 应用中间件
 	r.Use(middleware2.Logger())
@@ -27,7 +30,7 @@ func SetupRouter(
 	}
 
 	// 注册路由
-	registerRoutes(r, handlers, jwtAuth, adminAuth, apiKeyAuth)
+	registerRoutes(r, handlers, jwtAuth, adminAuth, apiKeyAuth, apiKeyService, subscriptionService)
 
 	return r
 }
@@ -39,6 +42,8 @@ func registerRoutes(
 	jwtAuth middleware2.JWTAuthMiddleware,
 	adminAuth middleware2.AdminAuthMiddleware,
 	apiKeyAuth middleware2.ApiKeyAuthMiddleware,
+	apiKeyService *service.ApiKeyService,
+	subscriptionService *service.SubscriptionService,
 ) {
 	// 通用路由（健康检查、状态等）
 	routes.RegisterCommonRoutes(r)
@@ -50,5 +55,5 @@ func registerRoutes(
 	routes.RegisterAuthRoutes(v1, h, jwtAuth)
 	routes.RegisterUserRoutes(v1, h, jwtAuth)
 	routes.RegisterAdminRoutes(v1, h, adminAuth)
-	routes.RegisterGatewayRoutes(r, h, apiKeyAuth)
+	routes.RegisterGatewayRoutes(r, h, apiKeyAuth, apiKeyService, subscriptionService)
 }

backend/internal/server/routes/admin.go

@@ -31,6 +31,9 @@ func RegisterAdminRoutes(
 		// OpenAI OAuth
 		registerOpenAIOAuthRoutes(admin, h)
 
+		// Gemini OAuth
+		registerGeminiOAuthRoutes(admin, h)
+
 		// 代理管理
 		registerProxyRoutes(admin, h)
 
@@ -136,6 +139,15 @@ func registerOpenAIOAuthRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
 	}
 }
 
+func registerGeminiOAuthRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	gemini := admin.Group("/gemini")
+	{
+		gemini.POST("/oauth/auth-url", h.Admin.GeminiOAuth.GenerateAuthURL)
+		gemini.POST("/oauth/exchange-code", h.Admin.GeminiOAuth.ExchangeCode)
+		gemini.GET("/oauth/capabilities", h.Admin.GeminiOAuth.GetCapabilities)
+	}
+}
+
 func registerProxyRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
 	proxies := admin.Group("/proxies")
 	{

backend/internal/server/routes/gateway.go

@@ -3,15 +3,18 @@ package routes
 import (
 	"github.com/Wei-Shaw/sub2api/internal/handler"
 	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
 
-// RegisterGatewayRoutes 注册 API 网关路由（Claude/OpenAI 兼容）
+// RegisterGatewayRoutes 注册 API 网关路由（Claude/OpenAI/Gemini 兼容）
 func RegisterGatewayRoutes(
 	r *gin.Engine,
 	h *handler.Handlers,
 	apiKeyAuth middleware.ApiKeyAuthMiddleware,
+	apiKeyService *service.ApiKeyService,
+	subscriptionService *service.SubscriptionService,
 ) {
 	// API网关（Claude API兼容）
 	gateway := r.Group("/v1")
@@ -25,6 +28,16 @@ func RegisterGatewayRoutes(
 		gateway.POST("/responses", h.OpenAIGateway.Responses)
 	}
 
+	// Gemini 原生 API 兼容层（Gemini SDK/CLI 直连）
+	gemini := r.Group("/v1beta")
+	gemini.Use(middleware.ApiKeyAuthWithSubscriptionGoogle(apiKeyService, subscriptionService))
+	{
+		gemini.GET("/models", h.Gateway.GeminiV1BetaListModels)
+		gemini.GET("/models/:model", h.Gateway.GeminiV1BetaGetModel)
+		// Gin treats ":" as a param marker, but Gemini uses "{model}:{action}" in the same segment.
+		gemini.POST("/models/*modelAction", h.Gateway.GeminiV1BetaModels)
+	}
+
 	// OpenAI Responses API（不带v1前缀的别名）
 	r.POST("/responses", gin.HandlerFunc(apiKeyAuth), h.OpenAIGateway.Responses)
 }

backend/internal/service/account.go

@@ -70,6 +70,10 @@ func (a *Account) IsOAuth() bool {
 	return a.Type == AccountTypeOAuth || a.Type == AccountTypeSetupToken
 }
 
+func (a *Account) IsGemini() bool {
+	return a.Platform == PlatformGemini
+}
+
 func (a *Account) CanGetUsage() bool {
 	return a.Type == AccountTypeOAuth
 }

backend/internal/service/account_test_service.go

@@ -3,6 +3,7 @@ package service
 import (
 	"bufio"
 	"bytes"
+	"context"
 	"crypto/rand"
 	"encoding/hex"
 	"encoding/json"
@@ -16,6 +17,7 @@ import (
 	"time"
 
 	"github.com/Wei-Shaw/sub2api/internal/pkg/claude"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/geminicli"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
@@ -42,19 +44,27 @@ type TestEvent struct {
 
 // AccountTestService handles account testing operations
 type AccountTestService struct {
-	accountRepo        AccountRepository
-	oauthService       *OAuthService
-	openaiOAuthService *OpenAIOAuthService
-	httpUpstream       HTTPUpstream
+	accountRepo         AccountRepository
+	oauthService        *OAuthService
+	openaiOAuthService  *OpenAIOAuthService
+	geminiTokenProvider *GeminiTokenProvider
+	httpUpstream        HTTPUpstream
 }
 
 // NewAccountTestService creates a new AccountTestService
-func NewAccountTestService(accountRepo AccountRepository, oauthService *OAuthService, openaiOAuthService *OpenAIOAuthService, httpUpstream HTTPUpstream) *AccountTestService {
+func NewAccountTestService(
+	accountRepo AccountRepository,
+	oauthService *OAuthService,
+	openaiOAuthService *OpenAIOAuthService,
+	geminiTokenProvider *GeminiTokenProvider,
+	httpUpstream HTTPUpstream,
+) *AccountTestService {
 	return &AccountTestService{
-		accountRepo:        accountRepo,
-		oauthService:       oauthService,
-		openaiOAuthService: openaiOAuthService,
-		httpUpstream:       httpUpstream,
+		accountRepo:         accountRepo,
+		oauthService:        oauthService,
+		openaiOAuthService:  openaiOAuthService,
+		geminiTokenProvider: geminiTokenProvider,
+		httpUpstream:        httpUpstream,
 	}
 }
 
@@ -127,6 +137,10 @@ func (s *AccountTestService) TestAccountConnection(c *gin.Context, accountID int
 		return s.testOpenAIAccountConnection(c, account, modelID)
 	}
 
+	if account.IsGemini() {
+		return s.testGeminiAccountConnection(c, account, modelID)
+	}
+
 	return s.testClaudeAccountConnection(c, account, modelID)
 }
 
@@ -372,6 +386,252 @@ func (s *AccountTestService) testOpenAIAccountConnection(c *gin.Context, account
 	return s.processOpenAIStream(c, resp.Body)
 }
 
+// testGeminiAccountConnection tests a Gemini account's connection
+func (s *AccountTestService) testGeminiAccountConnection(c *gin.Context, account *Account, modelID string) error {
+	ctx := c.Request.Context()
+
+	// Determine the model to use
+	testModelID := modelID
+	if testModelID == "" {
+		testModelID = geminicli.DefaultTestModel
+	}
+
+	// For API Key accounts with model mapping, map the model
+	if account.Type == AccountTypeApiKey {
+		mapping := account.GetModelMapping()
+		if len(mapping) > 0 {
+			if mappedModel, exists := mapping[testModelID]; exists {
+				testModelID = mappedModel
+			}
+		}
+	}
+
+	// Set SSE headers
+	c.Writer.Header().Set("Content-Type", "text/event-stream")
+	c.Writer.Header().Set("Cache-Control", "no-cache")
+	c.Writer.Header().Set("Connection", "keep-alive")
+	c.Writer.Header().Set("X-Accel-Buffering", "no")
+	c.Writer.Flush()
+
+	// Create test payload (Gemini format)
+	payload := createGeminiTestPayload()
+
+	// Build request based on account type
+	var req *http.Request
+	var err error
+
+	switch account.Type {
+	case AccountTypeApiKey:
+		req, err = s.buildGeminiAPIKeyRequest(ctx, account, testModelID, payload)
+	case AccountTypeOAuth:
+		req, err = s.buildGeminiOAuthRequest(ctx, account, testModelID, payload)
+	default:
+		return s.sendErrorAndEnd(c, fmt.Sprintf("Unsupported account type: %s", account.Type))
+	}
+
+	if err != nil {
+		return s.sendErrorAndEnd(c, fmt.Sprintf("Failed to build request: %s", err.Error()))
+	}
+
+	// Send test_start event
+	s.sendEvent(c, TestEvent{Type: "test_start", Model: testModelID})
+
+	// Get proxy and execute request
+	proxyURL := ""
+	if account.ProxyID != nil && account.Proxy != nil {
+		proxyURL = account.Proxy.URL()
+	}
+
+	resp, err := s.httpUpstream.Do(req, proxyURL)
+	if err != nil {
+		return s.sendErrorAndEnd(c, fmt.Sprintf("Request failed: %s", err.Error()))
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return s.sendErrorAndEnd(c, fmt.Sprintf("API returned %d: %s", resp.StatusCode, string(body)))
+	}
+
+	// Process SSE stream
+	return s.processGeminiStream(c, resp.Body)
+}
+
+// buildGeminiAPIKeyRequest builds request for Gemini API Key accounts
+func (s *AccountTestService) buildGeminiAPIKeyRequest(ctx context.Context, account *Account, modelID string, payload []byte) (*http.Request, error) {
+	apiKey := account.GetCredential("api_key")
+	if strings.TrimSpace(apiKey) == "" {
+		return nil, fmt.Errorf("no API key available")
+	}
+
+	baseURL := account.GetCredential("base_url")
+	if baseURL == "" {
+		baseURL = geminicli.AIStudioBaseURL
+	}
+
+	// Use streamGenerateContent for real-time feedback
+	fullURL := fmt.Sprintf("%s/v1beta/models/%s:streamGenerateContent?alt=sse",
+		strings.TrimRight(baseURL, "/"), modelID)
+
+	req, err := http.NewRequestWithContext(ctx, "POST", fullURL, bytes.NewReader(payload))
+	if err != nil {
+		return nil, err
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("x-goog-api-key", apiKey)
+
+	return req, nil
+}
+
+// buildGeminiOAuthRequest builds request for Gemini OAuth accounts
+func (s *AccountTestService) buildGeminiOAuthRequest(ctx context.Context, account *Account, modelID string, payload []byte) (*http.Request, error) {
+	if s.geminiTokenProvider == nil {
+		return nil, fmt.Errorf("gemini token provider not configured")
+	}
+
+	// Get access token (auto-refreshes if needed)
+	accessToken, err := s.geminiTokenProvider.GetAccessToken(ctx, account)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get access token: %w", err)
+	}
+
+	projectID := strings.TrimSpace(account.GetCredential("project_id"))
+	if projectID == "" {
+		// AI Studio OAuth mode (no project_id): call generativelanguage API directly with Bearer token.
+		baseURL := account.GetCredential("base_url")
+		if strings.TrimSpace(baseURL) == "" {
+			baseURL = geminicli.AIStudioBaseURL
+		}
+		fullURL := fmt.Sprintf("%s/v1beta/models/%s:streamGenerateContent?alt=sse", strings.TrimRight(baseURL, "/"), modelID)
+
+		req, err := http.NewRequestWithContext(ctx, http.MethodPost, fullURL, bytes.NewReader(payload))
+		if err != nil {
+			return nil, err
+		}
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Authorization", "Bearer "+accessToken)
+		return req, nil
+	}
+
+	// Wrap payload in Code Assist format
+	var inner map[string]any
+	if err := json.Unmarshal(payload, &inner); err != nil {
+		return nil, err
+	}
+
+	wrapped := map[string]any{
+		"model":   modelID,
+		"project": projectID,
+		"request": inner,
+	}
+	wrappedBytes, _ := json.Marshal(wrapped)
+
+	fullURL := fmt.Sprintf("%s/v1internal:streamGenerateContent?alt=sse", geminicli.GeminiCliBaseURL)
+
+	req, err := http.NewRequestWithContext(ctx, "POST", fullURL, bytes.NewReader(wrappedBytes))
+	if err != nil {
+		return nil, err
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+	req.Header.Set("User-Agent", geminicli.GeminiCLIUserAgent)
+
+	return req, nil
+}
+
+// createGeminiTestPayload creates a minimal test payload for Gemini API
+func createGeminiTestPayload() []byte {
+	payload := map[string]any{
+		"contents": []map[string]any{
+			{
+				"role": "user",
+				"parts": []map[string]any{
+					{"text": "hi"},
+				},
+			},
+		},
+		"systemInstruction": map[string]any{
+			"parts": []map[string]any{
+				{"text": "You are a helpful AI assistant."},
+			},
+		},
+	}
+	bytes, _ := json.Marshal(payload)
+	return bytes
+}
+
+// processGeminiStream processes SSE stream from Gemini API
+func (s *AccountTestService) processGeminiStream(c *gin.Context, body io.Reader) error {
+	reader := bufio.NewReader(body)
+
+	for {
+		line, err := reader.ReadString('\n')
+		if err != nil {
+			if err == io.EOF {
+				s.sendEvent(c, TestEvent{Type: "test_complete", Success: true})
+				return nil
+			}
+			return s.sendErrorAndEnd(c, fmt.Sprintf("Stream read error: %s", err.Error()))
+		}
+
+		line = strings.TrimSpace(line)
+		if line == "" || !strings.HasPrefix(line, "data: ") {
+			continue
+		}
+
+		jsonStr := strings.TrimPrefix(line, "data: ")
+		if jsonStr == "[DONE]" {
+			s.sendEvent(c, TestEvent{Type: "test_complete", Success: true})
+			return nil
+		}
+
+		var data map[string]any
+		if err := json.Unmarshal([]byte(jsonStr), &data); err != nil {
+			continue
+		}
+
+		// Support two Gemini response formats:
+		// - AI Studio: {"candidates": [...]}
+		// - Gemini CLI: {"response": {"candidates": [...]}}
+		if resp, ok := data["response"].(map[string]any); ok && resp != nil {
+			data = resp
+		}
+		if candidates, ok := data["candidates"].([]any); ok && len(candidates) > 0 {
+			if candidate, ok := candidates[0].(map[string]any); ok {
+				// Check for completion
+				if finishReason, ok := candidate["finishReason"].(string); ok && finishReason != "" {
+					s.sendEvent(c, TestEvent{Type: "test_complete", Success: true})
+					return nil
+				}
+
+				// Extract content
+				if content, ok := candidate["content"].(map[string]any); ok {
+					if parts, ok := content["parts"].([]any); ok {
+						for _, part := range parts {
+							if partMap, ok := part.(map[string]any); ok {
+								if text, ok := partMap["text"].(string); ok && text != "" {
+									s.sendEvent(c, TestEvent{Type: "content", Text: text})
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+
+		// Handle errors
+		if errData, ok := data["error"].(map[string]any); ok {
+			errorMsg := "Unknown error"
+			if msg, ok := errData["message"].(string); ok {
+				errorMsg = msg
+			}
+			return s.sendErrorAndEnd(c, errorMsg)
+		}
+	}
+}
+
 // createOpenAITestPayload creates a test payload for OpenAI Responses API
 func createOpenAITestPayload(modelID string, isOAuth bool) map[string]any {
 	payload := map[string]any{

backend/internal/service/crs_sync_service.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"net/http"
 	"net/url"
+	"strconv"
 	"strings"
 	"time"
 )
@@ -18,6 +19,7 @@ type CRSSyncService struct {
 	proxyRepo          ProxyRepository
 	oauthService       *OAuthService
 	openaiOAuthService *OpenAIOAuthService
+	geminiOAuthService *GeminiOAuthService
 }
 
 func NewCRSSyncService(
@@ -25,12 +27,14 @@ func NewCRSSyncService(
 	proxyRepo ProxyRepository,
 	oauthService *OAuthService,
 	openaiOAuthService *OpenAIOAuthService,
+	geminiOAuthService *GeminiOAuthService,
 ) *CRSSyncService {
 	return &CRSSyncService{
 		accountRepo:        accountRepo,
 		proxyRepo:          proxyRepo,
 		oauthService:       oauthService,
 		openaiOAuthService: openaiOAuthService,
+		geminiOAuthService: geminiOAuthService,
 	}
 }
 
@@ -75,6 +79,8 @@ type crsExportResponse struct {
 		ClaudeConsoleAccounts   []crsConsoleAccount         `json:"claudeConsoleAccounts"`
 		OpenAIOAuthAccounts     []crsOpenAIOAuthAccount     `json:"openaiOAuthAccounts"`
 		OpenAIResponsesAccounts []crsOpenAIResponsesAccount `json:"openaiResponsesAccounts"`
+		GeminiOAuthAccounts     []crsGeminiOAuthAccount     `json:"geminiOAuthAccounts"`
+		GeminiAPIKeyAccounts    []crsGeminiAPIKeyAccount    `json:"geminiApiKeyAccounts"`
 	} `json:"data"`
 }
 
@@ -147,6 +153,37 @@ type crsOpenAIOAuthAccount struct {
 	Extra       map[string]any `json:"extra"`
 }
 
+type crsGeminiOAuthAccount struct {
+	Kind        string         `json:"kind"`
+	ID          string         `json:"id"`
+	Name        string         `json:"name"`
+	Description string         `json:"description"`
+	Platform    string         `json:"platform"`
+	AuthType    string         `json:"authType"` // oauth
+	IsActive    bool           `json:"isActive"`
+	Schedulable bool           `json:"schedulable"`
+	Priority    int            `json:"priority"`
+	Status      string         `json:"status"`
+	Proxy       *crsProxy      `json:"proxy"`
+	Credentials map[string]any `json:"credentials"`
+	Extra       map[string]any `json:"extra"`
+}
+
+type crsGeminiAPIKeyAccount struct {
+	Kind        string         `json:"kind"`
+	ID          string         `json:"id"`
+	Name        string         `json:"name"`
+	Description string         `json:"description"`
+	Platform    string         `json:"platform"`
+	IsActive    bool           `json:"isActive"`
+	Schedulable bool           `json:"schedulable"`
+	Priority    int            `json:"priority"`
+	Status      string         `json:"status"`
+	Proxy       *crsProxy      `json:"proxy"`
+	Credentials map[string]any `json:"credentials"`
+	Extra       map[string]any `json:"extra"`
+}
+
 func (s *CRSSyncService) SyncFromCRS(ctx context.Context, input SyncFromCRSInput) (*SyncFromCRSResult, error) {
 	baseURL, err := normalizeBaseURL(input.BaseURL)
 	if err != nil {
@@ -174,7 +211,7 @@ func (s *CRSSyncService) SyncFromCRS(ctx context.Context, input SyncFromCRSInput
 		Items: make(
 			[]SyncFromCRSItemResult,
 			0,
-			len(exported.Data.ClaudeAccounts)+len(exported.Data.ClaudeConsoleAccounts)+len(exported.Data.OpenAIOAuthAccounts)+len(exported.Data.OpenAIResponsesAccounts),
+			len(exported.Data.ClaudeAccounts)+len(exported.Data.ClaudeConsoleAccounts)+len(exported.Data.OpenAIOAuthAccounts)+len(exported.Data.OpenAIResponsesAccounts)+len(exported.Data.GeminiOAuthAccounts)+len(exported.Data.GeminiAPIKeyAccounts),
 		),
 	}
 
@@ -678,6 +715,225 @@ func (s *CRSSyncService) SyncFromCRS(ctx context.Context, input SyncFromCRSInput
 		result.Items = append(result.Items, item)
 	}
 
+	// Gemini OAuth -> sub2api gemini oauth
+	for _, src := range exported.Data.GeminiOAuthAccounts {
+		item := SyncFromCRSItemResult{
+			CRSAccountID: src.ID,
+			Kind:         src.Kind,
+			Name:         src.Name,
+		}
+
+		refreshToken, _ := src.Credentials["refresh_token"].(string)
+		if strings.TrimSpace(refreshToken) == "" {
+			item.Action = "failed"
+			item.Error = "missing refresh_token"
+			result.Failed++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		proxyID, err := s.mapOrCreateProxy(ctx, input.SyncProxies, &proxies, src.Proxy, fmt.Sprintf("crs-%s", src.Name))
+		if err != nil {
+			item.Action = "failed"
+			item.Error = "proxy sync failed: " + err.Error()
+			result.Failed++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		credentials := sanitizeCredentialsMap(src.Credentials)
+		if v, ok := credentials["token_type"].(string); !ok || strings.TrimSpace(v) == "" {
+			credentials["token_type"] = "Bearer"
+		}
+		// Convert expires_at from RFC3339 to Unix seconds string (recommended to keep consistent with GetCredential())
+		if expiresAtStr, ok := credentials["expires_at"].(string); ok && strings.TrimSpace(expiresAtStr) != "" {
+			if t, err := time.Parse(time.RFC3339, expiresAtStr); err == nil {
+				credentials["expires_at"] = strconv.FormatInt(t.Unix(), 10)
+			}
+		}
+
+		extra := make(map[string]any)
+		if src.Extra != nil {
+			for k, v := range src.Extra {
+				extra[k] = v
+			}
+		}
+		extra["crs_account_id"] = src.ID
+		extra["crs_kind"] = src.Kind
+		extra["crs_synced_at"] = now
+
+		existing, err := s.accountRepo.GetByCRSAccountID(ctx, src.ID)
+		if err != nil {
+			item.Action = "failed"
+			item.Error = "db lookup failed: " + err.Error()
+			result.Failed++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		if existing == nil {
+			account := &Account{
+				Name:        defaultName(src.Name, src.ID),
+				Platform:    PlatformGemini,
+				Type:        AccountTypeOAuth,
+				Credentials: credentials,
+				Extra:       extra,
+				ProxyID:     proxyID,
+				Concurrency: 3,
+				Priority:    clampPriority(src.Priority),
+				Status:      mapCRSStatus(src.IsActive, src.Status),
+				Schedulable: src.Schedulable,
+			}
+			if err := s.accountRepo.Create(ctx, account); err != nil {
+				item.Action = "failed"
+				item.Error = "create failed: " + err.Error()
+				result.Failed++
+				result.Items = append(result.Items, item)
+				continue
+			}
+			if refreshedCreds := s.refreshOAuthToken(ctx, account); refreshedCreds != nil {
+				account.Credentials = refreshedCreds
+				_ = s.accountRepo.Update(ctx, account)
+			}
+			item.Action = "created"
+			result.Created++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		existing.Extra = mergeMap(existing.Extra, extra)
+		existing.Name = defaultName(src.Name, src.ID)
+		existing.Platform = PlatformGemini
+		existing.Type = AccountTypeOAuth
+		existing.Credentials = mergeMap(existing.Credentials, credentials)
+		if proxyID != nil {
+			existing.ProxyID = proxyID
+		}
+		existing.Concurrency = 3
+		existing.Priority = clampPriority(src.Priority)
+		existing.Status = mapCRSStatus(src.IsActive, src.Status)
+		existing.Schedulable = src.Schedulable
+
+		if err := s.accountRepo.Update(ctx, existing); err != nil {
+			item.Action = "failed"
+			item.Error = "update failed: " + err.Error()
+			result.Failed++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		if refreshedCreds := s.refreshOAuthToken(ctx, existing); refreshedCreds != nil {
+			existing.Credentials = refreshedCreds
+			_ = s.accountRepo.Update(ctx, existing)
+		}
+
+		item.Action = "updated"
+		result.Updated++
+		result.Items = append(result.Items, item)
+	}
+
+	// Gemini API Key -> sub2api gemini apikey
+	for _, src := range exported.Data.GeminiAPIKeyAccounts {
+		item := SyncFromCRSItemResult{
+			CRSAccountID: src.ID,
+			Kind:         src.Kind,
+			Name:         src.Name,
+		}
+
+		apiKey, _ := src.Credentials["api_key"].(string)
+		if strings.TrimSpace(apiKey) == "" {
+			item.Action = "failed"
+			item.Error = "missing api_key"
+			result.Failed++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		proxyID, err := s.mapOrCreateProxy(ctx, input.SyncProxies, &proxies, src.Proxy, fmt.Sprintf("crs-%s", src.Name))
+		if err != nil {
+			item.Action = "failed"
+			item.Error = "proxy sync failed: " + err.Error()
+			result.Failed++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		credentials := sanitizeCredentialsMap(src.Credentials)
+		if baseURL, ok := credentials["base_url"].(string); !ok || strings.TrimSpace(baseURL) == "" {
+			credentials["base_url"] = "https://generativelanguage.googleapis.com"
+		}
+
+		extra := make(map[string]any)
+		if src.Extra != nil {
+			for k, v := range src.Extra {
+				extra[k] = v
+			}
+		}
+		extra["crs_account_id"] = src.ID
+		extra["crs_kind"] = src.Kind
+		extra["crs_synced_at"] = now
+
+		existing, err := s.accountRepo.GetByCRSAccountID(ctx, src.ID)
+		if err != nil {
+			item.Action = "failed"
+			item.Error = "db lookup failed: " + err.Error()
+			result.Failed++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		if existing == nil {
+			account := &Account{
+				Name:        defaultName(src.Name, src.ID),
+				Platform:    PlatformGemini,
+				Type:        AccountTypeApiKey,
+				Credentials: credentials,
+				Extra:       extra,
+				ProxyID:     proxyID,
+				Concurrency: 3,
+				Priority:    clampPriority(src.Priority),
+				Status:      mapCRSStatus(src.IsActive, src.Status),
+				Schedulable: src.Schedulable,
+			}
+			if err := s.accountRepo.Create(ctx, account); err != nil {
+				item.Action = "failed"
+				item.Error = "create failed: " + err.Error()
+				result.Failed++
+				result.Items = append(result.Items, item)
+				continue
+			}
+			item.Action = "created"
+			result.Created++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		existing.Extra = mergeMap(existing.Extra, extra)
+		existing.Name = defaultName(src.Name, src.ID)
+		existing.Platform = PlatformGemini
+		existing.Type = AccountTypeApiKey
+		existing.Credentials = mergeMap(existing.Credentials, credentials)
+		if proxyID != nil {
+			existing.ProxyID = proxyID
+		}
+		existing.Concurrency = 3
+		existing.Priority = clampPriority(src.Priority)
+		existing.Status = mapCRSStatus(src.IsActive, src.Status)
+		existing.Schedulable = src.Schedulable
+
+		if err := s.accountRepo.Update(ctx, existing); err != nil {
+			item.Action = "failed"
+			item.Error = "update failed: " + err.Error()
+			result.Failed++
+			result.Items = append(result.Items, item)
+			continue
+		}
+
+		item.Action = "updated"
+		result.Updated++
+		result.Items = append(result.Items, item)
+	}
+
 	return result, nil
 }
 
@@ -944,6 +1200,21 @@ func (s *CRSSyncService) refreshOAuthToken(ctx context.Context, account *Account
 				}
 			}
 		}
+	case PlatformGemini:
+		if s.geminiOAuthService == nil {
+			return nil
+		}
+		tokenInfo, refreshErr := s.geminiOAuthService.RefreshAccountToken(ctx, account)
+		if refreshErr != nil {
+			err = refreshErr
+		} else {
+			newCredentials = s.geminiOAuthService.BuildAccountCredentials(tokenInfo)
+			for k, v := range account.Credentials {
+				if _, exists := newCredentials[k]; !exists {
+					newCredentials[k] = v
+				}
+			}
+		}
 	default:
 		return nil
 	}

backend/internal/service/gateway_service.go

@@ -320,8 +320,17 @@ func (s *GatewayService) SelectAccountForModel(ctx context.Context, groupID *int
 			selected = acc
 		} else if acc.Priority == selected.Priority {
 			// 优先级相同时，选最久未用的
-			if acc.LastUsedAt == nil || (selected.LastUsedAt != nil && acc.LastUsedAt.Before(*selected.LastUsedAt)) {
+			switch {
+			case acc.LastUsedAt == nil && selected.LastUsedAt != nil:
 				selected = acc
+			case acc.LastUsedAt != nil && selected.LastUsedAt == nil:
+				// keep selected (never used is preferred)
+			case acc.LastUsedAt == nil && selected.LastUsedAt == nil:
+				// keep selected (both never used)
+			default:
+				if acc.LastUsedAt.Before(*selected.LastUsedAt) {
+					selected = acc
+				}
 			}
 		}
 	}

backend/internal/service/gemini_messages_compat_service.go

+package service
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"math"
+	mathrand "math/rand"
+	"net/http"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/geminicli"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/googleapi"
+
+	"github.com/gin-gonic/gin"
+)
+
+const geminiStickySessionTTL = time.Hour
+
+const (
+	geminiMaxRetries     = 5
+	geminiRetryBaseDelay = 1 * time.Second
+	geminiRetryMaxDelay  = 16 * time.Second
+)
+
+type GeminiMessagesCompatService struct {
+	accountRepo      AccountRepository
+	cache            GatewayCache
+	tokenProvider    *GeminiTokenProvider
+	rateLimitService *RateLimitService
+	httpUpstream     HTTPUpstream
+}
+
+func NewGeminiMessagesCompatService(
+	accountRepo AccountRepository,
+	cache GatewayCache,
+	tokenProvider *GeminiTokenProvider,
+	rateLimitService *RateLimitService,
+	httpUpstream HTTPUpstream,
+) *GeminiMessagesCompatService {
+	return &GeminiMessagesCompatService{
+		accountRepo:      accountRepo,
+		cache:            cache,
+		tokenProvider:    tokenProvider,
+		rateLimitService: rateLimitService,
+		httpUpstream:     httpUpstream,
+	}
+}
+
+// GetTokenProvider returns the token provider for OAuth accounts
+func (s *GeminiMessagesCompatService) GetTokenProvider() *GeminiTokenProvider {
+	return s.tokenProvider
+}
+
+func (s *GeminiMessagesCompatService) SelectAccountForModel(ctx context.Context, groupID *int64, sessionHash string, requestedModel string) (*Account, error) {
+	cacheKey := "gemini:" + sessionHash
+	if sessionHash != "" {
+		accountID, err := s.cache.GetSessionAccountID(ctx, cacheKey)
+		if err == nil && accountID > 0 {
+			account, err := s.accountRepo.GetByID(ctx, accountID)
+			if err == nil && account.IsSchedulable() && account.Platform == PlatformGemini && (requestedModel == "" || account.IsModelSupported(requestedModel)) {
+				_ = s.cache.RefreshSessionTTL(ctx, cacheKey, geminiStickySessionTTL)
+				return account, nil
+			}
+		}
+	}
+
+	var accounts []Account
+	var err error
+	if groupID != nil {
+		accounts, err = s.accountRepo.ListSchedulableByGroupIDAndPlatform(ctx, *groupID, PlatformGemini)
+	} else {
+		accounts, err = s.accountRepo.ListSchedulableByPlatform(ctx, PlatformGemini)
+	}
+	if err != nil {
+		return nil, fmt.Errorf("query accounts failed: %w", err)
+	}
+
+	var selected *Account
+	for i := range accounts {
+		acc := &accounts[i]
+		if requestedModel != "" && !acc.IsModelSupported(requestedModel) {
+			continue
+		}
+		if selected == nil {
+			selected = acc
+			continue
+		}
+		if acc.Priority < selected.Priority {
+			selected = acc
+		} else if acc.Priority == selected.Priority {
+			switch {
+			case acc.LastUsedAt == nil && selected.LastUsedAt != nil:
+				selected = acc
+			case acc.LastUsedAt != nil && selected.LastUsedAt == nil:
+				// keep selected (never used is preferred)
+			case acc.LastUsedAt == nil && selected.LastUsedAt == nil:
+				// Prefer OAuth accounts when both are unused (more compatible for Code Assist flows).
+				if acc.Type == AccountTypeOAuth && selected.Type != AccountTypeOAuth {
+					selected = acc
+				}
+			default:
+				if acc.LastUsedAt.Before(*selected.LastUsedAt) {
+					selected = acc
+				}
+			}
+		}
+	}
+
+	if selected == nil {
+		if requestedModel != "" {
+			return nil, fmt.Errorf("no available Gemini accounts supporting model: %s", requestedModel)
+		}
+		return nil, errors.New("no available Gemini accounts")
+	}
+
+	if sessionHash != "" {
+		_ = s.cache.SetSessionAccountID(ctx, cacheKey, selected.ID, geminiStickySessionTTL)
+	}
+
+	return selected, nil
+}
+
+// SelectAccountForAIStudioEndpoints selects an account that is likely to succeed against
+// generativelanguage.googleapis.com (e.g. GET /v1beta/models).
+//
+// Preference order:
+// 1) API key accounts (AI Studio)
+// 2) OAuth accounts without project_id (AI Studio OAuth)
+// 3) OAuth accounts explicitly marked as ai_studio
+// 4) Any remaining Gemini accounts (fallback)
+func (s *GeminiMessagesCompatService) SelectAccountForAIStudioEndpoints(ctx context.Context, groupID *int64) (*Account, error) {
+	var accounts []Account
+	var err error
+	if groupID != nil {
+		accounts, err = s.accountRepo.ListSchedulableByGroupIDAndPlatform(ctx, *groupID, PlatformGemini)
+	} else {
+		accounts, err = s.accountRepo.ListSchedulableByPlatform(ctx, PlatformGemini)
+	}
+	if err != nil {
+		return nil, fmt.Errorf("query accounts failed: %w", err)
+	}
+	if len(accounts) == 0 {
+		return nil, errors.New("no available Gemini accounts")
+	}
+
+	rank := func(a *Account) int {
+		if a == nil {
+			return 999
+		}
+		switch a.Type {
+		case AccountTypeApiKey:
+			if strings.TrimSpace(a.GetCredential("api_key")) != "" {
+				return 0
+			}
+			return 9
+		case AccountTypeOAuth:
+			if strings.TrimSpace(a.GetCredential("project_id")) == "" {
+				return 1
+			}
+			if strings.TrimSpace(a.GetCredential("oauth_type")) == "ai_studio" {
+				return 2
+			}
+			// Code Assist OAuth tokens often lack AI Studio scopes for models listing.
+			return 3
+		default:
+			return 10
+		}
+	}
+
+	var selected *Account
+	for i := range accounts {
+		acc := &accounts[i]
+		if selected == nil {
+			selected = acc
+			continue
+		}
+
+		r1, r2 := rank(acc), rank(selected)
+		if r1 < r2 {
+			selected = acc
+			continue
+		}
+		if r1 > r2 {
+			continue
+		}
+
+		if acc.Priority < selected.Priority {
+			selected = acc
+		} else if acc.Priority == selected.Priority {
+			switch {
+			case acc.LastUsedAt == nil && selected.LastUsedAt != nil:
+				selected = acc
+			case acc.LastUsedAt != nil && selected.LastUsedAt == nil:
+				// keep selected
+			case acc.LastUsedAt == nil && selected.LastUsedAt == nil:
+				if acc.Type == AccountTypeOAuth && selected.Type != AccountTypeOAuth {
+					selected = acc
+				}
+			default:
+				if acc.LastUsedAt.Before(*selected.LastUsedAt) {
+					selected = acc
+				}
+			}
+		}
+	}
+
+	if selected == nil {
+		return nil, errors.New("no available Gemini accounts")
+	}
+	return selected, nil
+}
+
+func (s *GeminiMessagesCompatService) Forward(ctx context.Context, c *gin.Context, account *Account, body []byte) (*ForwardResult, error) {
+	startTime := time.Now()
+
+	var req struct {
+		Model  string `json:"model"`
+		Stream bool   `json:"stream"`
+	}
+	if err := json.Unmarshal(body, &req); err != nil {
+		return nil, fmt.Errorf("parse request: %w", err)
+	}
+	if strings.TrimSpace(req.Model) == "" {
+		return nil, fmt.Errorf("missing model")
+	}
+
+	originalModel := req.Model
+	mappedModel := req.Model
+	if account.Type == AccountTypeApiKey {
+		mappedModel = account.GetMappedModel(req.Model)
+	}
+
+	geminiReq, err := convertClaudeMessagesToGeminiGenerateContent(body)
+	if err != nil {
+		return nil, s.writeClaudeError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+	}
+
+	proxyURL := ""
+	if account.ProxyID != nil && account.Proxy != nil {
+		proxyURL = account.Proxy.URL()
+	}
+
+	var requestIDHeader string
+	var buildReq func(ctx context.Context) (*http.Request, string, error)
+	useUpstreamStream := req.Stream
+	if account.Type == AccountTypeOAuth && !req.Stream && strings.TrimSpace(account.GetCredential("project_id")) != "" {
+		// Code Assist's non-streaming generateContent may return no content; use streaming upstream and aggregate.
+		useUpstreamStream = true
+	}
+
+	switch account.Type {
+	case AccountTypeApiKey:
+		buildReq = func(ctx context.Context) (*http.Request, string, error) {
+			apiKey := account.GetCredential("api_key")
+			if strings.TrimSpace(apiKey) == "" {
+				return nil, "", errors.New("gemini api_key not configured")
+			}
+
+			baseURL := strings.TrimRight(account.GetCredential("base_url"), "/")
+			if baseURL == "" {
+				baseURL = geminicli.AIStudioBaseURL
+			}
+
+			action := "generateContent"
+			if req.Stream {
+				action = "streamGenerateContent"
+			}
+			fullURL := fmt.Sprintf("%s/v1beta/models/%s:%s", strings.TrimRight(baseURL, "/"), mappedModel, action)
+			if req.Stream {
+				fullURL += "?alt=sse"
+			}
+
+			upstreamReq, err := http.NewRequestWithContext(ctx, http.MethodPost, fullURL, bytes.NewReader(geminiReq))
+			if err != nil {
+				return nil, "", err
+			}
+			upstreamReq.Header.Set("Content-Type", "application/json")
+			upstreamReq.Header.Set("x-goog-api-key", apiKey)
+			return upstreamReq, "x-request-id", nil
+		}
+		requestIDHeader = "x-request-id"
+
+	case AccountTypeOAuth:
+		buildReq = func(ctx context.Context) (*http.Request, string, error) {
+			if s.tokenProvider == nil {
+				return nil, "", errors.New("gemini token provider not configured")
+			}
+			accessToken, err := s.tokenProvider.GetAccessToken(ctx, account)
+			if err != nil {
+				return nil, "", err
+			}
+
+			projectID := strings.TrimSpace(account.GetCredential("project_id"))
+
+			action := "generateContent"
+			if useUpstreamStream {
+				action = "streamGenerateContent"
+			}
+
+			// Two modes for OAuth:
+			// 1. With project_id -> Code Assist API (wrapped request)
+			// 2. Without project_id -> AI Studio API (direct OAuth, like API key but with Bearer token)
+			if projectID != "" {
+				// Mode 1: Code Assist API
+				fullURL := fmt.Sprintf("%s/v1internal:%s", geminicli.GeminiCliBaseURL, action)
+				if useUpstreamStream {
+					fullURL += "?alt=sse"
+				}
+
+				wrapped := map[string]any{
+					"model":   mappedModel,
+					"project": projectID,
+				}
+				var inner any
+				if err := json.Unmarshal(geminiReq, &inner); err != nil {
+					return nil, "", fmt.Errorf("failed to parse gemini request: %w", err)
+				}
+				wrapped["request"] = inner
+				wrappedBytes, _ := json.Marshal(wrapped)
+
+				upstreamReq, err := http.NewRequestWithContext(ctx, http.MethodPost, fullURL, bytes.NewReader(wrappedBytes))
+				if err != nil {
+					return nil, "", err
+				}
+				upstreamReq.Header.Set("Content-Type", "application/json")
+				upstreamReq.Header.Set("Authorization", "Bearer "+accessToken)
+				upstreamReq.Header.Set("User-Agent", geminicli.GeminiCLIUserAgent)
+				return upstreamReq, "x-request-id", nil
+			} else {
+				// Mode 2: AI Studio API with OAuth (like API key mode, but using Bearer token)
+				baseURL := strings.TrimRight(account.GetCredential("base_url"), "/")
+				if baseURL == "" {
+					baseURL = geminicli.AIStudioBaseURL
+				}
+
+				fullURL := fmt.Sprintf("%s/v1beta/models/%s:%s", baseURL, mappedModel, action)
+				if useUpstreamStream {
+					fullURL += "?alt=sse"
+				}
+
+				upstreamReq, err := http.NewRequestWithContext(ctx, http.MethodPost, fullURL, bytes.NewReader(geminiReq))
+				if err != nil {
+					return nil, "", err
+				}
+				upstreamReq.Header.Set("Content-Type", "application/json")
+				upstreamReq.Header.Set("Authorization", "Bearer "+accessToken)
+				return upstreamReq, "x-request-id", nil
+			}
+		}
+		requestIDHeader = "x-request-id"
+
+	default:
+		return nil, fmt.Errorf("unsupported account type: %s", account.Type)
+	}
+
+	var resp *http.Response
+	for attempt := 1; attempt <= geminiMaxRetries; attempt++ {
+		upstreamReq, idHeader, err := buildReq(ctx)
+		if err != nil {
+			if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+				return nil, err
+			}
+			// Local build error: don't retry.
+			if strings.Contains(err.Error(), "missing project_id") {
+				return nil, s.writeClaudeError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+			}
+			return nil, s.writeClaudeError(c, http.StatusBadGateway, "upstream_error", err.Error())
+		}
+		requestIDHeader = idHeader
+
+		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL)
+		if err != nil {
+			if attempt < geminiMaxRetries {
+				log.Printf("Gemini account %d: upstream request failed, retry %d/%d: %v", account.ID, attempt, geminiMaxRetries, err)
+				sleepGeminiBackoff(attempt)
+				continue
+			}
+			return nil, s.writeClaudeError(c, http.StatusBadGateway, "upstream_error", "Upstream request failed after retries: "+sanitizeUpstreamErrorMessage(err.Error()))
+		}
+
+		if resp.StatusCode >= 400 && s.shouldRetryGeminiUpstreamError(account, resp.StatusCode) {
+			respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 2<<20))
+			_ = resp.Body.Close()
+			// Don't treat insufficient-scope as transient.
+			if resp.StatusCode == 403 && isGeminiInsufficientScope(resp.Header, respBody) {
+				resp = &http.Response{
+					StatusCode: resp.StatusCode,
+					Header:     resp.Header.Clone(),
+					Body:       io.NopCloser(bytes.NewReader(respBody)),
+				}
+				break
+			}
+			if resp.StatusCode == 429 {
+				// Mark as rate-limited early so concurrent requests avoid this account.
+				s.handleGeminiUpstreamError(ctx, account, resp.StatusCode, resp.Header, respBody)
+			}
+			if attempt < geminiMaxRetries {
+				log.Printf("Gemini account %d: upstream status %d, retry %d/%d", account.ID, resp.StatusCode, attempt, geminiMaxRetries)
+				sleepGeminiBackoff(attempt)
+				continue
+			}
+			// Final attempt: surface the upstream error body (mapped below) instead of a generic retry error.
+			resp = &http.Response{
+				StatusCode: resp.StatusCode,
+				Header:     resp.Header.Clone(),
+				Body:       io.NopCloser(bytes.NewReader(respBody)),
+			}
+			break
+		}
+
+		break
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode >= 400 {
+		respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 2<<20))
+		s.handleGeminiUpstreamError(ctx, account, resp.StatusCode, resp.Header, respBody)
+		return nil, s.writeGeminiMappedError(c, resp.StatusCode, respBody)
+	}
+
+	requestID := resp.Header.Get(requestIDHeader)
+	if requestID == "" {
+		requestID = resp.Header.Get("x-goog-request-id")
+	}
+	if requestID != "" {
+		c.Header("x-request-id", requestID)
+	}
+
+	var usage *ClaudeUsage
+	var firstTokenMs *int
+	if req.Stream {
+		streamRes, err := s.handleStreamingResponse(c, resp, startTime, originalModel)
+		if err != nil {
+			return nil, err
+		}
+		usage = streamRes.usage
+		firstTokenMs = streamRes.firstTokenMs
+	} else {
+		if useUpstreamStream {
+			collected, usageObj, err := collectGeminiSSE(resp.Body, true)
+			if err != nil {
+				return nil, s.writeClaudeError(c, http.StatusBadGateway, "upstream_error", "Failed to read upstream stream")
+			}
+			claudeResp, usageObj2 := convertGeminiToClaudeMessage(collected, originalModel)
+			c.JSON(http.StatusOK, claudeResp)
+			usage = usageObj2
+			if usageObj != nil && (usageObj.InputTokens > 0 || usageObj.OutputTokens > 0) {
+				usage = usageObj
+			}
+		} else {
+			usage, err = s.handleNonStreamingResponse(c, resp, originalModel)
+			if err != nil {
+				return nil, err
+			}
+		}
+	}
+
+	return &ForwardResult{
+		RequestID:    requestID,
+		Usage:        *usage,
+		Model:        originalModel,
+		Stream:       req.Stream,
+		Duration:     time.Since(startTime),
+		FirstTokenMs: firstTokenMs,
+	}, nil
+}
+
+func (s *GeminiMessagesCompatService) ForwardNative(ctx context.Context, c *gin.Context, account *Account, originalModel string, action string, stream bool, body []byte) (*ForwardResult, error) {
+	startTime := time.Now()
+
+	if strings.TrimSpace(originalModel) == "" {
+		return nil, s.writeGoogleError(c, http.StatusBadRequest, "Missing model in URL")
+	}
+	if strings.TrimSpace(action) == "" {
+		return nil, s.writeGoogleError(c, http.StatusBadRequest, "Missing action in URL")
+	}
+	if len(body) == 0 {
+		return nil, s.writeGoogleError(c, http.StatusBadRequest, "Request body is empty")
+	}
+
+	switch action {
+	case "generateContent", "streamGenerateContent", "countTokens":
+		// ok
+	default:
+		return nil, s.writeGoogleError(c, http.StatusNotFound, "Unsupported action: "+action)
+	}
+
+	mappedModel := originalModel
+	if account.Type == AccountTypeApiKey {
+		mappedModel = account.GetMappedModel(originalModel)
+	}
+
+	proxyURL := ""
+	if account.ProxyID != nil && account.Proxy != nil {
+		proxyURL = account.Proxy.URL()
+	}
+
+	useUpstreamStream := stream
+	upstreamAction := action
+	if account.Type == AccountTypeOAuth && !stream && action == "generateContent" && strings.TrimSpace(account.GetCredential("project_id")) != "" {
+		// Code Assist's non-streaming generateContent may return no content; use streaming upstream and aggregate.
+		useUpstreamStream = true
+		upstreamAction = "streamGenerateContent"
+	}
+	forceAIStudio := action == "countTokens"
+
+	var requestIDHeader string
+	var buildReq func(ctx context.Context) (*http.Request, string, error)
+
+	switch account.Type {
+	case AccountTypeApiKey:
+		buildReq = func(ctx context.Context) (*http.Request, string, error) {
+			apiKey := account.GetCredential("api_key")
+			if strings.TrimSpace(apiKey) == "" {
+				return nil, "", errors.New("gemini api_key not configured")
+			}
+
+			baseURL := strings.TrimRight(account.GetCredential("base_url"), "/")
+			if baseURL == "" {
+				baseURL = geminicli.AIStudioBaseURL
+			}
+
+			fullURL := fmt.Sprintf("%s/v1beta/models/%s:%s", strings.TrimRight(baseURL, "/"), mappedModel, upstreamAction)
+			if useUpstreamStream {
+				fullURL += "?alt=sse"
+			}
+
+			upstreamReq, err := http.NewRequestWithContext(ctx, http.MethodPost, fullURL, bytes.NewReader(body))
+			if err != nil {
+				return nil, "", err
+			}
+			upstreamReq.Header.Set("Content-Type", "application/json")
+			upstreamReq.Header.Set("x-goog-api-key", apiKey)
+			return upstreamReq, "x-request-id", nil
+		}
+		requestIDHeader = "x-request-id"
+
+	case AccountTypeOAuth:
+		buildReq = func(ctx context.Context) (*http.Request, string, error) {
+			if s.tokenProvider == nil {
+				return nil, "", errors.New("gemini token provider not configured")
+			}
+			accessToken, err := s.tokenProvider.GetAccessToken(ctx, account)
+			if err != nil {
+				return nil, "", err
+			}
+
+			projectID := strings.TrimSpace(account.GetCredential("project_id"))
+
+			// Two modes for OAuth:
+			// 1. With project_id -> Code Assist API (wrapped request)
+			// 2. Without project_id -> AI Studio API (direct OAuth, like API key but with Bearer token)
+			if projectID != "" && !forceAIStudio {
+				// Mode 1: Code Assist API
+				fullURL := fmt.Sprintf("%s/v1internal:%s", geminicli.GeminiCliBaseURL, upstreamAction)
+				if useUpstreamStream {
+					fullURL += "?alt=sse"
+				}
+
+				wrapped := map[string]any{
+					"model":   mappedModel,
+					"project": projectID,
+				}
+				var inner any
+				if err := json.Unmarshal(body, &inner); err != nil {
+					return nil, "", fmt.Errorf("failed to parse gemini request: %w", err)
+				}
+				wrapped["request"] = inner
+				wrappedBytes, _ := json.Marshal(wrapped)
+
+				upstreamReq, err := http.NewRequestWithContext(ctx, http.MethodPost, fullURL, bytes.NewReader(wrappedBytes))
+				if err != nil {
+					return nil, "", err
+				}
+				upstreamReq.Header.Set("Content-Type", "application/json")
+				upstreamReq.Header.Set("Authorization", "Bearer "+accessToken)
+				upstreamReq.Header.Set("User-Agent", geminicli.GeminiCLIUserAgent)
+				return upstreamReq, "x-request-id", nil
+			} else {
+				// Mode 2: AI Studio API with OAuth (like API key mode, but using Bearer token)
+				baseURL := strings.TrimRight(account.GetCredential("base_url"), "/")
+				if baseURL == "" {
+					baseURL = geminicli.AIStudioBaseURL
+				}
+
+				fullURL := fmt.Sprintf("%s/v1beta/models/%s:%s", baseURL, mappedModel, upstreamAction)
+				if useUpstreamStream {
+					fullURL += "?alt=sse"
+				}
+
+				upstreamReq, err := http.NewRequestWithContext(ctx, http.MethodPost, fullURL, bytes.NewReader(body))
+				if err != nil {
+					return nil, "", err
+				}
+				upstreamReq.Header.Set("Content-Type", "application/json")
+				upstreamReq.Header.Set("Authorization", "Bearer "+accessToken)
+				return upstreamReq, "x-request-id", nil
+			}
+		}
+		requestIDHeader = "x-request-id"
+
+	default:
+		return nil, s.writeGoogleError(c, http.StatusBadGateway, "Unsupported account type: "+account.Type)
+	}
+
+	var resp *http.Response
+	for attempt := 1; attempt <= geminiMaxRetries; attempt++ {
+		upstreamReq, idHeader, err := buildReq(ctx)
+		if err != nil {
+			if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+				return nil, err
+			}
+			// Local build error: don't retry.
+			if strings.Contains(err.Error(), "missing project_id") {
+				return nil, s.writeGoogleError(c, http.StatusBadRequest, err.Error())
+			}
+			return nil, s.writeGoogleError(c, http.StatusBadGateway, err.Error())
+		}
+		requestIDHeader = idHeader
+
+		resp, err = s.httpUpstream.Do(upstreamReq, proxyURL)
+		if err != nil {
+			if attempt < geminiMaxRetries {
+				log.Printf("Gemini account %d: upstream request failed, retry %d/%d: %v", account.ID, attempt, geminiMaxRetries, err)
+				sleepGeminiBackoff(attempt)
+				continue
+			}
+			if action == "countTokens" {
+				estimated := estimateGeminiCountTokens(body)
+				c.JSON(http.StatusOK, map[string]any{"totalTokens": estimated})
+				return &ForwardResult{
+					RequestID:    "",
+					Usage:        ClaudeUsage{},
+					Model:        originalModel,
+					Stream:       false,
+					Duration:     time.Since(startTime),
+					FirstTokenMs: nil,
+				}, nil
+			}
+			return nil, s.writeGoogleError(c, http.StatusBadGateway, "Upstream request failed after retries: "+sanitizeUpstreamErrorMessage(err.Error()))
+		}
+
+		if resp.StatusCode >= 400 && s.shouldRetryGeminiUpstreamError(account, resp.StatusCode) {
+			respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 2<<20))
+			_ = resp.Body.Close()
+			// Don't treat insufficient-scope as transient.
+			if resp.StatusCode == 403 && isGeminiInsufficientScope(resp.Header, respBody) {
+				resp = &http.Response{
+					StatusCode: resp.StatusCode,
+					Header:     resp.Header.Clone(),
+					Body:       io.NopCloser(bytes.NewReader(respBody)),
+				}
+				break
+			}
+			if resp.StatusCode == 429 {
+				s.handleGeminiUpstreamError(ctx, account, resp.StatusCode, resp.Header, respBody)
+			}
+			if attempt < geminiMaxRetries {
+				log.Printf("Gemini account %d: upstream status %d, retry %d/%d", account.ID, resp.StatusCode, attempt, geminiMaxRetries)
+				sleepGeminiBackoff(attempt)
+				continue
+			}
+			if action == "countTokens" {
+				estimated := estimateGeminiCountTokens(body)
+				c.JSON(http.StatusOK, map[string]any{"totalTokens": estimated})
+				return &ForwardResult{
+					RequestID:    "",
+					Usage:        ClaudeUsage{},
+					Model:        originalModel,
+					Stream:       false,
+					Duration:     time.Since(startTime),
+					FirstTokenMs: nil,
+				}, nil
+			}
+			// Final attempt: surface the upstream error body (passed through below) instead of a generic retry error.
+			resp = &http.Response{
+				StatusCode: resp.StatusCode,
+				Header:     resp.Header.Clone(),
+				Body:       io.NopCloser(bytes.NewReader(respBody)),
+			}
+			break
+		}
+
+		break
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	requestID := resp.Header.Get(requestIDHeader)
+	if requestID == "" {
+		requestID = resp.Header.Get("x-goog-request-id")
+	}
+	if requestID != "" {
+		c.Header("x-request-id", requestID)
+	}
+
+	isOAuth := account.Type == AccountTypeOAuth
+
+	if resp.StatusCode >= 400 {
+		respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 2<<20))
+		s.handleGeminiUpstreamError(ctx, account, resp.StatusCode, resp.Header, respBody)
+
+		// Best-effort fallback for OAuth tokens missing AI Studio scopes when calling countTokens.
+		// This avoids Gemini SDKs failing hard during preflight token counting.
+		if action == "countTokens" && isOAuth && isGeminiInsufficientScope(resp.Header, respBody) {
+			estimated := estimateGeminiCountTokens(body)
+			c.JSON(http.StatusOK, map[string]any{"totalTokens": estimated})
+			return &ForwardResult{
+				RequestID:    requestID,
+				Usage:        ClaudeUsage{},
+				Model:        originalModel,
+				Stream:       false,
+				Duration:     time.Since(startTime),
+				FirstTokenMs: nil,
+			}, nil
+		}
+
+		respBody = unwrapIfNeeded(isOAuth, respBody)
+		contentType := resp.Header.Get("Content-Type")
+		if contentType == "" {
+			contentType = "application/json"
+		}
+		c.Data(resp.StatusCode, contentType, respBody)
+		return nil, fmt.Errorf("gemini upstream error: %d", resp.StatusCode)
+	}
+
+	var usage *ClaudeUsage
+	var firstTokenMs *int
+
+	if stream {
+		streamRes, err := s.handleNativeStreamingResponse(c, resp, startTime, isOAuth)
+		if err != nil {
+			return nil, err
+		}
+		usage = streamRes.usage
+		firstTokenMs = streamRes.firstTokenMs
+	} else {
+		if useUpstreamStream {
+			collected, usageObj, err := collectGeminiSSE(resp.Body, isOAuth)
+			if err != nil {
+				return nil, s.writeGoogleError(c, http.StatusBadGateway, "Failed to read upstream stream")
+			}
+			b, _ := json.Marshal(collected)
+			c.Data(http.StatusOK, "application/json", b)
+			usage = usageObj
+		} else {
+			usageResp, err := s.handleNativeNonStreamingResponse(c, resp, isOAuth)
+			if err != nil {
+				return nil, err
+			}
+			usage = usageResp
+		}
+	}
+
+	if usage == nil {
+		usage = &ClaudeUsage{}
+	}
+
+	return &ForwardResult{
+		RequestID:    requestID,
+		Usage:        *usage,
+		Model:        originalModel,
+		Stream:       stream,
+		Duration:     time.Since(startTime),
+		FirstTokenMs: firstTokenMs,
+	}, nil
+}
+
+func (s *GeminiMessagesCompatService) shouldRetryGeminiUpstreamError(account *Account, statusCode int) bool {
+	switch statusCode {
+	case 429, 500, 502, 503, 504, 529:
+		return true
+	case 403:
+		// GeminiCli OAuth occasionally returns 403 transiently (activation/quota propagation); allow retry.
+		if account == nil || account.Type != AccountTypeOAuth {
+			return false
+		}
+		oauthType := strings.ToLower(strings.TrimSpace(account.GetCredential("oauth_type")))
+		if oauthType == "" && strings.TrimSpace(account.GetCredential("project_id")) != "" {
+			// Legacy/implicit Code Assist OAuth accounts.
+			oauthType = "code_assist"
+		}
+		return oauthType == "code_assist"
+	default:
+		return false
+	}
+}
+
+func sleepGeminiBackoff(attempt int) {
+	delay := geminiRetryBaseDelay * time.Duration(1<<uint(attempt-1))
+	if delay > geminiRetryMaxDelay {
+		delay = geminiRetryMaxDelay
+	}
+
+	// +/- 20% jitter
+	r := mathrand.New(mathrand.NewSource(time.Now().UnixNano()))
+	jitter := time.Duration(float64(delay) * 0.2 * (r.Float64()*2 - 1))
+	sleepFor := delay + jitter
+	if sleepFor < 0 {
+		sleepFor = 0
+	}
+	time.Sleep(sleepFor)
+}
+
+var sensitiveQueryParamRegex = regexp.MustCompile(`(?i)([?&](?:key|client_secret|access_token|refresh_token)=)[^&"\s]+`)
+
+func sanitizeUpstreamErrorMessage(msg string) string {
+	if msg == "" {
+		return msg
+	}
+	return sensitiveQueryParamRegex.ReplaceAllString(msg, `$1***`)
+}
+
+func (s *GeminiMessagesCompatService) writeGeminiMappedError(c *gin.Context, upstreamStatus int, body []byte) error {
+	var statusCode int
+	var errType, errMsg string
+
+	if mapped := mapGeminiErrorBodyToClaudeError(body); mapped != nil {
+		errType = mapped.Type
+		if mapped.Message != "" {
+			errMsg = mapped.Message
+		}
+		if mapped.StatusCode > 0 {
+			statusCode = mapped.StatusCode
+		}
+	}
+
+	switch upstreamStatus {
+	case 400:
+		if statusCode == 0 {
+			statusCode = http.StatusBadRequest
+		}
+		if errType == "" {
+			errType = "invalid_request_error"
+		}
+		if errMsg == "" {
+			errMsg = "Invalid request"
+		}
+	case 401:
+		if statusCode == 0 {
+			statusCode = http.StatusBadGateway
+		}
+		if errType == "" {
+			errType = "authentication_error"
+		}
+		if errMsg == "" {
+			errMsg = "Upstream authentication failed, please contact administrator"
+		}
+	case 403:
+		if statusCode == 0 {
+			statusCode = http.StatusBadGateway
+		}
+		if errType == "" {
+			errType = "permission_error"
+		}
+		if errMsg == "" {
+			errMsg = "Upstream access forbidden, please contact administrator"
+		}
+	case 404:
+		if statusCode == 0 {
+			statusCode = http.StatusNotFound
+		}
+		if errType == "" {
+			errType = "not_found_error"
+		}
+		if errMsg == "" {
+			errMsg = "Resource not found"
+		}
+	case 429:
+		if statusCode == 0 {
+			statusCode = http.StatusTooManyRequests
+		}
+		if errType == "" {
+			errType = "rate_limit_error"
+		}
+		if errMsg == "" {
+			errMsg = "Upstream rate limit exceeded, please retry later"
+		}
+	case 529:
+		if statusCode == 0 {
+			statusCode = http.StatusServiceUnavailable
+		}
+		if errType == "" {
+			errType = "overloaded_error"
+		}
+		if errMsg == "" {
+			errMsg = "Upstream service overloaded, please retry later"
+		}
+	case 500, 502, 503, 504:
+		if statusCode == 0 {
+			statusCode = http.StatusBadGateway
+		}
+		if errType == "" {
+			switch upstreamStatus {
+			case 504:
+				errType = "timeout_error"
+			case 503:
+				errType = "overloaded_error"
+			default:
+				errType = "api_error"
+			}
+		}
+		if errMsg == "" {
+			errMsg = "Upstream service temporarily unavailable"
+		}
+	default:
+		if statusCode == 0 {
+			statusCode = http.StatusBadGateway
+		}
+		if errType == "" {
+			errType = "upstream_error"
+		}
+		if errMsg == "" {
+			errMsg = "Upstream request failed"
+		}
+	}
+
+	c.JSON(statusCode, gin.H{
+		"type":  "error",
+		"error": gin.H{"type": errType, "message": errMsg},
+	})
+	return fmt.Errorf("upstream error: %d", upstreamStatus)
+}
+
+type claudeErrorMapping struct {
+	Type       string
+	Message    string
+	StatusCode int
+}
+
+func mapGeminiErrorBodyToClaudeError(body []byte) *claudeErrorMapping {
+	if len(body) == 0 {
+		return nil
+	}
+
+	var parsed struct {
+		Error struct {
+			Code    int    `json:"code"`
+			Message string `json:"message"`
+			Status  string `json:"status"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal(body, &parsed); err != nil {
+		return nil
+	}
+	if strings.TrimSpace(parsed.Error.Status) == "" && parsed.Error.Code == 0 && strings.TrimSpace(parsed.Error.Message) == "" {
+		return nil
+	}
+
+	mapped := &claudeErrorMapping{
+		Type:    mapGeminiStatusToClaudeErrorType(parsed.Error.Status),
+		Message: "",
+	}
+	if mapped.Type == "" {
+		mapped.Type = "upstream_error"
+	}
+
+	switch strings.ToUpper(strings.TrimSpace(parsed.Error.Status)) {
+	case "INVALID_ARGUMENT":
+		mapped.StatusCode = http.StatusBadRequest
+	case "NOT_FOUND":
+		mapped.StatusCode = http.StatusNotFound
+	case "RESOURCE_EXHAUSTED":
+		mapped.StatusCode = http.StatusTooManyRequests
+	default:
+		// Keep StatusCode unset and let HTTP status mapping decide.
+	}
+
+	// Keep messages generic by default; upstream error message can be long or include sensitive fragments.
+	return mapped
+}
+
+func mapGeminiStatusToClaudeErrorType(status string) string {
+	switch strings.ToUpper(strings.TrimSpace(status)) {
+	case "INVALID_ARGUMENT":
+		return "invalid_request_error"
+	case "PERMISSION_DENIED":
+		return "permission_error"
+	case "NOT_FOUND":
+		return "not_found_error"
+	case "RESOURCE_EXHAUSTED":
+		return "rate_limit_error"
+	case "UNAUTHENTICATED":
+		return "authentication_error"
+	case "UNAVAILABLE":
+		return "overloaded_error"
+	case "INTERNAL":
+		return "api_error"
+	case "DEADLINE_EXCEEDED":
+		return "timeout_error"
+	default:
+		return ""
+	}
+}
+
+type geminiStreamResult struct {
+	usage        *ClaudeUsage
+	firstTokenMs *int
+}
+
+func (s *GeminiMessagesCompatService) handleNonStreamingResponse(c *gin.Context, resp *http.Response, originalModel string) (*ClaudeUsage, error) {
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 8<<20))
+	if err != nil {
+		return nil, s.writeClaudeError(c, http.StatusBadGateway, "upstream_error", "Failed to read upstream response")
+	}
+
+	geminiResp, err := unwrapGeminiResponse(body)
+	if err != nil {
+		return nil, s.writeClaudeError(c, http.StatusBadGateway, "upstream_error", "Failed to parse upstream response")
+	}
+
+	claudeResp, usage := convertGeminiToClaudeMessage(geminiResp, originalModel)
+	c.JSON(http.StatusOK, claudeResp)
+
+	return usage, nil
+}
+
+func (s *GeminiMessagesCompatService) handleStreamingResponse(c *gin.Context, resp *http.Response, startTime time.Time, originalModel string) (*geminiStreamResult, error) {
+	c.Header("Content-Type", "text/event-stream")
+	c.Header("Cache-Control", "no-cache")
+	c.Header("Connection", "keep-alive")
+	c.Header("X-Accel-Buffering", "no")
+	c.Status(http.StatusOK)
+
+	flusher, ok := c.Writer.(http.Flusher)
+	if !ok {
+		return nil, errors.New("streaming not supported")
+	}
+
+	messageID := "msg_" + randomHex(12)
+	messageStart := map[string]any{
+		"type": "message_start",
+		"message": map[string]any{
+			"id":            messageID,
+			"type":          "message",
+			"role":          "assistant",
+			"model":         originalModel,
+			"content":       []any{},
+			"stop_reason":   nil,
+			"stop_sequence": nil,
+			"usage": map[string]any{
+				"input_tokens":  0,
+				"output_tokens": 0,
+			},
+		},
+	}
+	writeSSE(c.Writer, "message_start", messageStart)
+	flusher.Flush()
+
+	var firstTokenMs *int
+	var usage ClaudeUsage
+	finishReason := ""
+	sawToolUse := false
+
+	nextBlockIndex := 0
+	openBlockIndex := -1
+	openBlockType := ""
+	seenText := ""
+	openToolIndex := -1
+	openToolID := ""
+	openToolName := ""
+	seenToolJSON := ""
+
+	reader := bufio.NewReader(resp.Body)
+	for {
+		line, err := reader.ReadString('\n')
+		if err != nil && !errors.Is(err, io.EOF) {
+			return nil, fmt.Errorf("stream read error: %w", err)
+		}
+
+		if !strings.HasPrefix(line, "data:") {
+			if errors.Is(err, io.EOF) {
+				break
+			}
+			continue
+		}
+		payload := strings.TrimSpace(strings.TrimPrefix(line, "data:"))
+		if payload == "" || payload == "[DONE]" {
+			if errors.Is(err, io.EOF) {
+				break
+			}
+			continue
+		}
+
+		geminiResp, err := unwrapGeminiResponse([]byte(payload))
+		if err != nil {
+			continue
+		}
+
+		if fr := extractGeminiFinishReason(geminiResp); fr != "" {
+			finishReason = fr
+		}
+
+		parts := extractGeminiParts(geminiResp)
+		for _, part := range parts {
+			if text, ok := part["text"].(string); ok && text != "" {
+				delta, newSeen := computeGeminiTextDelta(seenText, text)
+				seenText = newSeen
+				if delta == "" {
+					continue
+				}
+
+				if openBlockType != "text" {
+					if openBlockIndex >= 0 {
+						writeSSE(c.Writer, "content_block_stop", map[string]any{
+							"type":  "content_block_stop",
+							"index": openBlockIndex,
+						})
+					}
+					openBlockType = "text"
+					openBlockIndex = nextBlockIndex
+					nextBlockIndex++
+					writeSSE(c.Writer, "content_block_start", map[string]any{
+						"type":  "content_block_start",
+						"index": openBlockIndex,
+						"content_block": map[string]any{
+							"type": "text",
+							"text": "",
+						},
+					})
+				}
+
+				if firstTokenMs == nil {
+					ms := int(time.Since(startTime).Milliseconds())
+					firstTokenMs = &ms
+				}
+				writeSSE(c.Writer, "content_block_delta", map[string]any{
+					"type":  "content_block_delta",
+					"index": openBlockIndex,
+					"delta": map[string]any{
+						"type": "text_delta",
+						"text": delta,
+					},
+				})
+				flusher.Flush()
+				continue
+			}
+
+			if fc, ok := part["functionCall"].(map[string]any); ok && fc != nil {
+				name, _ := fc["name"].(string)
+				args := fc["args"]
+				if strings.TrimSpace(name) == "" {
+					name = "tool"
+				}
+
+				// Close any open text block before tool_use.
+				if openBlockIndex >= 0 {
+					writeSSE(c.Writer, "content_block_stop", map[string]any{
+						"type":  "content_block_stop",
+						"index": openBlockIndex,
+					})
+					openBlockIndex = -1
+					openBlockType = ""
+				}
+
+				// If we receive streamed tool args in pieces, keep a single tool block open and emit deltas.
+				if openToolIndex >= 0 && openToolName != name {
+					writeSSE(c.Writer, "content_block_stop", map[string]any{
+						"type":  "content_block_stop",
+						"index": openToolIndex,
+					})
+					openToolIndex = -1
+					openToolName = ""
+					seenToolJSON = ""
+				}
+
+				if openToolIndex < 0 {
+					openToolID = "toolu_" + randomHex(8)
+					openToolIndex = nextBlockIndex
+					openToolName = name
+					nextBlockIndex++
+					sawToolUse = true
+
+					writeSSE(c.Writer, "content_block_start", map[string]any{
+						"type":  "content_block_start",
+						"index": openToolIndex,
+						"content_block": map[string]any{
+							"type":  "tool_use",
+							"id":    openToolID,
+							"name":  name,
+							"input": map[string]any{},
+						},
+					})
+				}
+
+				argsJSONText := "{}"
+				switch v := args.(type) {
+				case nil:
+					// keep default "{}"
+				case string:
+					if strings.TrimSpace(v) != "" {
+						argsJSONText = v
+					}
+				default:
+					if b, err := json.Marshal(args); err == nil && len(b) > 0 {
+						argsJSONText = string(b)
+					}
+				}
+
+				delta, newSeen := computeGeminiTextDelta(seenToolJSON, argsJSONText)
+				seenToolJSON = newSeen
+				if delta != "" {
+					writeSSE(c.Writer, "content_block_delta", map[string]any{
+						"type":  "content_block_delta",
+						"index": openToolIndex,
+						"delta": map[string]any{
+							"type":         "input_json_delta",
+							"partial_json": delta,
+						},
+					})
+				}
+				flusher.Flush()
+			}
+		}
+
+		if u := extractGeminiUsage(geminiResp); u != nil {
+			usage = *u
+		}
+
+		// Process the final unterminated line at EOF as well.
+		if errors.Is(err, io.EOF) {
+			break
+		}
+	}
+
+	if openBlockIndex >= 0 {
+		writeSSE(c.Writer, "content_block_stop", map[string]any{
+			"type":  "content_block_stop",
+			"index": openBlockIndex,
+		})
+	}
+	if openToolIndex >= 0 {
+		writeSSE(c.Writer, "content_block_stop", map[string]any{
+			"type":  "content_block_stop",
+			"index": openToolIndex,
+		})
+	}
+
+	stopReason := mapGeminiFinishReasonToClaudeStopReason(finishReason)
+	if sawToolUse {
+		stopReason = "tool_use"
+	}
+
+	usageObj := map[string]any{
+		"output_tokens": usage.OutputTokens,
+	}
+	if usage.InputTokens > 0 {
+		usageObj["input_tokens"] = usage.InputTokens
+	}
+	writeSSE(c.Writer, "message_delta", map[string]any{
+		"type": "message_delta",
+		"delta": map[string]any{
+			"stop_reason":   stopReason,
+			"stop_sequence": nil,
+		},
+		"usage": usageObj,
+	})
+	writeSSE(c.Writer, "message_stop", map[string]any{
+		"type": "message_stop",
+	})
+	flusher.Flush()
+
+	return &geminiStreamResult{usage: &usage, firstTokenMs: firstTokenMs}, nil
+}
+
+func writeSSE(w io.Writer, event string, data any) {
+	if event != "" {
+		_, _ = fmt.Fprintf(w, "event: %s\n", event)
+	}
+	b, _ := json.Marshal(data)
+	_, _ = fmt.Fprintf(w, "data: %s\n\n", string(b))
+}
+
+func randomHex(nBytes int) string {
+	b := make([]byte, nBytes)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)
+}
+
+func (s *GeminiMessagesCompatService) writeClaudeError(c *gin.Context, status int, errType, message string) error {
+	c.JSON(status, gin.H{
+		"type":  "error",
+		"error": gin.H{"type": errType, "message": message},
+	})
+	return fmt.Errorf("%s", message)
+}
+
+func (s *GeminiMessagesCompatService) writeGoogleError(c *gin.Context, status int, message string) error {
+	c.JSON(status, gin.H{
+		"error": gin.H{
+			"code":    status,
+			"message": message,
+			"status":  googleapi.HTTPStatusToGoogleStatus(status),
+		},
+	})
+	return fmt.Errorf("%s", message)
+}
+
+func unwrapIfNeeded(isOAuth bool, raw []byte) []byte {
+	if !isOAuth {
+		return raw
+	}
+	inner, err := unwrapGeminiResponse(raw)
+	if err != nil {
+		return raw
+	}
+	b, err := json.Marshal(inner)
+	if err != nil {
+		return raw
+	}
+	return b
+}
+
+func collectGeminiSSE(body io.Reader, isOAuth bool) (map[string]any, *ClaudeUsage, error) {
+	reader := bufio.NewReader(body)
+
+	var last map[string]any
+	var lastWithParts map[string]any
+	usage := &ClaudeUsage{}
+
+	for {
+		line, err := reader.ReadString('\n')
+		if len(line) > 0 {
+			trimmed := strings.TrimRight(line, "\r\n")
+			if strings.HasPrefix(trimmed, "data:") {
+				payload := strings.TrimSpace(strings.TrimPrefix(trimmed, "data:"))
+				switch payload {
+				case "", "[DONE]":
+					if payload == "[DONE]" {
+						return pickGeminiCollectResult(last, lastWithParts), usage, nil
+					}
+				default:
+					var parsed map[string]any
+					if isOAuth {
+						inner, err := unwrapGeminiResponse([]byte(payload))
+						if err == nil && inner != nil {
+							parsed = inner
+						}
+					} else {
+						_ = json.Unmarshal([]byte(payload), &parsed)
+					}
+					if parsed != nil {
+						last = parsed
+						if u := extractGeminiUsage(parsed); u != nil {
+							usage = u
+						}
+						if parts := extractGeminiParts(parsed); len(parts) > 0 {
+							lastWithParts = parsed
+						}
+					}
+				}
+			}
+		}
+
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return nil, nil, err
+		}
+	}
+
+	return pickGeminiCollectResult(last, lastWithParts), usage, nil
+}
+
+func pickGeminiCollectResult(last map[string]any, lastWithParts map[string]any) map[string]any {
+	if lastWithParts != nil {
+		return lastWithParts
+	}
+	if last != nil {
+		return last
+	}
+	return map[string]any{}
+}
+
+type geminiNativeStreamResult struct {
+	usage        *ClaudeUsage
+	firstTokenMs *int
+}
+
+func isGeminiInsufficientScope(headers http.Header, body []byte) bool {
+	if strings.Contains(strings.ToLower(headers.Get("Www-Authenticate")), "insufficient_scope") {
+		return true
+	}
+	lower := strings.ToLower(string(body))
+	return strings.Contains(lower, "insufficient authentication scopes") || strings.Contains(lower, "access_token_scope_insufficient")
+}
+
+func estimateGeminiCountTokens(reqBody []byte) int {
+	var obj map[string]any
+	if err := json.Unmarshal(reqBody, &obj); err != nil {
+		return 0
+	}
+
+	var texts []string
+
+	// systemInstruction.parts[].text
+	if si, ok := obj["systemInstruction"].(map[string]any); ok {
+		if parts, ok := si["parts"].([]any); ok {
+			for _, p := range parts {
+				if pm, ok := p.(map[string]any); ok {
+					if t, ok := pm["text"].(string); ok && strings.TrimSpace(t) != "" {
+						texts = append(texts, t)
+					}
+				}
+			}
+		}
+	}
+
+	// contents[].parts[].text
+	if contents, ok := obj["contents"].([]any); ok {
+		for _, c := range contents {
+			cm, ok := c.(map[string]any)
+			if !ok {
+				continue
+			}
+			parts, ok := cm["parts"].([]any)
+			if !ok {
+				continue
+			}
+			for _, p := range parts {
+				pm, ok := p.(map[string]any)
+				if !ok {
+					continue
+				}
+				if t, ok := pm["text"].(string); ok && strings.TrimSpace(t) != "" {
+					texts = append(texts, t)
+				}
+			}
+		}
+	}
+
+	total := 0
+	for _, t := range texts {
+		total += estimateTokensForText(t)
+	}
+	if total < 0 {
+		return 0
+	}
+	return total
+}
+
+func estimateTokensForText(s string) int {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return 0
+	}
+	runes := []rune(s)
+	if len(runes) == 0 {
+		return 0
+	}
+	ascii := 0
+	for _, r := range runes {
+		if r <= 0x7f {
+			ascii++
+		}
+	}
+	asciiRatio := float64(ascii) / float64(len(runes))
+	if asciiRatio >= 0.8 {
+		// Roughly 4 chars per token for English-like text.
+		return (len(runes) + 3) / 4
+	}
+	// For CJK-heavy text, approximate 1 rune per token.
+	return len(runes)
+}
+
+type UpstreamHTTPResult struct {
+	StatusCode int
+	Headers    http.Header
+	Body       []byte
+}
+
+func (s *GeminiMessagesCompatService) handleNativeNonStreamingResponse(c *gin.Context, resp *http.Response, isOAuth bool) (*ClaudeUsage, error) {
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+
+	var parsed map[string]any
+	if isOAuth {
+		parsed, err = unwrapGeminiResponse(respBody)
+		if err == nil && parsed != nil {
+			respBody, _ = json.Marshal(parsed)
+		}
+	} else {
+		_ = json.Unmarshal(respBody, &parsed)
+	}
+
+	contentType := resp.Header.Get("Content-Type")
+	if contentType == "" {
+		contentType = "application/json"
+	}
+	c.Data(resp.StatusCode, contentType, respBody)
+
+	if parsed != nil {
+		if u := extractGeminiUsage(parsed); u != nil {
+			return u, nil
+		}
+	}
+	return &ClaudeUsage{}, nil
+}
+
+func (s *GeminiMessagesCompatService) handleNativeStreamingResponse(c *gin.Context, resp *http.Response, startTime time.Time, isOAuth bool) (*geminiNativeStreamResult, error) {
+	c.Status(resp.StatusCode)
+	c.Header("Cache-Control", "no-cache")
+	c.Header("Connection", "keep-alive")
+	c.Header("X-Accel-Buffering", "no")
+
+	contentType := resp.Header.Get("Content-Type")
+	if contentType == "" {
+		contentType = "text/event-stream; charset=utf-8"
+	}
+	c.Header("Content-Type", contentType)
+
+	flusher, ok := c.Writer.(http.Flusher)
+	if !ok {
+		return nil, errors.New("streaming not supported")
+	}
+
+	reader := bufio.NewReader(resp.Body)
+	usage := &ClaudeUsage{}
+	var firstTokenMs *int
+
+	for {
+		line, err := reader.ReadString('\n')
+		if len(line) > 0 {
+			trimmed := strings.TrimRight(line, "\r\n")
+			if strings.HasPrefix(trimmed, "data:") {
+				payload := strings.TrimSpace(strings.TrimPrefix(trimmed, "data:"))
+				// Keepalive / done markers
+				if payload == "" || payload == "[DONE]" {
+					_, _ = io.WriteString(c.Writer, line)
+					flusher.Flush()
+				} else {
+					var rawToWrite string
+					rawToWrite = payload
+
+					var parsed map[string]any
+					if isOAuth {
+						inner, err := unwrapGeminiResponse([]byte(payload))
+						if err == nil && inner != nil {
+							parsed = inner
+							if b, err := json.Marshal(inner); err == nil {
+								rawToWrite = string(b)
+							}
+						}
+					} else {
+						_ = json.Unmarshal([]byte(payload), &parsed)
+					}
+
+					if parsed != nil {
+						if u := extractGeminiUsage(parsed); u != nil {
+							usage = u
+						}
+					}
+
+					if firstTokenMs == nil {
+						ms := int(time.Since(startTime).Milliseconds())
+						firstTokenMs = &ms
+					}
+
+					if isOAuth {
+						// SSE format requires double newline (\n\n) to separate events
+						_, _ = fmt.Fprintf(c.Writer, "data: %s\n\n", rawToWrite)
+					} else {
+						// Pass-through for AI Studio responses.
+						_, _ = io.WriteString(c.Writer, line)
+					}
+					flusher.Flush()
+				}
+			} else {
+				_, _ = io.WriteString(c.Writer, line)
+				flusher.Flush()
+			}
+		}
+
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	return &geminiNativeStreamResult{usage: usage, firstTokenMs: firstTokenMs}, nil
+}
+
+// ForwardAIStudioGET forwards a GET request to AI Studio (generativelanguage.googleapis.com) for
+// endpoints like /v1beta/models and /v1beta/models/{model}.
+//
+// This is used to support Gemini SDKs that call models listing endpoints before generation.
+func (s *GeminiMessagesCompatService) ForwardAIStudioGET(ctx context.Context, account *Account, path string) (*UpstreamHTTPResult, error) {
+	if account == nil {
+		return nil, errors.New("account is nil")
+	}
+	path = strings.TrimSpace(path)
+	if path == "" || !strings.HasPrefix(path, "/") {
+		return nil, errors.New("invalid path")
+	}
+
+	baseURL := strings.TrimRight(account.GetCredential("base_url"), "/")
+	if baseURL == "" {
+		baseURL = geminicli.AIStudioBaseURL
+	}
+	fullURL := strings.TrimRight(baseURL, "/") + path
+
+	var proxyURL string
+	if account.ProxyID != nil && account.Proxy != nil {
+		proxyURL = account.Proxy.URL()
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, fullURL, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	switch account.Type {
+	case AccountTypeApiKey:
+		apiKey := strings.TrimSpace(account.GetCredential("api_key"))
+		if apiKey == "" {
+			return nil, errors.New("gemini api_key not configured")
+		}
+		req.Header.Set("x-goog-api-key", apiKey)
+	case AccountTypeOAuth:
+		if s.tokenProvider == nil {
+			return nil, errors.New("gemini token provider not configured")
+		}
+		accessToken, err := s.tokenProvider.GetAccessToken(ctx, account)
+		if err != nil {
+			return nil, err
+		}
+		req.Header.Set("Authorization", "Bearer "+accessToken)
+	default:
+		return nil, fmt.Errorf("unsupported account type: %s", account.Type)
+	}
+
+	resp, err := s.httpUpstream.Do(req, proxyURL)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 8<<20))
+	return &UpstreamHTTPResult{
+		StatusCode: resp.StatusCode,
+		Headers:    resp.Header.Clone(),
+		Body:       body,
+	}, nil
+}
+
+func unwrapGeminiResponse(raw []byte) (map[string]any, error) {
+	var outer map[string]any
+	if err := json.Unmarshal(raw, &outer); err != nil {
+		return nil, err
+	}
+	if resp, ok := outer["response"].(map[string]any); ok && resp != nil {
+		return resp, nil
+	}
+	return outer, nil
+}
+
+func convertGeminiToClaudeMessage(geminiResp map[string]any, originalModel string) (map[string]any, *ClaudeUsage) {
+	usage := extractGeminiUsage(geminiResp)
+	if usage == nil {
+		usage = &ClaudeUsage{}
+	}
+
+	contentBlocks := make([]any, 0)
+	sawToolUse := false
+	if candidates, ok := geminiResp["candidates"].([]any); ok && len(candidates) > 0 {
+		if cand, ok := candidates[0].(map[string]any); ok {
+			if content, ok := cand["content"].(map[string]any); ok {
+				if parts, ok := content["parts"].([]any); ok {
+					for _, part := range parts {
+						pm, ok := part.(map[string]any)
+						if !ok {
+							continue
+						}
+						if text, ok := pm["text"].(string); ok && text != "" {
+							contentBlocks = append(contentBlocks, map[string]any{
+								"type": "text",
+								"text": text,
+							})
+						}
+						if fc, ok := pm["functionCall"].(map[string]any); ok {
+							name, _ := fc["name"].(string)
+							if strings.TrimSpace(name) == "" {
+								name = "tool"
+							}
+							args := fc["args"]
+							sawToolUse = true
+							contentBlocks = append(contentBlocks, map[string]any{
+								"type":  "tool_use",
+								"id":    "toolu_" + randomHex(8),
+								"name":  name,
+								"input": args,
+							})
+						}
+					}
+				}
+			}
+		}
+	}
+
+	stopReason := mapGeminiFinishReasonToClaudeStopReason(extractGeminiFinishReason(geminiResp))
+	if sawToolUse {
+		stopReason = "tool_use"
+	}
+
+	resp := map[string]any{
+		"id":            "msg_" + randomHex(12),
+		"type":          "message",
+		"role":          "assistant",
+		"model":         originalModel,
+		"content":       contentBlocks,
+		"stop_reason":   stopReason,
+		"stop_sequence": nil,
+		"usage": map[string]any{
+			"input_tokens":  usage.InputTokens,
+			"output_tokens": usage.OutputTokens,
+		},
+	}
+
+	return resp, usage
+}
+
+func extractGeminiUsage(geminiResp map[string]any) *ClaudeUsage {
+	usageMeta, ok := geminiResp["usageMetadata"].(map[string]any)
+	if !ok || usageMeta == nil {
+		return nil
+	}
+	prompt, _ := asInt(usageMeta["promptTokenCount"])
+	cand, _ := asInt(usageMeta["candidatesTokenCount"])
+	return &ClaudeUsage{
+		InputTokens:  prompt,
+		OutputTokens: cand,
+	}
+}
+
+func asInt(v any) (int, bool) {
+	switch t := v.(type) {
+	case float64:
+		return int(t), true
+	case int:
+		return t, true
+	case int64:
+		return int(t), true
+	case json.Number:
+		i, err := t.Int64()
+		if err != nil {
+			return 0, false
+		}
+		return int(i), true
+	default:
+		return 0, false
+	}
+}
+
+func (s *GeminiMessagesCompatService) handleGeminiUpstreamError(ctx context.Context, account *Account, statusCode int, headers http.Header, body []byte) {
+	if s.rateLimitService != nil && (statusCode == 401 || statusCode == 403 || statusCode == 529) {
+		s.rateLimitService.HandleUpstreamError(ctx, account, statusCode, headers, body)
+		return
+	}
+	if statusCode != 429 {
+		return
+	}
+	resetAt := parseGeminiRateLimitResetTime(body)
+	if resetAt == nil {
+		ra := time.Now().Add(5 * time.Minute)
+		_ = s.accountRepo.SetRateLimited(ctx, account.ID, ra)
+		return
+	}
+	_ = s.accountRepo.SetRateLimited(ctx, account.ID, time.Unix(*resetAt, 0))
+}
+
+func parseGeminiRateLimitResetTime(body []byte) *int64 {
+	// Try to parse metadata.quotaResetDelay like "12.345s"
+	var parsed map[string]any
+	if err := json.Unmarshal(body, &parsed); err == nil {
+		if errObj, ok := parsed["error"].(map[string]any); ok {
+			if msg, ok := errObj["message"].(string); ok {
+				if looksLikeGeminiDailyQuota(msg) {
+					if ts := nextGeminiDailyResetUnix(); ts != nil {
+						return ts
+					}
+				}
+			}
+			if details, ok := errObj["details"].([]any); ok {
+				for _, d := range details {
+					dm, ok := d.(map[string]any)
+					if !ok {
+						continue
+					}
+					if meta, ok := dm["metadata"].(map[string]any); ok {
+						if v, ok := meta["quotaResetDelay"].(string); ok {
+							if dur, err := time.ParseDuration(v); err == nil {
+								ts := time.Now().Unix() + int64(dur.Seconds())
+								return &ts
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+
+	// Match "Please retry in Xs"
+	retryInRegex := regexp.MustCompile(`Please retry in ([0-9.]+)s`)
+	matches := retryInRegex.FindStringSubmatch(string(body))
+	if len(matches) == 2 {
+		if dur, err := time.ParseDuration(matches[1] + "s"); err == nil {
+			ts := time.Now().Unix() + int64(math.Ceil(dur.Seconds()))
+			return &ts
+		}
+	}
+
+	return nil
+}
+
+func looksLikeGeminiDailyQuota(message string) bool {
+	m := strings.ToLower(message)
+	if strings.Contains(m, "per day") || strings.Contains(m, "requests per day") || strings.Contains(m, "quota") && strings.Contains(m, "per day") {
+		return true
+	}
+	return false
+}
+
+func nextGeminiDailyResetUnix() *int64 {
+	loc, err := time.LoadLocation("America/Los_Angeles")
+	if err != nil {
+		// Fallback: PST without DST.
+		loc = time.FixedZone("PST", -8*3600)
+	}
+	now := time.Now().In(loc)
+	reset := time.Date(now.Year(), now.Month(), now.Day(), 0, 5, 0, 0, loc)
+	if !reset.After(now) {
+		reset = reset.Add(24 * time.Hour)
+	}
+	ts := reset.Unix()
+	return &ts
+}
+
+func extractGeminiFinishReason(geminiResp map[string]any) string {
+	if candidates, ok := geminiResp["candidates"].([]any); ok && len(candidates) > 0 {
+		if cand, ok := candidates[0].(map[string]any); ok {
+			if fr, ok := cand["finishReason"].(string); ok {
+				return fr
+			}
+		}
+	}
+	return ""
+}
+
+func extractGeminiParts(geminiResp map[string]any) []map[string]any {
+	if candidates, ok := geminiResp["candidates"].([]any); ok && len(candidates) > 0 {
+		if cand, ok := candidates[0].(map[string]any); ok {
+			if content, ok := cand["content"].(map[string]any); ok {
+				if partsAny, ok := content["parts"].([]any); ok && len(partsAny) > 0 {
+					out := make([]map[string]any, 0, len(partsAny))
+					for _, p := range partsAny {
+						pm, ok := p.(map[string]any)
+						if !ok {
+							continue
+						}
+						out = append(out, pm)
+					}
+					return out
+				}
+			}
+		}
+	}
+	return nil
+}
+
+func computeGeminiTextDelta(seen, incoming string) (delta, newSeen string) {
+	incoming = strings.TrimSuffix(incoming, "\u0000")
+	if incoming == "" {
+		return "", seen
+	}
+
+	// Cumulative mode: incoming contains full text so far.
+	if strings.HasPrefix(incoming, seen) {
+		return strings.TrimPrefix(incoming, seen), incoming
+	}
+	// Duplicate/rewind: ignore.
+	if strings.HasPrefix(seen, incoming) {
+		return "", seen
+	}
+	// Delta mode: treat incoming as incremental chunk.
+	return incoming, seen + incoming
+}
+
+func mapGeminiFinishReasonToClaudeStopReason(finishReason string) string {
+	switch strings.ToUpper(strings.TrimSpace(finishReason)) {
+	case "MAX_TOKENS":
+		return "max_tokens"
+	case "STOP":
+		return "end_turn"
+	default:
+		return "end_turn"
+	}
+}
+
+func convertClaudeMessagesToGeminiGenerateContent(body []byte) ([]byte, error) {
+	var req map[string]any
+	if err := json.Unmarshal(body, &req); err != nil {
+		return nil, err
+	}
+
+	toolUseIDToName := make(map[string]string)
+
+	systemText := extractClaudeSystemText(req["system"])
+	contents, err := convertClaudeMessagesToGeminiContents(req["messages"], toolUseIDToName)
+	if err != nil {
+		return nil, err
+	}
+
+	out := make(map[string]any)
+	if systemText != "" {
+		out["systemInstruction"] = map[string]any{
+			"parts": []any{map[string]any{"text": systemText}},
+		}
+	}
+	out["contents"] = contents
+
+	if tools := convertClaudeToolsToGeminiTools(req["tools"]); tools != nil {
+		out["tools"] = tools
+	}
+
+	generationConfig := convertClaudeGenerationConfig(req)
+	if generationConfig != nil {
+		out["generationConfig"] = generationConfig
+	}
+
+	stripGeminiFunctionIDs(out)
+	return json.Marshal(out)
+}
+
+func stripGeminiFunctionIDs(req map[string]any) {
+	// Defensive cleanup: some upstreams reject unexpected `id` fields in functionCall/functionResponse.
+	contents, ok := req["contents"].([]any)
+	if !ok {
+		return
+	}
+	for _, c := range contents {
+		cm, ok := c.(map[string]any)
+		if !ok {
+			continue
+		}
+		contentParts, ok := cm["parts"].([]any)
+		if !ok {
+			continue
+		}
+		for _, p := range contentParts {
+			pm, ok := p.(map[string]any)
+			if !ok {
+				continue
+			}
+			if fc, ok := pm["functionCall"].(map[string]any); ok && fc != nil {
+				delete(fc, "id")
+			}
+			if fr, ok := pm["functionResponse"].(map[string]any); ok && fr != nil {
+				delete(fr, "id")
+			}
+		}
+	}
+}
+
+func extractClaudeSystemText(system any) string {
+	switch v := system.(type) {
+	case string:
+		return strings.TrimSpace(v)
+	case []any:
+		var parts []string
+		for _, p := range v {
+			pm, ok := p.(map[string]any)
+			if !ok {
+				continue
+			}
+			if t, _ := pm["type"].(string); t != "text" {
+				continue
+			}
+			if text, ok := pm["text"].(string); ok && strings.TrimSpace(text) != "" {
+				parts = append(parts, text)
+			}
+		}
+		return strings.TrimSpace(strings.Join(parts, "\n"))
+	default:
+		return ""
+	}
+}
+
+func convertClaudeMessagesToGeminiContents(messages any, toolUseIDToName map[string]string) ([]any, error) {
+	arr, ok := messages.([]any)
+	if !ok {
+		return nil, errors.New("messages must be an array")
+	}
+
+	out := make([]any, 0, len(arr))
+	for _, m := range arr {
+		mm, ok := m.(map[string]any)
+		if !ok {
+			continue
+		}
+		role, _ := mm["role"].(string)
+		role = strings.ToLower(strings.TrimSpace(role))
+		gRole := "user"
+		if role == "assistant" {
+			gRole = "model"
+		}
+
+		parts := make([]any, 0)
+		switch content := mm["content"].(type) {
+		case string:
+			if strings.TrimSpace(content) != "" {
+				parts = append(parts, map[string]any{"text": content})
+			}
+		case []any:
+			for _, block := range content {
+				bm, ok := block.(map[string]any)
+				if !ok {
+					continue
+				}
+				bt, _ := bm["type"].(string)
+				switch bt {
+				case "text":
+					if text, ok := bm["text"].(string); ok && strings.TrimSpace(text) != "" {
+						parts = append(parts, map[string]any{"text": text})
+					}
+				case "tool_use":
+					id, _ := bm["id"].(string)
+					name, _ := bm["name"].(string)
+					if strings.TrimSpace(id) != "" && strings.TrimSpace(name) != "" {
+						toolUseIDToName[id] = name
+					}
+					parts = append(parts, map[string]any{
+						"functionCall": map[string]any{
+							"name": name,
+							"args": bm["input"],
+						},
+					})
+				case "tool_result":
+					toolUseID, _ := bm["tool_use_id"].(string)
+					name := toolUseIDToName[toolUseID]
+					if name == "" {
+						name = "tool"
+					}
+					parts = append(parts, map[string]any{
+						"functionResponse": map[string]any{
+							"name": name,
+							"response": map[string]any{
+								"content": extractClaudeContentText(bm["content"]),
+							},
+						},
+					})
+				case "image":
+					if src, ok := bm["source"].(map[string]any); ok {
+						if srcType, _ := src["type"].(string); srcType == "base64" {
+							mediaType, _ := src["media_type"].(string)
+							data, _ := src["data"].(string)
+							if mediaType != "" && data != "" {
+								parts = append(parts, map[string]any{
+									"inlineData": map[string]any{
+										"mimeType": mediaType,
+										"data":     data,
+									},
+								})
+							}
+						}
+					}
+				default:
+					// best-effort: preserve unknown blocks as text
+					if b, err := json.Marshal(bm); err == nil {
+						parts = append(parts, map[string]any{"text": string(b)})
+					}
+				}
+			}
+		default:
+			// ignore
+		}
+
+		out = append(out, map[string]any{
+			"role":  gRole,
+			"parts": parts,
+		})
+	}
+	return out, nil
+}
+
+func extractClaudeContentText(v any) string {
+	switch t := v.(type) {
+	case string:
+		return t
+	case []any:
+		var sb strings.Builder
+		for _, part := range t {
+			pm, ok := part.(map[string]any)
+			if !ok {
+				continue
+			}
+			if pm["type"] == "text" {
+				if text, ok := pm["text"].(string); ok {
+					_, _ = sb.WriteString(text)
+				}
+			}
+		}
+		return sb.String()
+	default:
+		b, _ := json.Marshal(t)
+		return string(b)
+	}
+}
+
+func convertClaudeToolsToGeminiTools(tools any) []any {
+	arr, ok := tools.([]any)
+	if !ok || len(arr) == 0 {
+		return nil
+	}
+
+	funcDecls := make([]any, 0, len(arr))
+	for _, t := range arr {
+		tm, ok := t.(map[string]any)
+		if !ok {
+			continue
+		}
+		name, _ := tm["name"].(string)
+		desc, _ := tm["description"].(string)
+		params := tm["input_schema"]
+		if name == "" {
+			continue
+		}
+		funcDecls = append(funcDecls, map[string]any{
+			"name":        name,
+			"description": desc,
+			"parameters":  params,
+		})
+	}
+
+	if len(funcDecls) == 0 {
+		return nil
+	}
+	return []any{
+		map[string]any{
+			"functionDeclarations": funcDecls,
+		},
+	}
+}
+
+func convertClaudeGenerationConfig(req map[string]any) map[string]any {
+	out := make(map[string]any)
+	if mt, ok := asInt(req["max_tokens"]); ok && mt > 0 {
+		out["maxOutputTokens"] = mt
+	}
+	if temp, ok := req["temperature"].(float64); ok {
+		out["temperature"] = temp
+	}
+	if topP, ok := req["top_p"].(float64); ok {
+		out["topP"] = topP
+	}
+	if stopSeq, ok := req["stop_sequences"].([]any); ok && len(stopSeq) > 0 {
+		out["stopSequences"] = stopSeq
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}

backend/internal/service/gemini_oauth.go

+package service
+
+import (
+	"context"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/geminicli"
+)
+
+// GeminiOAuthClient performs Google OAuth token exchange/refresh for Gemini integration.
+type GeminiOAuthClient interface {
+	ExchangeCode(ctx context.Context, oauthType, code, codeVerifier, redirectURI, proxyURL string) (*geminicli.TokenResponse, error)
+	RefreshToken(ctx context.Context, oauthType, refreshToken, proxyURL string) (*geminicli.TokenResponse, error)
+}

backend/internal/service/gemini_oauth_service.go

+package service
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/geminicli"
+)
+
+type GeminiOAuthService struct {
+	sessionStore *geminicli.SessionStore
+	proxyRepo    ProxyRepository
+	oauthClient  GeminiOAuthClient
+	codeAssist   GeminiCliCodeAssistClient
+	cfg          *config.Config
+}
+
+type GeminiOAuthCapabilities struct {
+	AIStudioOAuthEnabled bool     `json:"ai_studio_oauth_enabled"`
+	RequiredRedirectURIs []string `json:"required_redirect_uris"`
+}
+
+func NewGeminiOAuthService(
+	proxyRepo ProxyRepository,
+	oauthClient GeminiOAuthClient,
+	codeAssist GeminiCliCodeAssistClient,
+	cfg *config.Config,
+) *GeminiOAuthService {
+	return &GeminiOAuthService{
+		sessionStore: geminicli.NewSessionStore(),
+		proxyRepo:    proxyRepo,
+		oauthClient:  oauthClient,
+		codeAssist:   codeAssist,
+		cfg:          cfg,
+	}
+}
+
+func (s *GeminiOAuthService) GetOAuthConfig() *GeminiOAuthCapabilities {
+	// AI Studio OAuth is only enabled when the operator configures a custom OAuth client.
+	clientID := strings.TrimSpace(s.cfg.Gemini.OAuth.ClientID)
+	clientSecret := strings.TrimSpace(s.cfg.Gemini.OAuth.ClientSecret)
+	enabled := clientID != "" && clientSecret != "" &&
+		(clientID != geminicli.GeminiCLIOAuthClientID || clientSecret != geminicli.GeminiCLIOAuthClientSecret)
+
+	return &GeminiOAuthCapabilities{
+		AIStudioOAuthEnabled: enabled,
+		RequiredRedirectURIs: []string{geminicli.AIStudioOAuthRedirectURI},
+	}
+}
+
+type GeminiAuthURLResult struct {
+	AuthURL   string `json:"auth_url"`
+	SessionID string `json:"session_id"`
+	State     string `json:"state"`
+}
+
+func (s *GeminiOAuthService) GenerateAuthURL(ctx context.Context, proxyID *int64, redirectURI, projectID, oauthType string) (*GeminiAuthURLResult, error) {
+	state, err := geminicli.GenerateState()
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate state: %w", err)
+	}
+	codeVerifier, err := geminicli.GenerateCodeVerifier()
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate code verifier: %w", err)
+	}
+	codeChallenge := geminicli.GenerateCodeChallenge(codeVerifier)
+	sessionID, err := geminicli.GenerateSessionID()
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate session ID: %w", err)
+	}
+
+	var proxyURL string
+	if proxyID != nil {
+		proxy, err := s.proxyRepo.GetByID(ctx, *proxyID)
+		if err == nil && proxy != nil {
+			proxyURL = proxy.URL()
+		}
+	}
+
+	// OAuth client selection:
+	// - code_assist: always use built-in Gemini CLI OAuth client (public), regardless of configured client_id/secret.
+	// - ai_studio: requires a user-provided OAuth client.
+	oauthCfg := geminicli.OAuthConfig{
+		ClientID:     s.cfg.Gemini.OAuth.ClientID,
+		ClientSecret: s.cfg.Gemini.OAuth.ClientSecret,
+		Scopes:       s.cfg.Gemini.OAuth.Scopes,
+	}
+	if oauthType == "code_assist" {
+		oauthCfg.ClientID = ""
+		oauthCfg.ClientSecret = ""
+	}
+
+	session := &geminicli.OAuthSession{
+		State:        state,
+		CodeVerifier: codeVerifier,
+		ProxyURL:     proxyURL,
+		RedirectURI:  redirectURI,
+		ProjectID:    strings.TrimSpace(projectID),
+		OAuthType:    oauthType,
+		CreatedAt:    time.Now(),
+	}
+	s.sessionStore.Set(sessionID, session)
+
+	effectiveCfg, err := geminicli.EffectiveOAuthConfig(oauthCfg, oauthType)
+	if err != nil {
+		return nil, err
+	}
+
+	isBuiltinClient := effectiveCfg.ClientID == geminicli.GeminiCLIOAuthClientID &&
+		effectiveCfg.ClientSecret == geminicli.GeminiCLIOAuthClientSecret
+
+	// AI Studio OAuth requires a user-provided OAuth client (built-in Gemini CLI client is scope-restricted).
+	if oauthType == "ai_studio" && isBuiltinClient {
+		return nil, fmt.Errorf("AI Studio OAuth requires a custom OAuth Client (GEMINI_OAUTH_CLIENT_ID / GEMINI_OAUTH_CLIENT_SECRET). If you don't want to configure an OAuth client, please use an AI Studio API Key account instead")
+	}
+
+	// Redirect URI strategy:
+	// - code_assist: use Gemini CLI redirect URI (codeassist.google.com/authcode)
+	// - ai_studio: use localhost callback for manual copy/paste flow
+	if oauthType == "code_assist" {
+		redirectURI = geminicli.GeminiCLIRedirectURI
+	} else {
+		redirectURI = geminicli.AIStudioOAuthRedirectURI
+	}
+	session.RedirectURI = redirectURI
+	s.sessionStore.Set(sessionID, session)
+
+	authURL, err := geminicli.BuildAuthorizationURL(effectiveCfg, state, codeChallenge, redirectURI, session.ProjectID, oauthType)
+	if err != nil {
+		return nil, err
+	}
+
+	return &GeminiAuthURLResult{
+		AuthURL:   authURL,
+		SessionID: sessionID,
+		State:     state,
+	}, nil
+}
+
+type GeminiExchangeCodeInput struct {
+	SessionID string
+	State     string
+	Code      string
+	ProxyID   *int64
+	OAuthType string // "code_assist" 或 "ai_studio"
+}
+
+type GeminiTokenInfo struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+	ExpiresIn    int64  `json:"expires_in"`
+	ExpiresAt    int64  `json:"expires_at"`
+	TokenType    string `json:"token_type"`
+	Scope        string `json:"scope,omitempty"`
+	ProjectID    string `json:"project_id,omitempty"`
+	OAuthType    string `json:"oauth_type,omitempty"` // "code_assist" 或 "ai_studio"
+}
+
+func (s *GeminiOAuthService) ExchangeCode(ctx context.Context, input *GeminiExchangeCodeInput) (*GeminiTokenInfo, error) {
+	session, ok := s.sessionStore.Get(input.SessionID)
+	if !ok {
+		return nil, fmt.Errorf("session not found or expired")
+	}
+	if strings.TrimSpace(input.State) == "" || input.State != session.State {
+		return nil, fmt.Errorf("invalid state")
+	}
+
+	proxyURL := session.ProxyURL
+	if input.ProxyID != nil {
+		proxy, err := s.proxyRepo.GetByID(ctx, *input.ProxyID)
+		if err == nil && proxy != nil {
+			proxyURL = proxy.URL()
+		}
+	}
+
+	redirectURI := session.RedirectURI
+
+	// Resolve oauth_type early (defaults to code_assist for backward compatibility).
+	oauthType := session.OAuthType
+	if oauthType == "" {
+		oauthType = "code_assist"
+	}
+
+	// If the session was created for AI Studio OAuth, ensure a custom OAuth client is configured.
+	if oauthType == "ai_studio" {
+		effectiveCfg, err := geminicli.EffectiveOAuthConfig(geminicli.OAuthConfig{
+			ClientID:     s.cfg.Gemini.OAuth.ClientID,
+			ClientSecret: s.cfg.Gemini.OAuth.ClientSecret,
+			Scopes:       s.cfg.Gemini.OAuth.Scopes,
+		}, "ai_studio")
+		if err != nil {
+			return nil, err
+		}
+		isBuiltinClient := effectiveCfg.ClientID == geminicli.GeminiCLIOAuthClientID &&
+			effectiveCfg.ClientSecret == geminicli.GeminiCLIOAuthClientSecret
+		if isBuiltinClient {
+			return nil, fmt.Errorf("AI Studio OAuth requires a custom OAuth Client. Please use an AI Studio API Key account, or configure GEMINI_OAUTH_CLIENT_ID / GEMINI_OAUTH_CLIENT_SECRET and re-authorize")
+		}
+	}
+
+	// code_assist always uses the built-in client and its fixed redirect URI.
+	if oauthType == "code_assist" {
+		redirectURI = geminicli.GeminiCLIRedirectURI
+	}
+
+	tokenResp, err := s.oauthClient.ExchangeCode(ctx, oauthType, input.Code, session.CodeVerifier, redirectURI, proxyURL)
+	if err != nil {
+		return nil, fmt.Errorf("failed to exchange code: %w", err)
+	}
+	sessionProjectID := strings.TrimSpace(session.ProjectID)
+	s.sessionStore.Delete(input.SessionID)
+
+	// 计算过期时间时减去 5 分钟安全时间窗口,考虑网络延迟和时钟偏差
+	expiresAt := time.Now().Unix() + tokenResp.ExpiresIn - 300
+
+	projectID := sessionProjectID
+
+	// 对于 code_assist 模式，project_id 是必需的
+	// 对于 ai_studio 模式，project_id 是可选的（不影响使用 AI Studio API）
+	if oauthType == "code_assist" {
+		if projectID == "" {
+			var err error
+			projectID, err = s.fetchProjectID(ctx, tokenResp.AccessToken, proxyURL)
+			if err != nil {
+				// 记录警告但不阻断流程，允许后续补充 project_id
+				fmt.Printf("[GeminiOAuth] Warning: Failed to fetch project_id during token exchange: %v\n", err)
+			}
+		}
+		if strings.TrimSpace(projectID) == "" {
+			return nil, fmt.Errorf("missing project_id for Code Assist OAuth: please fill Project ID (optional field) and regenerate the auth URL, or ensure your Google account has an ACTIVE GCP project")
+		}
+	}
+
+	return &GeminiTokenInfo{
+		AccessToken:  tokenResp.AccessToken,
+		RefreshToken: tokenResp.RefreshToken,
+		TokenType:    tokenResp.TokenType,
+		ExpiresIn:    tokenResp.ExpiresIn,
+		ExpiresAt:    expiresAt,
+		Scope:        tokenResp.Scope,
+		ProjectID:    projectID,
+		OAuthType:    oauthType,
+	}, nil
+}
+
+func (s *GeminiOAuthService) RefreshToken(ctx context.Context, oauthType, refreshToken, proxyURL string) (*GeminiTokenInfo, error) {
+	var lastErr error
+
+	for attempt := 0; attempt <= 3; attempt++ {
+		if attempt > 0 {
+			backoff := time.Duration(1<<uint(attempt-1)) * time.Second
+			if backoff > 30*time.Second {
+				backoff = 30 * time.Second
+			}
+			time.Sleep(backoff)
+		}
+
+		tokenResp, err := s.oauthClient.RefreshToken(ctx, oauthType, refreshToken, proxyURL)
+		if err == nil {
+			// 计算过期时间时减去 5 分钟安全时间窗口,考虑网络延迟和时钟偏差
+			expiresAt := time.Now().Unix() + tokenResp.ExpiresIn - 300
+			return &GeminiTokenInfo{
+				AccessToken:  tokenResp.AccessToken,
+				RefreshToken: tokenResp.RefreshToken,
+				TokenType:    tokenResp.TokenType,
+				ExpiresIn:    tokenResp.ExpiresIn,
+				ExpiresAt:    expiresAt,
+				Scope:        tokenResp.Scope,
+			}, nil
+		}
+
+		if isNonRetryableGeminiOAuthError(err) {
+			return nil, err
+		}
+		lastErr = err
+	}
+
+	return nil, fmt.Errorf("token refresh failed after retries: %w", lastErr)
+}
+
+func isNonRetryableGeminiOAuthError(err error) bool {
+	msg := err.Error()
+	nonRetryable := []string{
+		"invalid_grant",
+		"invalid_client",
+		"unauthorized_client",
+		"access_denied",
+	}
+	for _, needle := range nonRetryable {
+		if strings.Contains(msg, needle) {
+			return true
+		}
+	}
+	return false
+}
+
+func (s *GeminiOAuthService) RefreshAccountToken(ctx context.Context, account *Account) (*GeminiTokenInfo, error) {
+	if account.Platform != PlatformGemini || account.Type != AccountTypeOAuth {
+		return nil, fmt.Errorf("account is not a Gemini OAuth account")
+	}
+
+	refreshToken := account.GetCredential("refresh_token")
+	if strings.TrimSpace(refreshToken) == "" {
+		return nil, fmt.Errorf("no refresh token available")
+	}
+
+	// Preserve oauth_type from the account (defaults to code_assist for backward compatibility).
+	oauthType := strings.TrimSpace(account.GetCredential("oauth_type"))
+	if oauthType == "" {
+		oauthType = "code_assist"
+	}
+
+	var proxyURL string
+	if account.ProxyID != nil {
+		proxy, err := s.proxyRepo.GetByID(ctx, *account.ProxyID)
+		if err == nil && proxy != nil {
+			proxyURL = proxy.URL()
+		}
+	}
+
+	tokenInfo, err := s.RefreshToken(ctx, oauthType, refreshToken, proxyURL)
+	// Backward compatibility:
+	// Older versions could refresh Code Assist tokens using a user-provided OAuth client when configured.
+	// If the refresh token was originally issued to that custom client, forcing the built-in client will
+	// fail with "unauthorized_client". In that case, retry with the custom client (ai_studio path) when available.
+	if err != nil && oauthType == "code_assist" && strings.Contains(err.Error(), "unauthorized_client") && s.GetOAuthConfig().AIStudioOAuthEnabled {
+		if alt, altErr := s.RefreshToken(ctx, "ai_studio", refreshToken, proxyURL); altErr == nil {
+			tokenInfo = alt
+			err = nil
+		}
+	}
+	if err != nil {
+		// Provide a more actionable error for common OAuth client mismatch issues.
+		if strings.Contains(err.Error(), "unauthorized_client") {
+			return nil, fmt.Errorf("%w (OAuth client mismatch: the refresh_token is bound to the OAuth client used during authorization; please re-authorize this account or restore the original GEMINI_OAUTH_CLIENT_ID/SECRET)", err)
+		}
+		return nil, err
+	}
+
+	tokenInfo.OAuthType = oauthType
+
+	// Preserve account's project_id when present.
+	existingProjectID := strings.TrimSpace(account.GetCredential("project_id"))
+	if existingProjectID != "" {
+		tokenInfo.ProjectID = existingProjectID
+	}
+
+	// For Code Assist, project_id is required. Auto-detect if missing.
+	// For AI Studio OAuth, project_id is optional and should not block refresh.
+	if oauthType == "code_assist" && strings.TrimSpace(tokenInfo.ProjectID) == "" {
+		projectID, err := s.fetchProjectID(ctx, tokenInfo.AccessToken, proxyURL)
+		if err != nil {
+			return nil, fmt.Errorf("failed to auto-detect project_id: %w", err)
+		}
+		projectID = strings.TrimSpace(projectID)
+		if projectID == "" {
+			return nil, fmt.Errorf("failed to auto-detect project_id: empty result")
+		}
+		tokenInfo.ProjectID = projectID
+	}
+
+	return tokenInfo, nil
+}
+
+func (s *GeminiOAuthService) BuildAccountCredentials(tokenInfo *GeminiTokenInfo) map[string]any {
+	creds := map[string]any{
+		"access_token": tokenInfo.AccessToken,
+		"expires_at":   strconv.FormatInt(tokenInfo.ExpiresAt, 10),
+	}
+	if tokenInfo.RefreshToken != "" {
+		creds["refresh_token"] = tokenInfo.RefreshToken
+	}
+	if tokenInfo.TokenType != "" {
+		creds["token_type"] = tokenInfo.TokenType
+	}
+	if tokenInfo.Scope != "" {
+		creds["scope"] = tokenInfo.Scope
+	}
+	if tokenInfo.ProjectID != "" {
+		creds["project_id"] = tokenInfo.ProjectID
+	}
+	if tokenInfo.OAuthType != "" {
+		creds["oauth_type"] = tokenInfo.OAuthType
+	}
+	return creds
+}
+
+func (s *GeminiOAuthService) Stop() {
+	s.sessionStore.Stop()
+}
+
+func (s *GeminiOAuthService) fetchProjectID(ctx context.Context, accessToken, proxyURL string) (string, error) {
+	if s.codeAssist == nil {
+		return "", errors.New("code assist client not configured")
+	}
+
+	loadResp, loadErr := s.codeAssist.LoadCodeAssist(ctx, accessToken, proxyURL, nil)
+	if loadErr == nil && loadResp != nil && strings.TrimSpace(loadResp.CloudAICompanionProject) != "" {
+		return strings.TrimSpace(loadResp.CloudAICompanionProject), nil
+	}
+
+	// Pick tier from allowedTiers; if no default tier is marked, pick the first non-empty tier ID.
+	tierID := "LEGACY"
+	if loadResp != nil {
+		for _, tier := range loadResp.AllowedTiers {
+			if tier.IsDefault && strings.TrimSpace(tier.ID) != "" {
+				tierID = strings.TrimSpace(tier.ID)
+				break
+			}
+		}
+		if strings.TrimSpace(tierID) == "" || tierID == "LEGACY" {
+			for _, tier := range loadResp.AllowedTiers {
+				if strings.TrimSpace(tier.ID) != "" {
+					tierID = strings.TrimSpace(tier.ID)
+					break
+				}
+			}
+		}
+	}
+
+	req := &geminicli.OnboardUserRequest{
+		TierID: tierID,
+		Metadata: geminicli.LoadCodeAssistMetadata{
+			IDEType:    "ANTIGRAVITY",
+			Platform:   "PLATFORM_UNSPECIFIED",
+			PluginType: "GEMINI",
+		},
+	}
+
+	maxAttempts := 5
+	for attempt := 1; attempt <= maxAttempts; attempt++ {
+		resp, err := s.codeAssist.OnboardUser(ctx, accessToken, proxyURL, req)
+		if err != nil {
+			// If Code Assist onboarding fails (e.g. INVALID_ARGUMENT), fallback to Cloud Resource Manager projects.
+			fallback, fbErr := fetchProjectIDFromResourceManager(ctx, accessToken, proxyURL)
+			if fbErr == nil && strings.TrimSpace(fallback) != "" {
+				return strings.TrimSpace(fallback), nil
+			}
+			return "", err
+		}
+		if resp.Done {
+			if resp.Response != nil && resp.Response.CloudAICompanionProject != nil {
+				switch v := resp.Response.CloudAICompanionProject.(type) {
+				case string:
+					return strings.TrimSpace(v), nil
+				case map[string]any:
+					if id, ok := v["id"].(string); ok {
+						return strings.TrimSpace(id), nil
+					}
+				}
+			}
+
+			fallback, fbErr := fetchProjectIDFromResourceManager(ctx, accessToken, proxyURL)
+			if fbErr == nil && strings.TrimSpace(fallback) != "" {
+				return strings.TrimSpace(fallback), nil
+			}
+			return "", errors.New("onboardUser completed but no project_id returned")
+		}
+		time.Sleep(2 * time.Second)
+	}
+
+	fallback, fbErr := fetchProjectIDFromResourceManager(ctx, accessToken, proxyURL)
+	if fbErr == nil && strings.TrimSpace(fallback) != "" {
+		return strings.TrimSpace(fallback), nil
+	}
+	if loadErr != nil {
+		return "", fmt.Errorf("loadCodeAssist failed (%v) and onboardUser timeout after %d attempts", loadErr, maxAttempts)
+	}
+	return "", fmt.Errorf("onboardUser timeout after %d attempts", maxAttempts)
+}
+
+type googleCloudProject struct {
+	ProjectID      string `json:"projectId"`
+	DisplayName    string `json:"name"`
+	LifecycleState string `json:"lifecycleState"`
+}
+
+type googleCloudProjectsResponse struct {
+	Projects []googleCloudProject `json:"projects"`
+}
+
+func fetchProjectIDFromResourceManager(ctx context.Context, accessToken, proxyURL string) (string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://cloudresourcemanager.googleapis.com/v1/projects", nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create resource manager request: %w", err)
+	}
+
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+	req.Header.Set("User-Agent", geminicli.GeminiCLIUserAgent)
+
+	client := &http.Client{Timeout: 30 * time.Second}
+	if strings.TrimSpace(proxyURL) != "" {
+		if proxyURLParsed, err := url.Parse(strings.TrimSpace(proxyURL)); err == nil {
+			client.Transport = &http.Transport{Proxy: http.ProxyURL(proxyURLParsed)}
+		}
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("resource manager request failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read resource manager response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("resource manager HTTP %d: %s", resp.StatusCode, string(bodyBytes))
+	}
+
+	var projectsResp googleCloudProjectsResponse
+	if err := json.Unmarshal(bodyBytes, &projectsResp); err != nil {
+		return "", fmt.Errorf("failed to parse resource manager response: %w", err)
+	}
+
+	active := make([]googleCloudProject, 0, len(projectsResp.Projects))
+	for _, p := range projectsResp.Projects {
+		if p.LifecycleState == "ACTIVE" && strings.TrimSpace(p.ProjectID) != "" {
+			active = append(active, p)
+		}
+	}
+	if len(active) == 0 {
+		return "", errors.New("no ACTIVE projects found from resource manager")
+	}
+
+	// Prefer likely companion projects first.
+	for _, p := range active {
+		id := strings.ToLower(strings.TrimSpace(p.ProjectID))
+		name := strings.ToLower(strings.TrimSpace(p.DisplayName))
+		if strings.Contains(id, "cloud-ai-companion") || strings.Contains(name, "cloud ai companion") || strings.Contains(name, "code assist") {
+			return strings.TrimSpace(p.ProjectID), nil
+		}
+	}
+	// Then prefer "default".
+	for _, p := range active {
+		id := strings.ToLower(strings.TrimSpace(p.ProjectID))
+		name := strings.ToLower(strings.TrimSpace(p.DisplayName))
+		if strings.Contains(id, "default") || strings.Contains(name, "default") {
+			return strings.TrimSpace(p.ProjectID), nil
+		}
+	}
+
+	return strings.TrimSpace(active[0].ProjectID), nil
+}

backend/internal/service/gemini_token_cache.go

+package service
+
+import (
+	"context"
+	"time"
+)
+
+// GeminiTokenCache stores short-lived access tokens and coordinates refresh to avoid stampedes.
+type GeminiTokenCache interface {
+	// cacheKey should be stable for the token scope; for GeminiCli OAuth we primarily use project_id.
+	GetAccessToken(ctx context.Context, cacheKey string) (string, error)
+	SetAccessToken(ctx context.Context, cacheKey string, token string, ttl time.Duration) error
+
+	AcquireRefreshLock(ctx context.Context, cacheKey string, ttl time.Duration) (bool, error)
+	ReleaseRefreshLock(ctx context.Context, cacheKey string) error
+}

backend/internal/service/gemini_token_provider.go

+package service
+
+import (
+	"context"
+	"errors"
+	"log"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	geminiTokenRefreshSkew = 3 * time.Minute
+	geminiTokenCacheSkew   = 5 * time.Minute
+)
+
+type GeminiTokenProvider struct {
+	accountRepo        AccountRepository
+	tokenCache         GeminiTokenCache
+	geminiOAuthService *GeminiOAuthService
+}
+
+func NewGeminiTokenProvider(
+	accountRepo AccountRepository,
+	tokenCache GeminiTokenCache,
+	geminiOAuthService *GeminiOAuthService,
+) *GeminiTokenProvider {
+	return &GeminiTokenProvider{
+		accountRepo:        accountRepo,
+		tokenCache:         tokenCache,
+		geminiOAuthService: geminiOAuthService,
+	}
+}
+
+func (p *GeminiTokenProvider) GetAccessToken(ctx context.Context, account *Account) (string, error) {
+	if account == nil {
+		return "", errors.New("account is nil")
+	}
+	if account.Platform != PlatformGemini || account.Type != AccountTypeOAuth {
+		return "", errors.New("not a gemini oauth account")
+	}
+
+	cacheKey := geminiTokenCacheKey(account)
+
+	// 1) Try cache first.
+	if p.tokenCache != nil {
+		if token, err := p.tokenCache.GetAccessToken(ctx, cacheKey); err == nil && strings.TrimSpace(token) != "" {
+			return token, nil
+		}
+	}
+
+	// 2) Refresh if needed (pre-expiry skew).
+	expiresAt := parseExpiresAt(account)
+	needsRefresh := expiresAt == nil || time.Until(*expiresAt) <= geminiTokenRefreshSkew
+	if needsRefresh && p.tokenCache != nil {
+		locked, err := p.tokenCache.AcquireRefreshLock(ctx, cacheKey, 30*time.Second)
+		if err == nil && locked {
+			defer func() { _ = p.tokenCache.ReleaseRefreshLock(ctx, cacheKey) }()
+
+			// Re-check after lock (another worker may have refreshed).
+			if token, err := p.tokenCache.GetAccessToken(ctx, cacheKey); err == nil && strings.TrimSpace(token) != "" {
+				return token, nil
+			}
+
+			fresh, err := p.accountRepo.GetByID(ctx, account.ID)
+			if err == nil && fresh != nil {
+				account = fresh
+			}
+			expiresAt = parseExpiresAt(account)
+			if expiresAt == nil || time.Until(*expiresAt) <= geminiTokenRefreshSkew {
+				if p.geminiOAuthService == nil {
+					return "", errors.New("gemini oauth service not configured")
+				}
+				tokenInfo, err := p.geminiOAuthService.RefreshAccountToken(ctx, account)
+				if err != nil {
+					return "", err
+				}
+				newCredentials := p.geminiOAuthService.BuildAccountCredentials(tokenInfo)
+				for k, v := range account.Credentials {
+					if _, exists := newCredentials[k]; !exists {
+						newCredentials[k] = v
+					}
+				}
+				account.Credentials = newCredentials
+				_ = p.accountRepo.Update(ctx, account)
+				expiresAt = parseExpiresAt(account)
+			}
+		}
+	}
+
+	accessToken := account.GetCredential("access_token")
+	if strings.TrimSpace(accessToken) == "" {
+		return "", errors.New("access_token not found in credentials")
+	}
+
+	// project_id is optional now:
+	// - If present: will use Code Assist API (requires project_id)
+	// - If absent: will use AI Studio API with OAuth token (like regular API key mode)
+	// Auto-detect project_id only if explicitly enabled via a credential flag
+	projectID := strings.TrimSpace(account.GetCredential("project_id"))
+	autoDetectProjectID := account.GetCredential("auto_detect_project_id") == "true"
+
+	if projectID == "" && autoDetectProjectID {
+		if p.geminiOAuthService == nil {
+			return accessToken, nil // Fallback to AI Studio API mode
+		}
+
+		var proxyURL string
+		if account.ProxyID != nil && p.geminiOAuthService.proxyRepo != nil {
+			if proxy, err := p.geminiOAuthService.proxyRepo.GetByID(ctx, *account.ProxyID); err == nil && proxy != nil {
+				proxyURL = proxy.URL()
+			}
+		}
+
+		detected, err := p.geminiOAuthService.fetchProjectID(ctx, accessToken, proxyURL)
+		if err != nil {
+			log.Printf("[GeminiTokenProvider] Auto-detect project_id failed: %v, fallback to AI Studio API mode", err)
+			return accessToken, nil
+		}
+		detected = strings.TrimSpace(detected)
+		if detected != "" {
+			if account.Credentials == nil {
+				account.Credentials = make(map[string]any)
+			}
+			account.Credentials["project_id"] = detected
+			_ = p.accountRepo.Update(ctx, account)
+		}
+	}
+
+	// 3) Populate cache with TTL.
+	if p.tokenCache != nil {
+		ttl := 30 * time.Minute
+		if expiresAt != nil {
+			until := time.Until(*expiresAt)
+			switch {
+			case until > geminiTokenCacheSkew:
+				ttl = until - geminiTokenCacheSkew
+			case until > 0:
+				ttl = until
+			default:
+				ttl = time.Minute
+			}
+		}
+		_ = p.tokenCache.SetAccessToken(ctx, cacheKey, accessToken, ttl)
+	}
+
+	return accessToken, nil
+}
+
+func geminiTokenCacheKey(account *Account) string {
+	projectID := strings.TrimSpace(account.GetCredential("project_id"))
+	if projectID != "" {
+		return projectID
+	}
+	return "account:" + strconv.FormatInt(account.ID, 10)
+}
+
+func parseExpiresAt(account *Account) *time.Time {
+	raw := strings.TrimSpace(account.GetCredential("expires_at"))
+	if raw == "" {
+		return nil
+	}
+	if unixSec, err := strconv.ParseInt(raw, 10, 64); err == nil && unixSec > 0 {
+		t := time.Unix(unixSec, 0)
+		return &t
+	}
+	if t, err := time.Parse(time.RFC3339, raw); err == nil {
+		return &t
+	}
+	return nil
+}

backend/internal/service/gemini_token_refresher.go

+package service
+
+import (
+	"context"
+	"strconv"
+	"time"
+)
+
+type GeminiTokenRefresher struct {
+	geminiOAuthService *GeminiOAuthService
+}
+
+func NewGeminiTokenRefresher(geminiOAuthService *GeminiOAuthService) *GeminiTokenRefresher {
+	return &GeminiTokenRefresher{geminiOAuthService: geminiOAuthService}
+}
+
+func (r *GeminiTokenRefresher) CanRefresh(account *Account) bool {
+	return account.Platform == PlatformGemini && account.Type == AccountTypeOAuth
+}
+
+func (r *GeminiTokenRefresher) NeedsRefresh(account *Account, refreshWindow time.Duration) bool {
+	if !r.CanRefresh(account) {
+		return false
+	}
+	expiresAtStr := account.GetCredential("expires_at")
+	if expiresAtStr == "" {
+		return false
+	}
+	expiresAt, err := strconv.ParseInt(expiresAtStr, 10, 64)
+	if err != nil {
+		return false
+	}
+	expiryTime := time.Unix(expiresAt, 0)
+	return time.Until(expiryTime) < refreshWindow
+}
+
+func (r *GeminiTokenRefresher) Refresh(ctx context.Context, account *Account) (map[string]any, error) {
+	tokenInfo, err := r.geminiOAuthService.RefreshAccountToken(ctx, account)
+	if err != nil {
+		return nil, err
+	}
+
+	newCredentials := r.geminiOAuthService.BuildAccountCredentials(tokenInfo)
+	for k, v := range account.Credentials {
+		if _, exists := newCredentials[k]; !exists {
+			newCredentials[k] = v
+		}
+	}
+
+	return newCredentials, nil
+}

backend/internal/service/geminicli_codeassist.go

+package service
+
+import (
+	"context"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/geminicli"
+)
+
+// GeminiCliCodeAssistClient calls GeminiCli internal Code Assist endpoints.
+type GeminiCliCodeAssistClient interface {
+	LoadCodeAssist(ctx context.Context, accessToken, proxyURL string, req *geminicli.LoadCodeAssistRequest) (*geminicli.LoadCodeAssistResponse, error)
+	OnboardUser(ctx context.Context, accessToken, proxyURL string, req *geminicli.OnboardUserRequest) (*geminicli.OnboardUserResponse, error)
+}