Deploy AI Studio Proxy API to Hugging Face Spaces

.dockerignore

@@ -0,0 +1,31 @@
+.git
+.git/
+.gitignore
+.vscode/
+.env
+.venv
+venv/
+env/
+__pycache__/
+*.pyc
+*.log
+*.DS_Store
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+coverage.xml
+deprecated_javascript_version/
+memory-bank/
+logs/
+outputs/
+work/
+auth_profiles/**/*.json
+auth_profiles/key.txt
+config/profile_usage.json
+config/cooldown_status.json
+static/frontend/node_modules/
+static/frontend/dist/
+# auth_profiles/ # Handled by volume mount or Hugging Face Secrets
+# certs/         # Handled by volume mount or generated in container
+# logs/          # Supervisord logs to stdout/stderr

.env.example

@@ -0,0 +1,414 @@
+# AI Studio Proxy API Configuration Template
+# Copy this file to .env and modify as needed
+
+# =============================================================================
+# 1. Server Port Configuration
+# =============================================================================
+
+# FastAPI Main Service Port
+# The port where the OpenAI-compatible API will listen.
+PORT=2048
+
+# Streaming Proxy Service Port
+# Set to 0 to disable the streaming proxy service.
+STREAM_PORT=3120
+
+# GUI Launcher Default Port Configuration
+# These are only used for default suggestions in the launcher.
+DEFAULT_FASTAPI_PORT=2048
+DEFAULT_CAMOUFOX_PORT=9222
+
+# =============================================================================
+# 2. Proxy Configuration
+# =============================================================================
+
+# Unified Proxy Configuration (Recommended)
+# High priority; configures HTTP_PROXY, HTTPS_PROXY, and internal browser proxy.
+UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890
+
+# Legacy Proxy Settings (Only used if UNIFIED_PROXY_CONFIG is not set)
+# HTTP_PROXY=http://127.0.0.1:7890
+# HTTPS_PROXY=http://127.0.0.1:7890
+
+# Proxy Bypass List (Separated by semicolons)
+# NO_PROXY=localhost;127.0.0.1;*.local
+
+# =============================================================================
+# 3. Logging & Debugging
+# =============================================================================
+
+# Server Log Level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+SERVER_LOG_LEVEL=INFO
+
+# Whether to redirect print output to logs
+SERVER_REDIRECT_PRINT=false
+
+# Enable Debug and Trace Logs
+DEBUG_LOGS_ENABLED=false
+TRACE_LOGS_ENABLED=false
+
+# JSON Structured Logging
+JSON_LOGS=false
+
+# Log Rotation Configuration
+LOG_FILE_MAX_BYTES=10485760
+LOG_FILE_BACKUP_COUNT=5
+
+# =============================================================================
+# 4. Authentication Configuration
+# =============================================================================
+
+# Auto-save Authentication Information
+# Set to true to automatically save auth status (cookies/localStorage) after login.
+AUTO_SAVE_AUTH=false
+
+# Auth Save Timeout (seconds)
+# Timeout while waiting for user to provide a filename for the saved auth.
+AUTH_SAVE_TIMEOUT=30
+
+# Auto Rotate Auth Profile (true/false)
+# Automatically switch to a different auth profile when quota is exceeded or issues occur.
+AUTO_ROTATE_AUTH_PROFILE=true
+
+# Auto Auth Rotation on Startup (true/false)
+# Automatically select an available auth profile when starting.
+AUTO_AUTH_ROTATION_ON_STARTUP=false
+
+# Auto Confirm Login
+AUTO_CONFIRM_LOGIN=true
+
+# Quota Rotation Thresholds (Graceful Rotation)
+# Soft Limit: Triggers "Rotation Pending". Current stream finishes, then rotates.
+QUOTA_SOFT_LIMIT=850000
+# Hard Limit: Triggers immediate "Kill Signal" to prevent hard bans.
+QUOTA_HARD_LIMIT=950000
+
+# -----------------------------------------------------------------------------
+# Cookie Refresh Configuration
+# -----------------------------------------------------------------------------
+# Automatically refresh and persist browser cookies to keep auth profiles fresh.
+# This helps prevent cookie expiration issues during long-running sessions.
+
+# Enable automatic cookie refresh (default: true)
+COOKIE_REFRESH_ENABLED=true
+
+# Periodic refresh interval in seconds (default: 1800 = 30 minutes)
+COOKIE_REFRESH_INTERVAL_SECONDS=1800
+
+# Enable cookie save after successful API requests (default: true)
+COOKIE_REFRESH_ON_REQUEST_ENABLED=true
+
+# Number of successful requests between cookie saves (default: 10)
+COOKIE_REFRESH_REQUEST_INTERVAL=10
+
+# Enable cookie save on graceful shutdown (default: true)
+COOKIE_REFRESH_ON_SHUTDOWN=true
+
+# =============================================================================
+# 5. Browser & Model Configuration
+# =============================================================================
+
+# Launch Mode (normal, debug, headless, virtual_display, direct_debug_no_browser)
+LAUNCH_MODE=normal
+
+# Camoufox WebSocket Endpoint
+# For connecting to existing external Camoufox/Chrome instance.
+# CAMOUFOX_WS_ENDPOINT=ws://127.0.0.1:9222
+
+# Quick Launch (Direct Launch)
+# Skip launcher menu and use .env configuration directly.
+DIRECT_LAUNCH=false
+
+# Only collect attachments from the current user's message (true/false)
+ONLY_COLLECT_CURRENT_USER_ATTACHMENTS=false
+
+# Camoufox WebSocket Capture Timeout (seconds)
+ENDPOINT_CAPTURE_TIMEOUT=45
+
+# =============================================================================
+# 6. API Default Parameter Configuration
+# =============================================================================
+
+# Default Sampling Parameters
+DEFAULT_TEMPERATURE=1.0
+DEFAULT_MAX_OUTPUT_TOKENS=65536
+DEFAULT_TOP_P=0.95
+DEFAULT_STOP_SEQUENCES=["User:"]
+
+# Thinking Model Configuration (e.g., gemini-2.0-flash-thinking)
+ENABLE_THINKING_BUDGET=true
+DEFAULT_THINKING_BUDGET=8192
+
+# Thinking Budget Level Values (tokens) - Used for "low", "medium", "high" presets
+THINKING_BUDGET_LOW=10923
+THINKING_BUDGET_MEDIUM=21845
+THINKING_BUDGET_HIGH=32768
+
+# Gemini 3 Default Thinking Levels
+DEFAULT_THINKING_LEVEL_PRO=high
+DEFAULT_THINKING_LEVEL_FLASH=high
+
+# Control if disabling streaming also disables thinking budget (default behavior: false)
+DISABLE_THINKING_BUDGET_ON_STREAMING_DISABLE=false
+
+# Feature Toggles (Google Search, URL Context)
+ENABLE_GOOGLE_SEARCH=false
+ENABLE_URL_CONTEXT=false
+
+# =============================================================================
+# Function Calling Configuration (Native vs Emulated)
+# =============================================================================
+# This configures how OpenAI-compatible tool calls (tools parameter) are handled.
+# NOTE: XML-based tools in prompts are NOT affected - they pass through as plain text.
+
+# Function Calling Mode: "auto" | "native" | "emulated"
+# - "auto": (RECOMMENDED) Tries native first, auto-fallback to emulated on failure
+# - "native": AI Studio UI-driven function calling (best reliability)
+# - "emulated": Text-based prompt injection (legacy, backwards compatible)
+#
+# When to use each:
+# - "auto": Best for most users - resilient with automatic fallback
+# - "native": When you need maximum reliability and your models support it
+# - "emulated": For older setups or if native mode causes issues
+FUNCTION_CALLING_MODE=auto
+
+# Enable automatic fallback to emulated mode when native mode fails
+# Only applies when FUNCTION_CALLING_MODE=native (auto mode always has fallback)
+FUNCTION_CALLING_NATIVE_FALLBACK=true
+
+# Timeout for function calling UI operations (milliseconds)
+FUNCTION_CALLING_UI_TIMEOUT=10000
+
+# Native mode retry attempts before fallback
+FUNCTION_CALLING_NATIVE_RETRY_COUNT=3
+
+# Clear function definitions between requests (stateless behavior)
+# Set to false if you want to reuse tool definitions across requests
+FUNCTION_CALLING_CLEAR_BETWEEN_REQUESTS=true
+
+# -----------------------------------------------------------------------------
+# Function Calling Debug Logging (Master Switch)
+# -----------------------------------------------------------------------------
+# When false, ALL function calling logs (console & modular) are disabled.
+# Useful for production to minimize noise and disk I/O.
+FUNCTION_CALLING_DEBUG=false
+
+# Enable function calling state caching for performance
+# Reduces UI operations when same tools are used in subsequent requests
+FUNCTION_CALLING_CACHE_ENABLED=true
+
+# Cache TTL in seconds (0 = no expiration within session)
+FUNCTION_CALLING_CACHE_TTL=0
+
+# -----------------------------------------------------------------------------
+# Function Calling Improvements (FC-001 to FC-004)
+# -----------------------------------------------------------------------------
+# These settings control advanced function calling compatibility features.
+# See docs/architecture/FUNCTION_CALLING_IMPROVEMENTS.md for details.
+
+# FC-001: thoughtSignature Support for Gemini 3
+# Add thoughtSignature to functionCall parts for Gemini 3 model compatibility.
+# When replaying conversation history with tool calls, Gemini 3 may require
+# this field for validation. Safe for older models (ignored if not needed).
+FUNCTION_CALLING_THOUGHT_SIGNATURE=true
+
+# FC-004: Type Case Normalization (UPPERCASE types)
+# Convert JSON Schema types to UPPERCASE (e.g., "string" -> "STRING").
+# The iBUHub/AIStudioToAPI project uses UPPERCASE types.
+# WARNING: Set to false by default - requires UI verification before enabling.
+# Only enable after confirming AI Studio UI accepts UPPERCASE types.
+FUNCTION_CALLING_UPPERCASE_TYPES=false
+
+# -----------------------------------------------------------------------------
+# Modular Per-Component Logging (Active only if FUNCTION_CALLING_DEBUG=true)
+# -----------------------------------------------------------------------------
+# Fine-grained logging with separate log files in logs/fc_debug/<module>.log
+# See docs/architecture/FC_DEBUG_LOGGING_DESIGN.md for full documentation.
+
+# Enable individual modules for targeted debugging. Only enabled modules
+# will create log files. All default to false to minimize disk I/O.
+#
+# ORCHESTRATOR: Mode selection, fallback logic, high-level flow
+# UI:           Browser UI automation (toggle, dialog, paste)
+# CACHE:        Cache hits/misses/invalidation
+# WIRE:         Wire format parsing from network responses
+# DOM:          DOM-based function call extraction
+# SCHEMA:       Tool schema conversion and validation
+# RESPONSE:     Response formatting for OpenAI compatibility
+
+FC_DEBUG_ORCHESTRATOR=false
+FC_DEBUG_UI=false
+FC_DEBUG_CACHE=false
+FC_DEBUG_WIRE=false
+FC_DEBUG_DOM=false
+FC_DEBUG_SCHEMA=false
+FC_DEBUG_RESPONSE=false
+
+# -----------------------------------------------------------------------------
+# Per-Module Log Levels
+# -----------------------------------------------------------------------------
+# Available levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
+# Only affects modules that are enabled above.
+# Recommendation: Use DEBUG for troubleshooting, INFO for general monitoring.
+
+FC_DEBUG_LEVEL_ORCHESTRATOR=DEBUG
+FC_DEBUG_LEVEL_UI=DEBUG
+FC_DEBUG_LEVEL_CACHE=DEBUG
+FC_DEBUG_LEVEL_WIRE=DEBUG
+FC_DEBUG_LEVEL_DOM=DEBUG
+FC_DEBUG_LEVEL_SCHEMA=DEBUG
+FC_DEBUG_LEVEL_RESPONSE=DEBUG
+
+# -----------------------------------------------------------------------------
+# Log File Rotation
+# -----------------------------------------------------------------------------
+# Configure rotation to prevent unbounded disk usage.
+# Max file size in bytes (default: 5MB = 5242880)
+# Backup count determines how many rotated files to keep.
+
+FC_DEBUG_LOG_MAX_BYTES=5242880
+FC_DEBUG_LOG_BACKUP_COUNT=3
+
+# -----------------------------------------------------------------------------
+# Payload Truncation
+# -----------------------------------------------------------------------------
+# Large payloads (tool definitions, arguments) can clutter logs.
+# Enable truncation to keep logs readable while preserving key info.
+
+# Master switch for truncation
+FC_DEBUG_TRUNCATE_ENABLED=true
+
+# Maximum characters for different payload types:
+# - TOOL_DEF: Tool/function schema definitions (often 10KB+)
+# - ARGS: Function call arguments
+# - RESPONSE: Response bodies
+
+FC_DEBUG_TRUNCATE_MAX_TOOL_DEF=500
+FC_DEBUG_TRUNCATE_MAX_ARGS=1000
+FC_DEBUG_TRUNCATE_MAX_RESPONSE=2000
+
+# -----------------------------------------------------------------------------
+# Combined Log (Optional)
+# -----------------------------------------------------------------------------
+# Additionally write all FC debug logs to a single combined file.
+# Useful for seeing cross-module request flow in one place.
+# File: logs/fc_debug/fc_combined.log
+
+FC_DEBUG_COMBINED_LOG=false
+
+# =============================================================================
+# Quick Start Examples:
+# =============================================================================
+#
+# Example 1: Debug cache issues only
+#   FUNCTION_CALLING_DEBUG=true
+#   FC_DEBUG_CACHE=true
+#
+# Example 2: Full FC debugging with combined log
+#   FUNCTION_CALLING_DEBUG=true
+#   FC_DEBUG_ORCHESTRATOR=true
+#   FC_DEBUG_UI=true
+#   FC_DEBUG_CACHE=true
+#   FC_DEBUG_WIRE=true
+#   FC_DEBUG_DOM=true
+#   FC_DEBUG_SCHEMA=true
+#   FC_DEBUG_RESPONSE=true
+#   FC_DEBUG_COMBINED_LOG=true
+#
+# Example 3: Production monitoring (errors only)
+#   FUNCTION_CALLING_DEBUG=true
+#   FC_DEBUG_ORCHESTRATOR=true
+#   FC_DEBUG_LEVEL_ORCHESTRATOR=ERROR
+# =============================================================================
+
+
+# =============================================================================
+# 7. Advanced Timeout Configuration (milliseconds)
+# =============================================================================
+
+# Response Completion Total Timeout
+# Default: 600000 (10 minutes)
+RESPONSE_COMPLETION_TIMEOUT=600000
+
+# Initial Wait Time Before Polling
+INITIAL_WAIT_MS_BEFORE_POLLING=500
+
+# Polling Interval
+POLLING_INTERVAL=300
+POLLING_INTERVAL_STREAM=180
+
+# Silence Timeout (Base threshold for inactivity detection)
+SILENCE_TIMEOUT_MS=60000
+
+# Page Action Timeouts
+POST_SPINNER_CHECK_DELAY_MS=500
+FINAL_STATE_CHECK_TIMEOUT_MS=1500
+POST_COMPLETION_BUFFER=700
+
+# UI Generation Wait Configuration
+UI_GENERATION_WAIT_TIMEOUT_MS=5000
+UI_GENERATION_CHECK_INTERVAL_MS=500
+UI_STABILIZATION_BUFFER_MS=500
+
+# Clear Chat Related Timeouts
+CLEAR_CHAT_VERIFY_TIMEOUT_MS=4000
+CLEAR_CHAT_VERIFY_INTERVAL_MS=4000
+
+# Interaction Timeouts
+CLICK_TIMEOUT_MS=3000
+CLIPBOARD_READ_TIMEOUT_MS=3000
+WAIT_FOR_ELEMENT_TIMEOUT_MS=10000
+
+# Stream Related Configuration
+PSEUDO_STREAM_DELAY=0.01
+
+# =============================================================================
+# 8. GUI Launcher Configuration
+# =============================================================================
+
+# GUI Default Proxy and Port settings
+GUI_DEFAULT_PROXY_ADDRESS=http://127.0.0.1:7890
+GUI_DEFAULT_STREAM_PORT=3120
+GUI_DEFAULT_HELPER_ENDPOINT=
+
+# =============================================================================
+# 9. Script Injection Configuration
+# =============================================================================
+
+# Whether to enable Tampermonkey script injection (Deprecated)
+ENABLE_SCRIPT_INJECTION=false
+
+# Tampermonkey script file path (relative to project root)
+USERSCRIPT_PATH=browser_utils/more_models.js
+
+# =============================================================================
+# 10. Miscellaneous System Config
+# =============================================================================
+
+# Model Metadata
+MODEL_NAME=AI-Studio_Proxy_API
+CHAT_COMPLETION_ID_PREFIX=chatcmpl-
+AI_STUDIO_URL_PATTERN=aistudio.google.com/
+EXCLUDED_MODELS_FILENAME=excluded_models.txt
+
+# Internal URL Markers and Fallbacks
+DEFAULT_FALLBACK_MODEL_ID=no model list
+MODELS_ENDPOINT_URL_CONTAINS=MakerSuiteService/ListModels
+USER_INPUT_START_MARKER_SERVER=__USER_INPUT_START__
+USER_INPUT_END_MARKER_SERVER=__USER_INPUT_END__
+
+# =============================================================================
+# 11. Stream State and Error Suppression
+# =============================================================================
+
+# Stream Timeout Log State Configuration
+STREAM_MAX_INITIAL_ERRORS=3
+STREAM_WARNING_INTERVAL_AFTER_SUPPRESS=60.0
+STREAM_SUPPRESS_DURATION_AFTER_INITIAL_BURST=400.0
+
+# =============================================================================
+# 12. Frontend Build Configuration
+# =============================================================================
+
+# Skip frontend build check (for environments without Node.js/npm)
+SKIP_FRONTEND_BUILD=false

.gitattributes

@@ -0,0 +1,79 @@
+# Enforce LF line endings for all text files (cross-platform consistency)
+* text=auto eol=lf
+
+# =============================================================================
+# TRANSLATION FORK MERGE STRATEGY
+# =============================================================================
+# This is an English translation fork of a Chinese upstream repository.
+# The README.md will always conflict because:
+#   - Fork: English README (intentional localization)
+#   - Upstream: Chinese README
+#
+# The 'merge=ours' strategy tells Git to always keep our (fork's) version
+# during merges. This serves as additional protection alongside the workflow
+# conflict handling in .github/workflows/upstream-sync.yml
+# =============================================================================
+README.md merge=ours
+
+# Binary files (no line ending conversion)
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary
+*.pyc binary
+*.pyd binary
+*.so binary
+*.dll binary
+*.exe binary
+*.zip binary
+*.tar binary
+*.gz binary
+*.db binary
+*.sqlite binary
+*.sqlite3 binary
+
+# Python files (explicit LF)
+*.py text eol=lf
+*.pyi text eol=lf
+*.pyx text eol=lf
+
+# Configuration files
+*.toml text eol=lf
+*.ini text eol=lf
+*.cfg text eol=lf
+*.conf text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.txt text eol=lf
+.env* text eol=lf
+.gitignore text eol=lf
+.gitattributes text eol=lf
+
+# Shell scripts
+*.sh text eol=lf
+*.bash text eol=lf
+
+# Windows scripts (keep CRLF for Windows)
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# JavaScript/TypeScript
+*.js text eol=lf
+*.ts text eol=lf
+*.jsx text eol=lf
+*.tsx text eol=lf
+*.css text eol=lf
+*.scss text eol=lf
+*.html text eol=lf
+
+# Lock files
+poetry.lock text eol=lf
+package-lock.json text eol=lf

.github/workflows/pr-check.yml

@@ -0,0 +1,229 @@
+# PR Check Workflow
+# Runs linting, type checking, and tests on pull requests and pushes to main
+#
+# NOTE: Lint and type check are set to continue-on-error because this is a fork
+# of an upstream project with pre-existing code quality issues. These jobs will
+# report issues but won't block the workflow from completing successfully.
+# As code quality improves, these can be made blocking again.
+#
+# CACHING STRATEGY:
+# - Poetry virtualenv: Cached per OS/Python version/poetry.lock hash
+# - Pip cache: Cached per OS/Python version for faster package resolution
+# - Playwright browsers: Cached per OS/Playwright version (test job only)
+name: PR Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-progress runs for the same branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  POETRY_VERSION: "1.8.3"
+  PYTHON_KEYRING_BACKEND: "keyring.backends.null.Keyring"
+  # Playwright browser cache location (Linux)
+  PLAYWRIGHT_BROWSERS_PATH: ~/.cache/ms-playwright
+
+jobs:
+  lint:
+    name: Lint (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    # Continue even if linting fails - reports issues without blocking
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11"]
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: ${{ env.POETRY_VERSION }}
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Cache pip downloads
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            pip-${{ runner.os }}-${{ matrix.python-version }}-
+
+      - name: Cache Poetry virtualenv
+        uses: actions/cache@v4
+        id: cache-deps
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            venv-${{ runner.os }}-${{ matrix.python-version }}-
+
+      - name: Install dependencies
+        run: poetry install --no-interaction --no-root
+
+      - name: Run Ruff linting
+        run: poetry run ruff check . --output-format=github
+
+  typecheck:
+    name: Type Check (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    # Continue even if type checking fails - reports issues without blocking
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11"]
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: ${{ env.POETRY_VERSION }}
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Cache pip downloads
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            pip-${{ runner.os }}-${{ matrix.python-version }}-
+
+      - name: Cache Poetry virtualenv
+        uses: actions/cache@v4
+        id: cache-deps
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            venv-${{ runner.os }}-${{ matrix.python-version }}-
+
+      - name: Install dependencies
+        run: poetry install --no-interaction --no-root
+
+      - name: Run Pyright type checking
+        # Use exit 0 to always succeed - Pyright will still report issues in the log
+        run: poetry run pyright || true
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20  # Prevent stuck jobs from blocking indefinitely
+    # Remove dependency on lint/typecheck - tests should run regardless
+    # Tests are the most critical check for functionality
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11"]
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: ${{ env.POETRY_VERSION }}
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Cache pip downloads
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            pip-${{ runner.os }}-${{ matrix.python-version }}-
+
+      - name: Cache Poetry virtualenv
+        uses: actions/cache@v4
+        id: cache-deps
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            venv-${{ runner.os }}-${{ matrix.python-version }}-
+
+      - name: Install dependencies
+        run: poetry install --no-interaction --no-root
+
+      - name: Get Playwright version
+        id: playwright-version
+        run: |
+          PLAYWRIGHT_VERSION=$(poetry run python -c "import playwright; print(playwright.__version__)" 2>/dev/null || echo "unknown")
+          echo "version=$PLAYWRIGHT_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        id: cache-playwright
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
+          restore-keys: |
+            playwright-${{ runner.os }}-
+
+      - name: Install Playwright browsers
+        if: steps.cache-playwright.outputs.cache-hit != 'true'
+        run: poetry run playwright install chromium --with-deps
+
+      - name: Install Playwright system dependencies
+        if: steps.cache-playwright.outputs.cache-hit == 'true'
+        run: poetry run playwright install-deps chromium
+
+      - name: Run pytest with coverage
+        run: |
+          poetry run pytest \
+            -n auto \
+            --dist=loadfile \
+            -m "not integration" \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            --junitxml=test-results.xml
+        env:
+          LAUNCH_MODE: test
+          STREAM_PORT: "0"
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-report-${{ matrix.python-version }}
+          path: coverage.xml
+          retention-days: 7
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-results-${{ matrix.python-version }}
+          path: test-results.xml
+          retention-days: 7

.github/workflows/release.yml

@@ -0,0 +1,441 @@
+# Automated Release Workflow for AI Studio Proxy API
+# Creates GitHub releases with source code archives when version tags are pushed,
+# on pushes to main (nightly builds), or manually triggered via workflow_dispatch.
+#
+# Release Types:
+#   - Stable: Push a tag (git tag v0.1.0 && git push origin v0.1.0)
+#   - Nightly: Automatic on every push to main branch (rolling release)
+#   - Manual: Actions -> Release -> Run workflow -> Enter version (e.g., v0.2.0)
+#             The tag will be auto-created on the current HEAD if it doesn't exist.
+
+name: Release
+
+on:
+  # Trigger on pushes to main branch for nightly builds
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*.*.*'  # Matches v1.0.0, v2.1.3, etc.
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., v0.1.0 or 0.1.0)'
+        required: true
+        type: string
+
+# Ensure only one release workflow runs at a time
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write  # Required for creating releases
+
+jobs:
+  # ===========================================================================
+  # Stable Release Job
+  # ===========================================================================
+  # Runs on tag pushes (v*.*.*) or manual workflow_dispatch
+  # Creates versioned, stable releases
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    # Only run on tag pushes or manual triggers (not on main branch pushes)
+    if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'
+    
+    steps:
+      - name: Validate version format (manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          VERSION_RAW="${{ github.event.inputs.version }}"
+
+          if [[ "$VERSION_RAW" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+            VERSION="v$VERSION_RAW"
+          else
+            VERSION="$VERSION_RAW"
+          fi
+
+          if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+            echo "::error::Invalid version format '$VERSION_RAW'. Expected format: v1.2.3, 1.2.3, or pre-release variants like v1.2.3-beta.1"
+            exit 1
+          fi
+          echo "Version format validated: $VERSION"
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for changelog generation
+          # For workflow_dispatch, checkout default branch first, then verify/checkout tag
+          # For tag pushes, checkout the tag directly
+          ref: ${{ github.event_name == 'workflow_dispatch' && '' || github.ref }}
+
+      - name: Determine version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            VERSION_RAW="${{ github.event.inputs.version }}"
+            if [[ "$VERSION_RAW" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+              VERSION="v$VERSION_RAW"
+            else
+              VERSION="$VERSION_RAW"
+            fi
+          else
+            VERSION="${GITHUB_REF#refs/tags/}"
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "version_number=${VERSION#v}" >> $GITHUB_OUTPUT
+          echo "Release version: $VERSION"
+
+      - name: Setup Git for tagging (manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Create or verify tag (manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          # Fetch all tags to ensure we have the latest
+          git fetch --tags --force
+          
+          if git rev-parse "refs/tags/$VERSION" >/dev/null 2>&1; then
+            echo "✓ Tag $VERSION already exists"
+            echo "Checking out existing tag..."
+            git checkout "refs/tags/$VERSION"
+          else
+            echo "Tag $VERSION does not exist, creating it on current HEAD..."
+            CURRENT_SHA=$(git rev-parse HEAD)
+            echo "Creating tag $VERSION at commit $CURRENT_SHA"
+            
+            # Create the tag locally
+            git tag -a "$VERSION" -m "Release $VERSION"
+            
+            # Push the tag to remote
+            git push origin "$VERSION"
+            
+            echo "✓ Tag $VERSION created and pushed successfully"
+          fi
+
+      - name: Generate changelog
+        id: changelog
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          
+          # Find the previous tag for comparison
+          PREVIOUS_TAG=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+' | grep -v "^$VERSION$" | head -n 1)
+          
+          if [ -n "$PREVIOUS_TAG" ]; then
+            echo "Generating changelog from $PREVIOUS_TAG to $VERSION"
+            
+            # Generate commit log grouped by type
+            CHANGELOG=$(cat << 'CHANGELOG_EOF'
+          ## What's Changed
+
+          CHANGELOG_EOF
+          )
+            
+            TEMP_FILE=$(mktemp)
+
+            while IFS= read -r commit_sha || [ -n "$commit_sha" ]; do
+              if [ -z "$commit_sha" ]; then
+                continue
+              fi
+
+              commit_msg=$(git log -1 --pretty=format:"%s" "$commit_sha")
+              short_sha=$(git rev-parse --short "$commit_sha")
+              git_author=$(git log -1 --pretty=format:"%an" "$commit_sha")
+
+              api_response=$(gh api "repos/${{ github.repository }}/commits/$commit_sha" 2>/dev/null || echo '{}')
+              github_username=$(echo "$api_response" | jq -r '.author.login // empty')
+
+              if [ -n "$github_username" ]; then
+                echo "- ${commit_msg} by @${github_username} (${short_sha})" >> "$TEMP_FILE"
+              else
+                echo "- ${commit_msg} by ${git_author} (${short_sha})" >> "$TEMP_FILE"
+              fi
+            done < <(git log --pretty=format:"%H" "$PREVIOUS_TAG..$VERSION" 2>/dev/null || true)
+
+            if [ -s "$TEMP_FILE" ]; then
+              CHANGELOG="$CHANGELOG
+          $(cat "$TEMP_FILE")"
+            else
+              CHANGELOG="$CHANGELOG
+          - Various improvements and updates"
+            fi
+
+            rm -f "$TEMP_FILE"
+
+            CHANGELOG="$CHANGELOG
+
+          **Full Changelog**: https://github.com/${{ github.repository }}/compare/$PREVIOUS_TAG...$VERSION"
+          else
+            echo "No previous tag found, this appears to be the first release"
+            CHANGELOG="## What's Changed
+
+          This is the first automated release in this repository.
+
+          See the commit history for details."
+
+          fi
+          
+          # Write to file for use in release
+          echo "$CHANGELOG" > CHANGELOG.md
+          echo "Changelog generated successfully"
+
+      - name: Build release body
+        id: release_body
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          VERSION_NUMBER="${{ steps.version.outputs.version_number }}"
+          
+          cat > RELEASE_BODY.md << 'EOF'
+          ${{ steps.version.outputs.version }} brings improvements and updates to the AI Studio Proxy API.
+
+          EOF
+          
+          # Append the generated changelog
+          cat CHANGELOG.md >> RELEASE_BODY.md
+          
+          cat >> RELEASE_BODY.md << 'EOF'
+
+          ---
+
+          ## Installation
+
+          ### Quick Start
+          ```bash
+          # Clone the repository
+          git clone https://github.com/${{ github.repository }}.git
+          cd AIstudioProxyAPI
+
+          # Install dependencies with Poetry
+          poetry install
+
+          # Run the server
+          poetry run python server.py
+          ```
+
+          ### Docker
+          ```bash
+          docker-compose -f docker/docker-compose.yml up -d
+          ```
+
+          For full installation and configuration details, see the [README](https://github.com/${{ github.repository }}/blob/main/README.md).
+
+          ## Source Code
+
+          Source code archives (zip and tar.gz) are automatically attached below.
+
+          ---
+
+          **Thank you to all contributors!**
+          EOF
+          
+          echo "Release body generated successfully"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "AI Studio Proxy API ${{ steps.version.outputs.version }}"
+          tag_name: ${{ steps.version.outputs.version }}
+          body_path: RELEASE_BODY.md
+          draft: false
+          prerelease: ${{ contains(steps.version.outputs.version, '-') }}
+          generate_release_notes: false  # We generate our own
+          make_latest: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Release summary
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          echo "## Release Created Successfully!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** $VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "**Release URL:** https://github.com/${{ github.repository }}/releases/tag/$VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Included Assets" >> $GITHUB_STEP_SUMMARY
+          echo "- Source code (zip)" >> $GITHUB_STEP_SUMMARY
+          echo "- Source code (tar.gz)" >> $GITHUB_STEP_SUMMARY
+
+  # ===========================================================================
+  # Nightly Release Job
+  # ===========================================================================
+  # Runs on every push to main branch (not on tags)
+  # Creates/updates a rolling "nightly" release with the latest development code
+  nightly:
+    name: Create Nightly Release
+    runs-on: ubuntu-latest
+    # Only run on pushes to main branch, NOT on tag pushes
+    if: github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for changelog generation
+
+      - name: Get build info
+        id: build_info
+        run: |
+          # Get short commit SHA and date for versioning
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          BUILD_DATE=$(date +'%Y-%m-%d')
+          BUILD_TIME=$(date +'%H:%M:%S UTC')
+          COMMIT_MSG=$(git log -1 --pretty=format:"%s")
+          
+          echo "short_sha=$SHORT_SHA" >> $GITHUB_OUTPUT
+          echo "build_date=$BUILD_DATE" >> $GITHUB_OUTPUT
+          echo "build_time=$BUILD_TIME" >> $GITHUB_OUTPUT
+          echo "commit_msg=$COMMIT_MSG" >> $GITHUB_OUTPUT
+          
+          echo "Build info: $SHORT_SHA @ $BUILD_DATE $BUILD_TIME"
+
+      - name: Generate recent changes
+        id: changes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Build nightly changelog from latest stable tag to HEAD
+          echo "## What's Changed" > NIGHTLY_CHANGES.md
+          echo "" >> NIGHTLY_CHANGES.md
+
+          LATEST_STABLE_TAG=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1)
+
+          if [ -n "$LATEST_STABLE_TAG" ]; then
+            echo "_Changes since ${LATEST_STABLE_TAG}_" >> NIGHTLY_CHANGES.md
+            echo "" >> NIGHTLY_CHANGES.md
+            echo "Using commit range: ${LATEST_STABLE_TAG}..HEAD"
+          else
+            echo "_No stable release tag found. Showing last 20 commits (first release scenario)._" >> NIGHTLY_CHANGES.md
+            echo "" >> NIGHTLY_CHANGES.md
+            echo "No stable tag found; falling back to last 20 commits"
+          fi
+
+          TEMP_FILE=$(mktemp)
+
+          while IFS= read -r commit_sha || [ -n "$commit_sha" ]; do
+            if [ -z "$commit_sha" ]; then
+              continue
+            fi
+
+            commit_msg=$(git log -1 --pretty=format:"%s" "$commit_sha")
+            short_sha=$(git rev-parse --short "$commit_sha")
+            git_author=$(git log -1 --pretty=format:"%an" "$commit_sha")
+
+            api_response=$(gh api "repos/${{ github.repository }}/commits/$commit_sha" 2>/dev/null || echo '{}')
+            github_username=$(echo "$api_response" | jq -r '.author.login // empty')
+
+            if [ -n "$github_username" ]; then
+              echo "- ${commit_msg} by @${github_username} (${short_sha})" >> "$TEMP_FILE"
+            else
+              echo "- ${commit_msg} by ${git_author} (${short_sha})" >> "$TEMP_FILE"
+            fi
+          done < <(
+            if [ -n "$LATEST_STABLE_TAG" ]; then
+              git log --pretty=format:"%H" "${LATEST_STABLE_TAG}..HEAD" 2>/dev/null || true
+            else
+              git log --pretty=format:"%H" -20 2>/dev/null || true
+            fi
+          )
+
+          if [ -s "$TEMP_FILE" ]; then
+            cat "$TEMP_FILE" >> NIGHTLY_CHANGES.md
+          else
+            if [ -n "$LATEST_STABLE_TAG" ]; then
+              echo "- No commits found since ${LATEST_STABLE_TAG}" >> NIGHTLY_CHANGES.md
+            else
+              echo "- Various improvements and updates" >> NIGHTLY_CHANGES.md
+            fi
+          fi
+
+          rm -f "$TEMP_FILE"
+          echo "" >> NIGHTLY_CHANGES.md
+          
+          echo "Recent changes generated"
+
+      - name: Build nightly release body
+        run: |
+          cat > NIGHTLY_BODY.md << 'EOF'
+          ## ⚠️ Nightly Build (Development Version)
+          
+          **This is an automated nightly build from the `main` branch.**
+          
+          > **Warning**: This release may contain untested features, breaking changes, or bugs.
+          > For stable releases, please use a [versioned release](https://github.com/${{ github.repository }}/releases?q=v&expanded=true).
+          
+          ### Build Information
+          - **Commit**: `${{ steps.build_info.outputs.short_sha }}`
+          - **Date**: ${{ steps.build_info.outputs.build_date }} ${{ steps.build_info.outputs.build_time }}
+          - **Latest Change**: ${{ steps.build_info.outputs.commit_msg }}
+          
+          EOF
+          
+          cat NIGHTLY_CHANGES.md >> NIGHTLY_BODY.md
+          
+          cat >> NIGHTLY_BODY.md << 'EOF'
+          
+          ---
+          
+          ## Quick Start
+          
+          ```bash
+          # Clone the repository
+          git clone https://github.com/${{ github.repository }}.git
+          cd AIstudioProxyAPI
+          
+          # Install dependencies
+          poetry install
+          
+          # Run the server
+          poetry run python server.py
+          ```
+          
+          ---
+
+          *This nightly release is automatically updated on every push to the main branch.*
+
+          **Thank you to all contributors!**
+          EOF
+          
+          echo "Nightly release body generated"
+
+      - name: Delete existing nightly release
+        run: |
+          # Delete existing nightly release if it exists (to avoid accumulation)
+          echo "Checking for existing nightly release..."
+          if gh release view nightly &>/dev/null; then
+            echo "Deleting existing nightly release..."
+            gh release delete nightly --yes --cleanup-tag
+            echo "Existing nightly release deleted"
+          else
+            echo "No existing nightly release found"
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create nightly release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "Nightly Build (Latest)"
+          tag_name: nightly
+          body_path: NIGHTLY_BODY.md
+          draft: false
+          prerelease: true  # Mark as prerelease since it's development code
+          generate_release_notes: false
+          make_latest: false  # Don't mark nightly as "latest" - reserve that for stable releases
+          target_commitish: ${{ github.sha }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Nightly release summary
+        run: |
+          echo "## Nightly Release Updated!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Commit:** ${{ steps.build_info.outputs.short_sha }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Build Date:** ${{ steps.build_info.outputs.build_date }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Release URL:** https://github.com/${{ github.repository }}/releases/tag/nightly" >> $GITHUB_STEP_SUMMARY

.github/workflows/upstream-sync.yml

@@ -0,0 +1,324 @@
+# =============================================================================
+# Upstream Sync Workflow
+# =============================================================================
+# Automatically syncs this repository with the upstream repository.
+# Creates a PR when new changes are detected from upstream.
+#
+# Local repository: current default branch (main)
+# Upstream source: CJackHwang/AIstudioProxyAPI (main)
+#
+# CONFLICT HANDLING:
+# README.md can conflict when this repository keeps custom docs/content.
+# The workflow auto-resolves README.md conflicts by keeping local version.
+# Other conflicts will fail the workflow and require manual intervention.
+# =============================================================================
+
+name: Sync with Upstream
+
+on:
+  # Run every 6 hours (at 00:00, 06:00, 12:00, 18:00 UTC)
+  # This ensures timely detection of upstream changes while avoiding excessive API calls
+  schedule:
+    - cron: '0 */6 * * *'
+
+  # Allow manual trigger from GitHub Actions UI
+  workflow_dispatch:
+    inputs:
+      force_sync:
+        description: 'Force sync even if no new commits detected'
+        required: false
+        default: false
+        type: boolean
+
+# Ensure only one sync workflow runs at a time
+concurrency:
+  group: upstream-sync
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    name: Sync Repository with Upstream
+    runs-on: ubuntu-latest
+
+    # Required permissions for creating PRs and pushing branches
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      # -----------------------------------------------------------------------
+      # Step 1: Checkout current repository
+      # -----------------------------------------------------------------------
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          # Fetch all history to properly compare with upstream
+          fetch-depth: 0
+          # Use the default GITHUB_TOKEN
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      # -----------------------------------------------------------------------
+      # Step 2: Configure Git identity for commits
+      # -----------------------------------------------------------------------
+      - name: Configure Git Identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      # -----------------------------------------------------------------------
+      # Step 3: Add upstream remote and fetch latest changes
+      # -----------------------------------------------------------------------
+      - name: Add Upstream Remote
+        run: |
+          echo "Adding upstream remote..."
+          git remote add upstream https://github.com/CJackHwang/AIstudioProxyAPI.git
+          
+          echo "Fetching upstream changes..."
+          git fetch upstream main --tags
+          
+          echo "Upstream remote added and fetched successfully."
+
+      # -----------------------------------------------------------------------
+      # Step 4: Check for new commits from upstream
+      # -----------------------------------------------------------------------
+      - name: Check for Upstream Changes
+        id: check_changes
+        run: |
+          echo "Comparing local main with upstream/main..."
+          
+          # Get commit counts
+          LOCAL_COMMIT=$(git rev-parse HEAD)
+          UPSTREAM_COMMIT=$(git rev-parse upstream/main)
+          
+          echo "Local HEAD: $LOCAL_COMMIT"
+          echo "Upstream HEAD: $UPSTREAM_COMMIT"
+          
+          # Count commits ahead and behind
+          COMMITS_BEHIND=$(git rev-list --count HEAD..upstream/main)
+          COMMITS_AHEAD=$(git rev-list --count upstream/main..HEAD)
+          
+          echo "Commits behind upstream: $COMMITS_BEHIND"
+          echo "Commits ahead of upstream: $COMMITS_AHEAD"
+          
+          # Determine if sync is needed
+          if [ "$COMMITS_BEHIND" -gt 0 ]; then
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            echo "commits_behind=$COMMITS_BEHIND" >> $GITHUB_OUTPUT
+            echo "::notice::Found $COMMITS_BEHIND new commit(s) from upstream"
+          else
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+            echo "commits_behind=0" >> $GITHUB_OUTPUT
+            echo "::notice::Fork is up to date with upstream"
+          fi
+          
+          # Get the date for PR title
+          echo "sync_date=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
+          
+          # Get recent upstream commit messages for PR body
+          if [ "$COMMITS_BEHIND" -gt 0 ]; then
+            echo "Getting recent upstream commits..."
+            COMMIT_LOG=$(git log --oneline HEAD..upstream/main | head -20)
+            
+            # Write commit log to file for multi-line output
+            echo "$COMMIT_LOG" > /tmp/commit_log.txt
+            
+            # Use delimiter for multi-line output
+            {
+              echo 'commit_log<<EOF'
+              cat /tmp/commit_log.txt
+              echo 'EOF'
+            } >> $GITHUB_OUTPUT
+          fi
+
+      # -----------------------------------------------------------------------
+      # Step 5: Create sync branch with upstream changes
+      # -----------------------------------------------------------------------
+      # CONFLICT RESOLUTION STRATEGY:
+      # 1. Attempt merge with upstream
+      # 2. If conflicts occur, check if ONLY expected files conflict (README.md)
+      # 3. Auto-resolve expected conflicts by keeping fork's version (--ours)
+      # 4. Fail only if unexpected files have conflicts
+      # -----------------------------------------------------------------------
+      - name: Create Sync Branch
+        id: create_branch
+        if: steps.check_changes.outputs.has_changes == 'true' || github.event.inputs.force_sync == 'true'
+        run: |
+          BRANCH_NAME="sync/upstream-${{ steps.check_changes.outputs.sync_date }}"
+          echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
+          
+          echo "Creating sync branch: $BRANCH_NAME"
+          
+          # Check if branch already exists remotely
+          if git ls-remote --heads origin "$BRANCH_NAME" | grep -q "$BRANCH_NAME"; then
+            echo "::warning::Sync branch already exists. Deleting and recreating..."
+            git push origin --delete "$BRANCH_NAME" || true
+          fi
+          
+          # Create new branch from current main
+          git checkout -b "$BRANCH_NAME"
+          
+          echo "Merging upstream/main into sync branch..."
+          
+          # =====================================================================
+          # EXPECTED CONFLICT FILES (Translation Fork)
+          # These files are expected to conflict because they are intentionally
+          # different in this English fork vs the Chinese upstream.
+          # =====================================================================
+          EXPECTED_CONFLICT_FILES="README.md"
+          
+          # Attempt merge with upstream
+          # Using --no-edit to auto-generate merge commit message
+          if git merge upstream/main --no-edit --allow-unrelated-histories; then
+            echo "merge_success=true" >> $GITHUB_OUTPUT
+            echo "auto_resolved=false" >> $GITHUB_OUTPUT
+            echo "::notice::Merge successful (no conflicts)"
+          else
+            echo "::warning::Merge conflicts detected. Checking if auto-resolvable..."
+            
+            # Get list of conflicting files
+            CONFLICTING_FILES=$(git diff --name-only --diff-filter=U)
+            echo "Conflicting files:"
+            echo "$CONFLICTING_FILES"
+            
+            # Check if all conflicts are in expected files
+            UNEXPECTED_CONFLICTS=""
+            for file in $CONFLICTING_FILES; do
+              IS_EXPECTED=false
+              for expected in $EXPECTED_CONFLICT_FILES; do
+                if [ "$file" = "$expected" ]; then
+                  IS_EXPECTED=true
+                  break
+                fi
+              done
+              
+              if [ "$IS_EXPECTED" = false ]; then
+                UNEXPECTED_CONFLICTS="$UNEXPECTED_CONFLICTS $file"
+              fi
+            done
+            
+            # Trim whitespace
+            UNEXPECTED_CONFLICTS=$(echo "$UNEXPECTED_CONFLICTS" | xargs)
+            
+            if [ -n "$UNEXPECTED_CONFLICTS" ]; then
+              # Unexpected conflicts found - fail the workflow
+              echo "merge_success=false" >> $GITHUB_OUTPUT
+              echo "auto_resolved=false" >> $GITHUB_OUTPUT
+              echo "::error::Unexpected conflicts in: $UNEXPECTED_CONFLICTS"
+              echo "::error::Manual intervention required for these files."
+              
+              # Abort the merge to leave clean state
+              git merge --abort
+              exit 1
+            else
+              # Only expected conflicts - auto-resolve by keeping fork's version
+              echo "::notice::All conflicts are in expected files. Auto-resolving..."
+              
+              for file in $CONFLICTING_FILES; do
+                echo "  Resolving $file by keeping fork's version (--ours)..."
+                git checkout --ours "$file"
+                git add "$file"
+              done
+              
+              # Complete the merge with resolved conflicts
+              git commit --no-edit
+              
+              echo "merge_success=true" >> $GITHUB_OUTPUT
+              echo "auto_resolved=true" >> $GITHUB_OUTPUT
+              echo "::notice::Merge successful (auto-resolved expected conflicts)"
+            fi
+          fi
+
+      # -----------------------------------------------------------------------
+      # Step 6: Push sync branch to origin
+      # -----------------------------------------------------------------------
+      - name: Push Sync Branch
+        if: steps.create_branch.outputs.merge_success == 'true'
+        run: |
+          echo "Pushing sync branch to origin..."
+          git push origin "${{ steps.create_branch.outputs.branch_name }}"
+          echo "::notice::Sync branch pushed successfully"
+
+      # -----------------------------------------------------------------------
+      # Step 7: Create Pull Request
+      # -----------------------------------------------------------------------
+      - name: Create Pull Request
+        if: steps.create_branch.outputs.merge_success == 'true'
+        uses: peter-evans/create-pull-request@v7
+        id: create_pr
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ steps.create_branch.outputs.branch_name }}
+          base: main
+          title: "chore: Sync with upstream [${{ steps.check_changes.outputs.sync_date }}]"
+          body: |
+            ## Upstream Sync
+
+            This PR syncs the fork with the upstream repository.
+
+            ### Summary
+            - **Upstream Repository**: [CJackHwang/AIstudioProxyAPI](https://github.com/CJackHwang/AIstudioProxyAPI)
+            - **Commits Behind**: ${{ steps.check_changes.outputs.commits_behind }}
+            - **Sync Date**: ${{ steps.check_changes.outputs.sync_date }}
+            - **Auto-resolved Conflicts**: ${{ steps.create_branch.outputs.auto_resolved == 'true' && '✅ Yes (README.md kept from fork)' || '❌ None' }}
+
+            ### Recent Upstream Commits
+            ```
+            ${{ steps.check_changes.outputs.commit_log }}
+            ```
+
+            ### Review Notes
+            - Please review changes carefully before merging
+            - Check for any conflicts with fork-specific modifications
+            - Ensure translation/localization files are preserved
+            ${{ steps.create_branch.outputs.auto_resolved == 'true' && '- ⚠️ **README.md conflict was auto-resolved** - The English README from this fork was preserved' || '' }}
+
+            ---
+            *This PR was automatically generated by the [Upstream Sync Workflow](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})*
+          labels: |
+            upstream-sync
+            automated
+          draft: false
+          delete-branch: false
+
+      # -----------------------------------------------------------------------
+      # Step 8: Output Results
+      # -----------------------------------------------------------------------
+      - name: Output Results
+        if: always()
+        run: |
+          echo "=========================================="
+          echo "Upstream Sync Workflow Complete"
+          echo "=========================================="
+          echo ""
+          
+          if [ "${{ steps.check_changes.outputs.has_changes }}" == "true" ]; then
+            echo "Status: Changes detected from upstream"
+            echo "Commits behind: ${{ steps.check_changes.outputs.commits_behind }}"
+            
+            if [ "${{ steps.create_branch.outputs.merge_success }}" == "true" ]; then
+              echo "Merge: Successful"
+              
+              if [ "${{ steps.create_branch.outputs.auto_resolved }}" == "true" ]; then
+                echo "Conflicts: Auto-resolved (expected files only)"
+                echo "  - README.md: Kept fork's English version"
+              else
+                echo "Conflicts: None"
+              fi
+              
+              echo "PR Created: Yes"
+              echo "Branch: ${{ steps.create_branch.outputs.branch_name }}"
+            else
+              echo "Merge: Failed (unexpected conflicts detected)"
+              echo "PR Created: No"
+              echo ""
+              echo "Manual intervention required to resolve conflicts."
+              echo "Expected conflict files (auto-resolved): README.md"
+              echo "Unexpected conflicts require manual resolution."
+            fi
+          else
+            echo "Status: Fork is up to date with upstream"
+            echo "No action required."
+          fi
+          
+          echo ""
+          echo "=========================================="

.gitignore

@@ -0,0 +1,296 @@
+# Logs
+logs
+*.log
+certs/*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+/upload_images
+/upload_files
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+coverage_*.txt
+coverage_*.html
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# Windows artifacts
+NUL
+
+# Test backup files
+*.backup
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the next line if you're using Gatsby Cloud
+# .gatsby/
+public
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# macOS files
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear on external disk
+.Spotlight-V100
+.Trashes
+
+# Temporary files created by editors
+*~
+#*.swp
+
+# IDE config folders
+.idea/
+.vscode/
+
+# Custom
+errors/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Python Libraries
+*.egg-info/
+*.egg
+
+# Distribution / packaging
+.Python
+build/
+dist/
+part/
+sdist/
+*.manifest
+*.spec
+wheels/
+
+# PyInstaller
+# Usually these files are written by a python script from a template
+# before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.testmondata*
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Error snapshots directory (Python specific)
+# New date-based structure: errors_py/YYYY-MM-DD/HH-MM-SS_reqid_errorname/
+errors_py/*/
+!errors_py/.gitkeep
+logs/
+errors_py
+
+# Authentication Profiles (Sensitive)
+auth_profiles/active/*
+!auth_profiles/active/.gitkeep
+auth_profiles/saved/*
+!auth_profiles/saved/.gitkeep
+auth_profiles/emergency/*
+!auth_profiles/emergency/.gitkeep
+config/profile_usage.json
+config/cooldown_status.json
+auth_profiles/locked
+auth_profilesBackup
+
+# Camoufox/Playwright Profile Data (Assume these are generated/temporary)
+camoufox_profile/
+chrome_temp_profile/
+
+# Deprecated Javascript Version node_modules
+deprecated_javascript_version/node_modules/ 
+
+.roomodes
+memory-bank/
+gui_config.json
+.rooignore
+.kiloignore
+.kilocodeignore
+
+# key
+key.txt
+
+# 脚本注入相关文件
+# 用户自定义的模型配置文件（保留示例文件）
+browser_utils/model_configs.json
+browser_utils/my_*.json
+# 用户自定义的油猴脚本（如果不是默认的）
+browser_utils/custom_*.js
+browser_utils/my_*.js
+# 临时生成的脚本文件
+browser_utils/generated_*.js
+# Docker 环境的实际配置文件（保留示例文件）
+docker/.env
+docker/my_*.json
+
+monkeytype.sqlite3
+
+# Pyright output
+baseline_pyright.txt
+pyright_*.txt
+
+# Ruff cache (explicit)
+.ruff_cache/
+
+# Temporary debug/output files
+pyright_output.txt
+pyright_utils_full.txt
+temp_*.txt
+temp_*.md
+utils_errors.txt
+# React frontend build artifacts and dependencies
+static/frontend/node_modules/
+static/frontend/coverage/
+static/frontend/dist/
+
+# GUI Launcher user config (contains user-specific settings)
+gui/user_config.json
+
+.multi-instance-runtime/

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# 贡献指南
+
+感谢你参与 AI Studio Proxy API 的改进。
+
+## 本地开发准备
+
+```bash
+git clone https://github.com/CJackHwang/AIstudioProxyAPI.git
+cd AIstudioProxyAPI
+poetry install --with dev
+```
+
+## 提交前检查（必须）
+
+```bash
+poetry run ruff check .
+poetry run pyright
+poetry run pytest
+```
+
+如涉及前端改动，请额外执行：
+
+```bash
+cd static/frontend
+npm ci
+npm run build
+npm run test
+```
+
+## 分支与提交规范
+
+- 新功能：`feat/...`
+- 缺陷修复：`fix/...`
+- 文档改动：`docs/...`
+- 重构：`refactor/...`
+
+建议使用 Conventional Commits：
+
+- `feat:` 新能力
+- `fix:` 缺陷修复
+- `docs:` 文档更新
+- `refactor:` 重构
+- `test:` 测试改进
+- `chore:` 工程性调整
+
+## Pull Request 要求
+
+- 说明变更动机、核心实现和影响范围。
+- 如涉及配置/接口变更，必须更新文档。
+- 引入新环境变量时，必须同步更新 `.env.example`。
+- 通过 CI 检查后再请求合并。
+
+## CI/CD 工作流
+
+- `PR Check`：运行 lint/typecheck/tests。
+- `Release`：tag 或手动触发发布。
+- `Sync with Upstream`：从上游仓库同步提交并自动建 PR。
+
+## 参考文档
+
+- [快速开始](docs/quick-start.md)
+- [配置参考](docs/configuration-reference.md)
+- [排障指南](docs/troubleshooting.md)
+- [开发、测试与发布](docs/development-and-release.md)
+
+## Issue 反馈建议
+
+请尽量提供：
+
+- 复现步骤
+- 期望行为与实际行为
+- Python 版本 / 操作系统
+- 相关日志（如 `logs/`、`errors_py/`）

Dockerfile

@@ -0,0 +1,98 @@
+# Hugging Face Spaces Dockerfile.
+# The original Docker setup lives in docker/Dockerfile; this root Dockerfile is
+# required by Spaces and keeps the public HTTP service on port 7860.
+FROM python:3.10-slim-bookworm AS builder
+
+ARG DEBIAN_FRONTEND=noninteractive
+ARG PROXY_ADDR
+
+RUN if [ -n "$PROXY_ADDR" ]; then \
+        printf 'Acquire::http::Proxy "%s";\nAcquire::https::Proxy "%s";\n' "$PROXY_ADDR" "$PROXY_ADDR" > /etc/apt/apt.conf.d/99proxy; \
+    fi && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends curl && \
+    apt-get clean && rm -rf /var/lib/apt/lists/* && \
+    if [ -n "$PROXY_ADDR" ]; then rm -f /etc/apt/apt.conf.d/99proxy; fi
+
+ENV HTTP_PROXY=${PROXY_ADDR}
+ENV HTTPS_PROXY=${PROXY_ADDR}
+ENV POETRY_HOME="/opt/poetry"
+ENV POETRY_VERSION=1.8.3
+ENV PATH="${POETRY_HOME}/bin:${PATH}"
+
+RUN curl -sSL https://install.python-poetry.org | python3 - --version ${POETRY_VERSION}
+
+WORKDIR /app_builder
+COPY pyproject.toml poetry.lock ./
+RUN poetry config virtualenvs.create false --local && \
+    poetry install --only main --no-root --no-interaction --no-ansi
+
+FROM python:3.10-slim-bookworm
+
+ARG DEBIAN_FRONTEND=noninteractive
+ARG PROXY_ADDR
+
+ENV HTTP_PROXY=${PROXY_ADDR}
+ENV HTTPS_PROXY=${PROXY_ADDR}
+
+RUN if [ -n "$PROXY_ADDR" ]; then \
+        printf 'Acquire::http::Proxy "%s";\nAcquire::https::Proxy "%s";\n' "$PROXY_ADDR" "$PROXY_ADDR" > /etc/apt/apt.conf.d/99proxy; \
+    fi && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends \
+        ca-certificates curl fonts-liberation \
+        libasound2 libatk-bridge2.0-0 libatk1.0-0 libcups2 libdbus-1-3 \
+        libdrm2 libgbm1 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 \
+        libpangocairo-1.0-0 libu2f-udev libx11-6 libx11-xcb1 libxcb1 \
+        libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 \
+        libxrender1 libxtst6 && \
+    apt-get clean && rm -rf /var/lib/apt/lists/* && \
+    if [ -n "$PROXY_ADDR" ]; then rm -f /etc/apt/apt.conf.d/99proxy; fi
+
+RUN groupadd -r appgroup && useradd -r -g appgroup -s /bin/bash -d /app appuser
+
+WORKDIR /app
+
+COPY --from=builder /usr/local/lib/python3.10/site-packages/ /usr/local/lib/python3.10/site-packages/
+COPY --from=builder /usr/local/bin/ /usr/local/bin/
+COPY --from=builder /opt/poetry/bin/poetry /usr/local/bin/poetry
+COPY . .
+
+RUN camoufox fetch && \
+    python -m playwright install firefox && \
+    python scripts/update_browserforge_data.py
+
+RUN mkdir -p /var/cache/camoufox && \
+    if [ -d /root/.cache/camoufox ]; then cp -a /root/.cache/camoufox/. /var/cache/camoufox/; fi && \
+    mkdir -p /app/.cache && \
+    ln -s /var/cache/camoufox /app/.cache/camoufox && \
+    mkdir -p /app/logs \
+        /app/auth_profiles/active \
+        /app/auth_profiles/saved \
+        /app/auth_profiles/emergency \
+        /app/certs \
+        /app/browser_utils/custom_scripts \
+        /home/appuser/.cache/ms-playwright \
+        /home/appuser/.mozilla && \
+    chown -R appuser:appgroup /app /home/appuser /var/cache/camoufox
+
+USER appuser
+
+ENV HOME=/app
+ENV PLAYWRIGHT_BROWSERS_PATH=/home/appuser/.cache/ms-playwright
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+ENV SERVER_PORT=7860
+ENV DEFAULT_FASTAPI_PORT=7860
+ENV DEFAULT_CAMOUFOX_PORT=9222
+ENV STREAM_PORT=3120
+ENV SERVER_LOG_LEVEL=INFO
+ENV DEBUG_LOGS_ENABLED=false
+ENV AUTO_CONFIRM_LOGIN=true
+ENV INTERNAL_CAMOUFOX_PROXY=""
+ENV HTTP_PROXY=""
+ENV HTTPS_PROXY=""
+
+EXPOSE 7860
+
+CMD ["python", "scripts/huggingface/entrypoint.py"]

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published
+    by the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

README.md

@@ -0,0 +1,214 @@
+---
+title: AI Studio Proxy API
+sdk: docker
+app_port: 7860
+license: agpl-3.0
+---
+
+# AI Studio Proxy API
+
+将 Google AI Studio 网页界面转换为 OpenAI 兼容 API 的代理服务。通过 Camoufox + Playwright 自动化，提供稳定可控的 API 访问。
+
+[![Star History Chart](https://api.star-history.com/svg?repos=CJackHwang/AIstudioProxyAPI&type=Date)](https://www.star-history.com/#CJackHwang/AIstudioProxyAPI&Date)
+
+---
+
+## 主要特性
+
+- **OpenAI 兼容 API**：支持 `/v1/chat/completions`、`/v1/models`
+- **函数调用三模式**：`auto` / `native` / `emulated`，支持失败回退
+- **认证轮转与 Cookie 刷新**：支持 profile 自动轮转、周期刷新与关停保存
+- **启动链路完整**：CLI 启动器、内置 Web UI、桌面 GUI 启动器
+- **现代化前端**：内置设置页、状态检查与日志能力
+- **CI/CD 工作流**：PR 检查、Release、Upstream Sync
+
+## 系统要求
+
+| 组件 | 要求 | 推荐 |
+| --- | --- | --- |
+| Python | >=3.9, <4.0 | 3.10+ / 3.11+ |
+| 依赖管理 | Poetry | 最新版本 |
+| Node.js | 前端构建需要 | LTS |
+| 内存 | >=2GB | >=4GB |
+
+---
+
+## 🚀 快速开始
+
+### 1. 克隆并安装
+
+```bash
+git clone https://github.com/CJackHwang/AIstudioProxyAPI.git
+cd AIstudioProxyAPI
+poetry install --with dev
+```
+
+### 2. 配置环境
+
+```bash
+cp .env.example .env
+```
+
+建议先确认：`PORT`、`STREAM_PORT`、`UNIFIED_PROXY_CONFIG`、`LAUNCH_MODE`、`FUNCTION_CALLING_MODE`。
+
+### 3. 首次认证并启动
+
+```bash
+# 首次建议 debug，完成登录并保存 auth
+poetry run python launch_camoufox.py --debug
+
+# 日常建议 headless
+poetry run python launch_camoufox.py --headless
+```
+
+### 快速测试
+
+```bash
+# 健康检查
+curl http://127.0.0.1:2048/health
+
+# 模型列表
+curl http://127.0.0.1:2048/v1/models
+
+# 聊天请求
+curl -X POST http://127.0.0.1:2048/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gemini-2.5-pro","messages":[{"role":"user","content":"你好"}]}'
+```
+
+访问 `http://127.0.0.1:2048/` 使用内置 Web UI。
+
+---
+
+## 系统架构
+
+```mermaid
+graph TD
+    subgraph "用户端"
+        User["用户"]
+        WebUI["Web UI"]
+        APIClient["API 客户端"]
+    end
+
+    subgraph "启动与配置"
+        Launcher["launch_camoufox.py"]
+        Env[".env 配置"]
+    end
+
+    subgraph "核心服务"
+        FastAPI["FastAPI 应用<br/>api_utils/"]
+        BrowserOps["页面控制与自动化<br/>browser_utils/"]
+        StreamProxy["流式代理<br/>stream/"]
+    end
+
+    subgraph "外部依赖"
+        Camoufox["Camoufox 浏览器"]
+        AIStudio["Google AI Studio"]
+    end
+
+    User --> Launcher
+    Launcher --> Env
+    WebUI --> FastAPI
+    APIClient --> FastAPI
+    FastAPI --> BrowserOps
+    FastAPI --> StreamProxy
+    BrowserOps --> Camoufox --> AIStudio
+    StreamProxy --> AIStudio
+```
+
+---
+
+## 运行模式
+
+| 命令 | 说明 | 场景 |
+| --- | --- | --- |
+| `python launch_camoufox.py --headless` | 无头模式 | 日常使用、服务器 |
+| `python launch_camoufox.py --debug` | 调试模式 | 首次认证、故障排查 |
+| `python launch_camoufox.py --virtual-display` | 虚拟显示 | Linux 无 GUI 环境 |
+
+---
+
+## ⚙️ 配置
+
+项目使用 `.env` 统一配置管理：
+
+```bash
+cp .env.example .env
+```
+
+核心配置示例：
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `PORT` | `2048` | 主 API 端口 |
+| `STREAM_PORT` | `3120` | 流式代理端口（`0` 关闭） |
+| `UNIFIED_PROXY_CONFIG` | 空 | HTTP/HTTPS 代理 |
+| `AUTO_ROTATE_AUTH_PROFILE` | `true` | 认证自动轮转 |
+| `FUNCTION_CALLING_MODE` | `auto` | 函数调用模式 |
+
+详细项见：[配置参考](docs/configuration-reference.md)
+
+> 说明：配置默认值以 `.env.example` 为准；少数配置存在代码兜底默认值，详见配置参考中的说明。
+
+---
+
+## 📚 文档
+
+- [文档总览](docs/README.md)
+- [快速开始](docs/quick-start.md)
+- [部署与运维指南](docs/deployment-and-operations.md)
+- [API 使用说明](docs/api-usage.md)
+- [函数调用模式](docs/function-calling.md)
+- [认证轮转与 Cookie 刷新](docs/auth-rotation-cookie-refresh.md)
+- [排障指南](docs/troubleshooting.md)
+- [开发、测试与发布](docs/development-and-release.md)
+- [多实例 Docker 管理器](scripts/multi-instance-manager/README.md)
+
+---
+
+## 客户端配置示例
+
+以 Open WebUI 为例：
+
+1. 进入设置 -> 连接
+2. API Base URL 填 `http://127.0.0.1:2048/v1`
+3. 若你未配置 API Keys，可留空或填任意字符；若已配置，请填写有效 Key
+4. 保存后即可对话
+
+---
+
+## 开发检查
+
+```bash
+poetry run ruff check .
+poetry run pyright
+poetry run pytest
+```
+
+前端构建：
+
+```bash
+cd static/frontend
+npm ci
+npm run build
+```
+
+---
+
+## 致谢
+
+- **项目发起与主要开发**: [@CJackHwang](https://github.com/CJackHwang)
+- **核心维护**（架构重构、测试体系）: [@NikkeTryHard](https://github.com/NikkeTryHard)
+- **功能完善、页面操作优化**: [@ayuayue](https://github.com/ayuayue)
+- **实时流式功能优化**: [@luispater](https://github.com/luispater)
+- **项目重构贡献**: [@yattin](https://github.com/yattin)（Holt）
+- **下游维护分支致谢作者**: [@MasuRii](https://github.com/MasuRii)
+- **社区支持**: [Linux.do 社区](https://linux.do/)
+
+## License
+
+[AGPLv3](LICENSE)
+
+## 支持作者
+
+如果本项目对你有帮助，欢迎支持作者持续开发。

api_utils/__init__.py

@@ -0,0 +1,74 @@
+"""
+API Utilities Module
+Provides FastAPI application initialization, route handlers, and utility functions
+"""
+
+# Application initialization
+from .app import create_app
+
+# Queue worker
+from .queue_worker import queue_worker
+
+# Request processor
+from .request_processor import (
+    _process_request_refactored,  # pyright: ignore[reportPrivateUsage]
+)
+
+# Route handlers (aggregated from routers)
+from .routers import (
+    cancel_request,
+    chat_completions,
+    get_api_info,
+    get_queue_status,
+    health_check,
+    list_models,
+    read_index,
+    websocket_log_endpoint,
+)
+from .sse import (
+    generate_sse_chunk,
+    generate_sse_error_chunk,
+    generate_sse_stop_chunk,
+)
+
+# Utility functions
+from .utils import prepare_combined_prompt
+from .utils_ext.helper import use_helper_get_response
+from .utils_ext.stream import (
+    clear_stream_queue,
+    use_stream_response,
+)
+from .utils_ext.tokens import (
+    calculate_usage_stats,
+    estimate_tokens,
+)
+from .utils_ext.validation import validate_chat_request
+
+__all__ = [
+    # Application initialization
+    "create_app",
+    # Route handlers
+    "read_index",
+    "get_api_info",
+    "health_check",
+    "list_models",
+    "chat_completions",
+    "cancel_request",
+    "get_queue_status",
+    "websocket_log_endpoint",
+    # Utility functions
+    "generate_sse_chunk",
+    "generate_sse_stop_chunk",
+    "generate_sse_error_chunk",
+    "use_stream_response",
+    "clear_stream_queue",
+    "use_helper_get_response",
+    "validate_chat_request",
+    "prepare_combined_prompt",
+    "estimate_tokens",
+    "calculate_usage_stats",
+    # Request processor
+    "_process_request_refactored",
+    # Queue worker
+    "queue_worker",
+]

api_utils/app.py

@@ -0,0 +1,454 @@
+"""
+FastAPI application initialization and lifecycle management
+"""
+
+import asyncio
+import multiprocessing
+import queue
+import sys
+import time
+from asyncio import Lock, Queue
+from contextlib import asynccontextmanager
+from typing import Awaitable, Callable
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+import stream
+from api_utils.server_state import state
+
+# --- browser_utils module imports ---
+from browser_utils import (
+    _close_page_logic,
+    _handle_initial_model_state_and_storage,
+    _initialize_page_logic,
+    enable_temporary_chat_mode,
+    load_excluded_models,
+)
+
+# --- Configuration imports ---
+from config import EXCLUDED_MODELS_FILENAME, NO_PROXY_ENV, get_environment_variable
+
+# --- logging_utils module imports ---
+from logging_utils import restore_original_streams, setup_server_logging
+
+# --- models module imports ---
+from models import WebSocketConnectionManager
+
+from . import auth_utils
+
+VERSION = "0.1.0"
+
+
+# --- Lifespan Context Manager ---
+def _setup_logging():
+    log_level_env = get_environment_variable("SERVER_LOG_LEVEL", "INFO")
+    redirect_print_env = get_environment_variable("SERVER_REDIRECT_PRINT", "false")
+    state.log_ws_manager = WebSocketConnectionManager()
+    return setup_server_logging(
+        logger_instance=state.logger,
+        log_ws_manager=state.log_ws_manager,
+        log_level_name=log_level_env,
+        redirect_print_str=redirect_print_env,
+    )
+
+
+def _initialize_globals():
+    from api_utils.server_state import state
+
+    state.request_queue = Queue()
+    state.processing_lock = Lock()
+    state.model_switching_lock = Lock()
+    state.params_cache_lock = Lock()
+
+    # Initialize model_list_fetch_event
+    state.model_list_fetch_event = asyncio.Event()
+
+    auth_utils.initialize_keys()
+
+    # Initialize Auth Rotation Lock
+    from config.global_state import GlobalState
+
+    GlobalState.init_rotation_lock()
+
+    state.logger.info("API keys and global locks initialized.")
+
+
+def _initialize_proxy_settings():
+    stream_port_env = get_environment_variable("STREAM_PORT")
+    if stream_port_env == "0":
+        proxy_server_url = get_environment_variable(
+            "HTTPS_PROXY"
+        ) or get_environment_variable("HTTP_PROXY")
+    else:
+        proxy_server_url = f"http://127.0.0.1:{stream_port_env or 3120}/"
+
+    if proxy_server_url:
+        state.PLAYWRIGHT_PROXY_SETTINGS = {"server": proxy_server_url}
+        if NO_PROXY_ENV:
+            state.PLAYWRIGHT_PROXY_SETTINGS["bypass"] = NO_PROXY_ENV.replace(",", ";")
+        state.logger.info(
+            f"Playwright proxy settings configured: {state.PLAYWRIGHT_PROXY_SETTINGS}"
+        )
+    else:
+        state.logger.info("No proxy configured for Playwright.")
+
+
+async def _start_stream_proxy():
+    stream_port_env = get_environment_variable("STREAM_PORT")
+    if stream_port_env != "0":
+        port = int(stream_port_env or 3120)
+        stream_proxy_server_env = (
+            get_environment_variable("UNIFIED_PROXY_CONFIG")
+            or get_environment_variable("HTTPS_PROXY")
+            or get_environment_variable("HTTP_PROXY")
+        )
+        state.logger.info(
+            f"Starting STREAM proxy on port {port} with upstream proxy: {stream_proxy_server_env}"
+        )
+        state.STREAM_QUEUE = multiprocessing.Queue()
+        state.STREAM_PROCESS = multiprocessing.Process(
+            target=stream.start,
+            args=(state.STREAM_QUEUE, port, stream_proxy_server_env),
+        )
+        state.STREAM_PROCESS.start()
+        state.logger.info("STREAM proxy process started. Waiting for 'READY' signal...")
+
+        try:
+            ready_signal = await asyncio.to_thread(state.STREAM_QUEUE.get, timeout=15)
+            if ready_signal == "READY":
+                state.logger.info(
+                    "[SUCCESS] Received 'READY' signal from STREAM proxy."
+                )
+            else:
+                state.logger.warning(
+                    f"Received unexpected signal from proxy: {ready_signal}"
+                )
+        except queue.Empty:
+            state.logger.error(
+                "[ERROR] Timed out waiting for STREAM proxy to become ready. Startup will likely fail."
+            )
+            raise RuntimeError("STREAM proxy failed to start in time.")
+
+
+async def _initialize_browser_and_page():
+    from playwright.async_api import async_playwright
+
+    state.logger.info("Starting Playwright...")
+    state.playwright_manager = await async_playwright().start()
+    state.is_playwright_ready = True
+    state.logger.info("Playwright started.")
+
+    ws_endpoint = get_environment_variable("CAMOUFOX_WS_ENDPOINT")
+    launch_mode = get_environment_variable("LAUNCH_MODE", "unknown")
+
+    if not ws_endpoint and launch_mode != "direct_debug_no_browser":
+        raise ValueError("CAMOUFOX_WS_ENDPOINT environment variable is missing.")
+
+    if ws_endpoint:
+        state.logger.info(f"Connecting to browser at: {ws_endpoint}")
+        state.browser_instance = await state.playwright_manager.firefox.connect(
+            ws_endpoint, timeout=30000
+        )
+        state.is_browser_connected = True
+        state.logger.info(f"Connected to browser: {state.browser_instance.version}")
+
+        state.page_instance, state.is_page_ready = await _initialize_page_logic(
+            state.browser_instance
+        )
+        if state.is_page_ready:
+            await _handle_initial_model_state_and_storage(state.page_instance)
+            await enable_temporary_chat_mode(state.page_instance)
+            state.logger.info("Page initialized successfully.")
+        else:
+            state.logger.error("Page initialization failed.")
+            state.page_instance = None
+            state.is_page_ready = False
+            state.current_ai_studio_model_id = None
+
+    if not state.model_list_fetch_event.is_set():
+        state.model_list_fetch_event.set()
+
+
+async def _shutdown_resources():
+    logger = state.logger
+    logger.info("Shutting down resources...")
+
+    # Signal global shutdown if event exists
+    try:
+        from config import GlobalState
+
+        if hasattr(GlobalState, "IS_SHUTTING_DOWN") and hasattr(
+            GlobalState.IS_SHUTTING_DOWN, "set"
+        ):
+            GlobalState.IS_SHUTTING_DOWN.set()
+    except Exception as e:
+        logger.debug(f"Failed to set IS_SHUTTING_DOWN: {e}")
+
+    state.should_exit = True
+
+    if state.STREAM_PROCESS:
+        try:
+            state.STREAM_PROCESS.terminate()
+            state.STREAM_PROCESS.join(timeout=3)
+            if state.STREAM_PROCESS.is_alive():
+                logger.warning("STREAM proxy did not terminate, killing...")
+                state.STREAM_PROCESS.kill()
+                state.STREAM_PROCESS.join(timeout=1)
+        except Exception as e:
+            logger.error(f"Error terminating STREAM proxy: {e}")
+        finally:
+            if state.STREAM_QUEUE:
+                try:
+                    state.STREAM_QUEUE.close()
+                    state.STREAM_QUEUE.join_thread()
+                except Exception:
+                    pass
+            state.STREAM_PROCESS = None
+            state.STREAM_QUEUE = None
+            logger.info("STREAM proxy terminated.")
+
+    if state.worker_task and not state.worker_task.done():
+        logger.info("Cancelling worker task...")
+        state.worker_task.cancel()
+        try:
+            await asyncio.wait_for(state.worker_task, timeout=2.0)
+            logger.info("Worker task cancelled.")
+        except asyncio.TimeoutError:
+            logger.warning("Worker task did not respond to cancellation within 2s.")
+        except asyncio.CancelledError:
+            logger.debug("Worker task cancellation acknowledged (CancelledError).")
+        except Exception as e:
+            logger.error(f"Error cancelling worker task: {e}")
+        finally:
+            state.worker_task = None
+
+    if state.page_instance:
+        try:
+            await _close_page_logic()
+        except asyncio.CancelledError:
+            logger.debug("Page closure cancelled (CancelledError).")
+        except Exception as e:
+            logger.error(f"Error during page closure: {e}")
+        finally:
+            state.page_instance = None
+            state.is_page_ready = False
+
+    if state.browser_instance:
+        try:
+            if state.browser_instance.is_connected():
+                await state.browser_instance.close()
+                logger.info("Browser connection closed.")
+        except asyncio.CancelledError:
+            logger.debug("Browser closure cancelled (CancelledError).")
+        except Exception as e:
+            logger.error(f"Error during browser closure: {e}")
+        finally:
+            state.browser_instance = None
+            state.is_browser_connected = False
+
+    if state.playwright_manager:
+        try:
+            await state.playwright_manager.stop()
+            logger.info("Playwright stopped.")
+        except asyncio.CancelledError:
+            logger.debug("Playwright stop cancelled (CancelledError).")
+        except Exception as e:
+            logger.error(f"Error stopping playwright: {e}")
+        finally:
+            state.playwright_manager = None
+            state.is_playwright_ready = False
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """FastAPI application lifecycle management"""
+    from .queue_worker import queue_worker
+
+    original_streams = sys.stdout, sys.stderr
+    initial_stdout, initial_stderr = _setup_logging()
+    logger = state.logger
+
+    _initialize_globals()
+    _initialize_proxy_settings()
+    load_excluded_models(EXCLUDED_MODELS_FILENAME)
+
+    state.is_initializing = True
+    startup_start_time = time.time()
+    logger.info("Starting AI Studio Proxy Server...")
+
+    try:
+        await _start_stream_proxy()
+        await _initialize_browser_and_page()
+
+        launch_mode = get_environment_variable("LAUNCH_MODE", "unknown")
+        if state.is_page_ready or launch_mode == "direct_debug_no_browser":
+            state.worker_task = asyncio.create_task(queue_worker())
+            logger.info("Request processing worker started.")
+        else:
+            raise RuntimeError("Failed to initialize browser/page, worker not started.")
+
+        logger.info("[WATCHDOG] Starting Quota Watchdog Task...")
+        watchdog_func = state.quota_watchdog
+        if watchdog_func:
+            app.state.watchdog_task = asyncio.create_task(watchdog_func())
+        else:
+            logger.warning(
+                "[WATCHDOG] Quota Watchdog function not found, task not started."
+            )
+
+        # Start periodic cookie refresh task
+        try:
+            from browser_utils.cookie_refresh import start_periodic_refresh
+
+            cookie_refresh_task = start_periodic_refresh()
+            if cookie_refresh_task:
+                app.state.cookie_refresh_task = cookie_refresh_task
+        except Exception as e:
+            logger.warning(f"[COOKIE-REFRESH] Failed to start periodic refresh: {e}")
+
+        startup_duration = time.time() - startup_start_time
+        logger.info(f"Server startup complete. (Took: {startup_duration:.2f}s)")
+        state.is_initializing = False
+        yield
+    except Exception as e:
+        logger.critical(f"Application startup failed: {e}", exc_info=True)
+        await _shutdown_resources()
+        raise RuntimeError(f"Application startup failed: {e}") from e
+    finally:
+        logger.info("Shutting down server...")
+
+        # Stop periodic cookie refresh and save cookies before shutdown
+        if hasattr(app.state, "cookie_refresh_task"):
+            logger.info("[STOP] Stopping Cookie Refresh Task...")
+            try:
+                from browser_utils.cookie_refresh import (
+                    save_cookies_on_shutdown,
+                    stop_periodic_refresh,
+                )
+
+                await stop_periodic_refresh()
+                # Save cookies one final time before shutdown
+                await save_cookies_on_shutdown()
+            except Exception as e:
+                logger.warning(f"[COOKIE-REFRESH] Shutdown save error: {e}")
+
+        if hasattr(app.state, "watchdog_task"):
+            logger.info("[STOP] Stopping Quota Watchdog...")
+            task = app.state.watchdog_task
+            if hasattr(task, "cancel"):
+                task.cancel()
+                # Only await if it's actually an asyncio task or future
+                if isinstance(task, (asyncio.Task, asyncio.Future)):
+                    try:
+                        await task
+                    except asyncio.CancelledError:
+                        pass
+
+        try:
+            await _shutdown_resources()
+        finally:
+            restore_original_streams(initial_stdout, initial_stderr)
+            restore_original_streams(*original_streams)
+            logger.info("Server shut down.")
+
+
+class APIKeyAuthMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app: ASGIApp):
+        super().__init__(app)
+        self.excluded_paths = [
+            "/v1/models",
+            "/health",
+            "/docs",
+            "/openapi.json",
+            "/redoc",
+            "/favicon.ico",
+        ]
+
+    async def dispatch(
+        self, request: Request, call_next: Callable[[Request], Awaitable]
+    ):
+        if not auth_utils.API_KEYS:
+            return await call_next(request)
+        if not request.url.path.startswith("/v1/"):
+            return await call_next(request)
+        for excluded_path in self.excluded_paths:
+            if request.url.path == excluded_path or request.url.path.startswith(
+                excluded_path + "/"
+            ):
+                return await call_next(request)
+        api_key = request.headers.get("Authorization")
+        if api_key and api_key.startswith("Bearer "):
+            api_key = api_key[7:]
+        if not api_key:
+            api_key = request.headers.get("X-API-Key")
+        if not api_key or not auth_utils.verify_api_key(api_key):
+            return JSONResponse(
+                status_code=401,
+                content={
+                    "error": {
+                        "message": "Invalid or missing API key. Please provide a valid API key using 'Authorization: Bearer <your_key>' or 'X-API-Key: <your_key>' header.",
+                        "type": "invalid_request_error",
+                        "param": None,
+                        "code": "invalid_api_key",
+                    }
+                },
+            )
+        return await call_next(request)
+
+
+def create_app() -> FastAPI:
+    """Create FastAPI application instance"""
+    app = FastAPI(
+        title="AI Studio Proxy Server (Integrated Mode)",
+        description="Proxy server interacting with AI Studio via Playwright.",
+        version=VERSION,
+        lifespan=lifespan,
+    )
+    app.add_middleware(APIKeyAuthMiddleware)
+    from fastapi.responses import FileResponse
+
+    from .routers import (
+        add_api_key,
+        auth_files_router,
+        cancel_request,
+        chat_completions,
+        delete_api_key,
+        get_api_info,
+        get_api_keys,
+        get_queue_status,
+        health_check,
+        list_models,
+        model_capabilities_router,
+        ports_router,
+        proxy_router,
+        read_index,
+        serve_react_assets,
+        test_api_key,
+        websocket_log_endpoint,
+    )
+
+    app.get("/", response_class=FileResponse)(read_index)
+    app.get("/assets/{filename:path}")(serve_react_assets)
+    app.get("/api/info")(get_api_info)
+    app.get("/health")(health_check)
+    app.get("/v1/models")(list_models)
+    app.post("/v1/chat/completions")(chat_completions)
+    app.post("/v1/cancel/{req_id}")(cancel_request)
+    app.get("/v1/queue")(get_queue_status)
+    app.websocket("/ws/logs")(websocket_log_endpoint)
+    app.include_router(model_capabilities_router)
+    app.include_router(proxy_router)
+    app.include_router(auth_files_router)
+    app.include_router(ports_router)
+    from api_utils.routers import helper_router, server_router
+
+    app.include_router(server_router)
+    app.include_router(helper_router)
+    app.get("/api/keys")(get_api_keys)
+    app.post("/api/keys")(add_api_key)
+    app.post("/api/keys/test")(test_api_key)
+    app.delete("/api/keys")(delete_api_key)
+    return app

api_utils/auth_manager.py

@@ -0,0 +1,89 @@
+import asyncio
+import glob
+import logging
+import os
+from typing import List, Optional, Set
+
+from launcher.config import SAVED_AUTH_DIR
+
+logger = logging.getLogger("AuthManager")
+
+
+class AuthManager:
+    """
+    Manages authentication profiles for rotation and error recovery.
+    """
+
+    def __init__(self) -> None:
+        self.failed_profiles: Set[str] = set()
+        self.current_profile: Optional[str] = None
+
+        # Initialize with the profile from environment if available
+        initial_profile = os.environ.get("ACTIVE_AUTH_JSON_PATH")
+        if initial_profile:
+            self.current_profile = initial_profile
+
+    async def get_available_profiles(self) -> List[str]:
+        """List all .json files in the saved auth directory."""
+        if not os.path.exists(SAVED_AUTH_DIR):
+            logger.warning(f"Saved auth directory not found: {SAVED_AUTH_DIR}")
+            return []
+
+        loop = asyncio.get_running_loop()
+        pattern = os.path.join(SAVED_AUTH_DIR, "*.json")
+        # Run glob in executor to avoid blocking the event loop
+        profiles = await loop.run_in_executor(None, glob.glob, pattern)
+        return sorted(profiles)  # Sort for deterministic order
+
+    async def get_next_profile(self) -> str:
+        """
+        Get the next available profile that hasn't failed yet.
+        Raises RuntimeError if no profiles are available.
+        """
+        profiles = await self.get_available_profiles()
+
+        # Get set of basenames for failed profiles (prevents duplicates due to path differences)
+        failed_basenames = {os.path.basename(p) for p in self.failed_profiles}
+        current_basename = (
+            os.path.basename(self.current_profile) if self.current_profile else None
+        )
+
+        # Filter out failed profiles by basename comparison
+        available = [
+            p
+            for p in profiles
+            if os.path.basename(p) not in failed_basenames
+            and os.path.basename(p)
+            != current_basename  # Also exclude the current profile
+        ]
+
+        if not available:
+            msg = f"All authentication profiles exhausted. Failed: {len(self.failed_profiles)}, Total: {len(profiles)}"
+            logger.critical(msg)
+            raise RuntimeError(msg)
+
+        # Simple strategy: Pick the first available one.
+        next_profile = available[0]
+        self.current_profile = next_profile
+        logger.info(f"Switched to auth profile: {os.path.basename(next_profile)}")
+        return next_profile
+
+    def mark_profile_failed(self, profile_path: Optional[str] = None) -> None:
+        """Mark a profile as failed so it won't be used again in this cycle."""
+        target = profile_path or self.current_profile
+        if target:
+            self.failed_profiles.add(target)
+            logger.warning(f"Marked auth profile as failed: {os.path.basename(target)}")
+        else:
+            logger.warning(
+                "Attempted to mark profile failed but no profile provided or active."
+            )
+
+    def reset_failures(self) -> None:
+        """Reset the failure tracking."""
+        self.failed_profiles.clear()
+        logger.info("Auth profile failure tracking reset.")
+
+
+# Global instance
+auth_manager = AuthManager()

api_utils/auth_utils.py

@@ -0,0 +1,39 @@
+import os
+from typing import Set
+
+API_KEYS: Set[str] = set()
+KEY_FILE_PATH = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+    "auth_profiles",
+    "key.txt",
+)
+
+
+def load_api_keys():
+    """Loads API keys from the key file into the API_KEYS set."""
+    global API_KEYS
+    API_KEYS.clear()
+    if os.path.exists(KEY_FILE_PATH):
+        with open(KEY_FILE_PATH, "r") as f:
+            for line in f:
+                key = line.strip()
+                if key:
+                    API_KEYS.add(key)
+
+
+def initialize_keys():
+    """Initializes API keys. Ensures key.txt exists and loads keys."""
+    if not os.path.exists(KEY_FILE_PATH):
+        with open(KEY_FILE_PATH, "w"):
+            pass  # Create an empty file
+    load_api_keys()
+
+
+def verify_api_key(api_key_from_header: str) -> bool:
+    """
+    Verifies the API key.
+    Returns True if API_KEYS is empty (no validation) or if the key is valid.
+    """
+    if not API_KEYS:
+        return True
+    return api_key_from_header in API_KEYS

api_utils/client_connection.py

@@ -0,0 +1,196 @@
+import asyncio
+from asyncio import Event, Task
+from typing import Any, Callable, Coroutine, Dict, Tuple
+
+from fastapi import HTTPException, Request
+
+from models import ClientDisconnectedError
+
+
+async def check_client_connection(req_id: str, http_request: Request) -> bool:
+    """
+    Checks if the client is still connected.
+    Returns True if connected, False if disconnected.
+    """
+    try:
+        if hasattr(http_request, "_receive"):
+            try:
+                # Use a very short timeout to check for disconnect message
+                # _receive is a private Starlette/FastAPI method that returns a coroutine
+                receive_obj = http_request  # type: ignore[misc]
+                receive_coro: Coroutine[Any, Any, Dict[str, Any]] = (
+                    receive_obj._receive()
+                )  # type: ignore[misc]
+                receive_task: Task[Dict[str, Any]] = asyncio.create_task(receive_coro)
+                done, pending = await asyncio.wait([receive_task], timeout=0.01)
+
+                if done:
+                    message = receive_task.result()
+                    if message.get("type") == "http.disconnect":
+                        return False
+                else:
+                    # Cancel the task if it didn't complete immediately
+                    receive_task.cancel()
+                    try:
+                        await receive_task
+                    except asyncio.CancelledError:
+                        pass
+                    # If it didn't complete immediately, proceed to fallback check
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                # If checking fails, proceed to fallback
+                pass
+
+        # Fallback to is_disconnected() if available (Starlette/FastAPI)
+        # Wrap in wait_for to prevent infinite hang in some ASGI implementations
+        if hasattr(http_request, "is_disconnected"):
+            try:
+                # Handle both sync and async versions for better mock compatibility
+                res = http_request.is_disconnected()
+                if asyncio.iscoroutine(res):
+                    if await asyncio.wait_for(res, timeout=0.01):
+                        return False
+                elif res:
+                    return False
+            except (asyncio.TimeoutError, asyncio.CancelledError):
+                # If it times out, it's likely still connected
+                return True
+
+        return True
+    except asyncio.CancelledError:
+        raise
+    except Exception as e:
+        # Re-raise to allow caller to log/handle
+        raise e
+
+
+async def enhanced_disconnect_monitor(
+    req_id: str,
+    http_request: Request,
+    completion_event: asyncio.Event,
+    logger: Any,
+) -> bool:
+    """
+    Monitors for client disconnect during streaming.
+    Returns True if disconnected, False otherwise.
+    """
+    disconnect_detection_count = 0
+    while not completion_event.is_set():
+        try:
+            is_connected = await check_client_connection(req_id, http_request)
+            if not is_connected:
+                disconnect_detection_count += 1
+                if disconnect_detection_count >= 3:
+                    logger.info(
+                        f"[{req_id}] Client disconnect confirmed during streaming."
+                    )
+                    completion_event.set()
+                    return True
+            else:
+                disconnect_detection_count = 0
+            await asyncio.sleep(0.2)
+        except asyncio.CancelledError:
+            break
+        except Exception as e:
+            logger.error(f"[{req_id}] Error in enhanced_disconnect_monitor: {e}")
+            break
+    return False
+
+
+async def non_streaming_disconnect_monitor(
+    req_id: str,
+    http_request: Request,
+    result_future: asyncio.Future,
+    logger: Any,
+) -> bool:
+    """
+    Monitors for client disconnect during non-streaming processing.
+    Returns True if disconnected, False otherwise.
+    """
+    while not result_future.done():
+        try:
+            is_connected = await check_client_connection(req_id, http_request)
+            if not is_connected:
+                logger.info(
+                    f"[{req_id}] Client disconnect detected during non-streaming."
+                )
+                if not result_future.done():
+                    result_future.set_exception(
+                        HTTPException(status_code=499, detail="Client disconnected")
+                    )
+                return True
+            await asyncio.sleep(0.3)
+        except asyncio.CancelledError:
+            break
+        except Exception as e:
+            logger.error(f"[{req_id}] Error in non_streaming_disconnect_monitor: {e}")
+            break
+    return False
+
+
+async def setup_disconnect_monitoring(
+    req_id: str, http_request: Request, result_future
+) -> Tuple[Event, asyncio.Task, Callable]:
+    from api_utils.server_state import state
+
+    logger = state.logger
+
+    client_disconnected_event = Event()
+    disconnect_count = 0
+    disconnect_threshold = 5  # Require 5 consecutive disconnect signals (1.5 seconds)
+
+    async def check_disconnect_periodically():
+        nonlocal disconnect_count
+        while not client_disconnected_event.is_set():
+            try:
+                is_connected = await check_client_connection(req_id, http_request)
+                if not is_connected:
+                    disconnect_count += 1
+                    if disconnect_count >= disconnect_threshold:
+                        logger.info(
+                            f"[{req_id}] Active detection of client disconnect (consecutive {disconnect_count} times)."
+                        )
+                        client_disconnected_event.set()
+                        if not result_future.done():
+                            result_future.set_exception(
+                                HTTPException(
+                                    status_code=499,
+                                    detail=f"[{req_id}] Client closed the request",
+                                )
+                            )
+                        break
+                    else:
+                        logger.debug(
+                            f"[{req_id}] Active detection of potential disconnect (round {disconnect_count}/{disconnect_threshold})"
+                        )
+                else:
+                    disconnect_count = 0  # Reset counter on successful connection
+
+                await asyncio.sleep(0.3)
+            except asyncio.CancelledError:
+                # Task cancelled, exit gracefully
+                break
+            except Exception as e:
+                logger.error(f"(Disco Check Task) Error: {e}")
+                client_disconnected_event.set()
+                if not result_future.done():
+                    result_future.set_exception(
+                        HTTPException(
+                            status_code=500,
+                            detail=f"[{req_id}] Internal disconnect checker error: {e}",
+                        )
+                    )
+                break
+
+    disconnect_check_task = asyncio.create_task(check_disconnect_periodically())
+
+    def check_client_disconnected(stage: str = "") -> bool:
+        if client_disconnected_event.is_set():
+            logger.info(f"Client disconnected detected at stage: '{stage}'")
+            raise ClientDisconnectedError(
+                f"[{req_id}] Client disconnected at stage: {stage}"
+            )
+        return False
+
+    return client_disconnected_event, disconnect_check_task, check_client_disconnected

api_utils/common_utils.py

@@ -0,0 +1,6 @@
+import random
+
+
+def random_id(length: int = 24) -> str:
+    charset = "abcdefghijklmnopqrstuvwxyz0123456789"
+    return "".join(random.choice(charset) for _ in range(length))

api_utils/context_init.py

@@ -0,0 +1,38 @@
+from typing import cast
+
+from logging_utils import set_request_id
+from models import ChatCompletionRequest
+
+from .context_types import RequestContext
+
+
+async def initialize_request_context(
+    req_id: str, request: ChatCompletionRequest
+) -> RequestContext:
+    from api_utils.server_state import state
+
+    set_request_id(req_id)
+    state.logger.debug(
+        f"[Request] Parameters: Model={request.model}, Stream={request.stream}"
+    )
+
+    context: RequestContext = cast(
+        RequestContext,
+        {
+            "logger": state.logger,
+            "page": state.page_instance,
+            "is_page_ready": state.is_page_ready,
+            "parsed_model_list": state.parsed_model_list,
+            "current_ai_studio_model_id": state.current_ai_studio_model_id,
+            "model_switching_lock": state.model_switching_lock,
+            "page_params_cache": state.page_params_cache,
+            "params_cache_lock": state.params_cache_lock,
+            "is_streaming": request.stream,
+            "model_actually_switched": False,
+            "requested_model": request.model,
+            "model_id_to_use": None,
+            "needs_model_switching": False,
+        },
+    )
+
+    return context

api_utils/context_types.py

@@ -0,0 +1,54 @@
+import logging
+from asyncio import Future, Lock
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, TypedDict, Union
+
+from playwright.async_api import Page as AsyncPage
+
+if TYPE_CHECKING:
+    from fastapi import Request
+    from fastapi.responses import JSONResponse, StreamingResponse
+
+    from models.chat import ChatCompletionRequest
+
+
+class QueueItem(TypedDict):
+    """Type definition for items in the request queue.
+
+    This defines the structure of each item put into the request_queue,
+    ensuring type safety for queue operations.
+    """
+
+    req_id: str
+    request_data: "ChatCompletionRequest"
+    http_request: "Request"
+    result_future: "Future[Union[JSONResponse, StreamingResponse]]"
+    enqueue_time: float
+    cancelled: bool
+
+
+class RequestContext(TypedDict):
+    """Request context with all keys always present after initialization.
+
+    All keys are required (always exist in the dict) after context_init.py initialization.
+    Optional[] types indicate that the VALUE can be None, not that the key might not exist.
+    """
+
+    # Core components (always set by context_init.py)
+    req_id: str
+    logger: logging.Logger
+    page: Optional[AsyncPage]  # Value can be None if browser not ready
+    is_page_ready: bool
+    parsed_model_list: List[Dict[str, Any]]
+    current_ai_studio_model_id: Optional[str]  # Value can be None initially
+
+    # Locks (always set by server_state)
+    model_switching_lock: Lock
+    page_params_cache: Dict[str, Any]
+    params_cache_lock: Lock
+
+    # Request-specific state (always initialized)
+    is_streaming: bool
+    model_actually_switched: bool
+    requested_model: Optional[str]  # Value can be None if not specified
+    model_id_to_use: Optional[str]  # Value set during model analysis
+    needs_model_switching: bool

api_utils/dependencies.py

@@ -0,0 +1,169 @@
+"""
+FastAPI Dependencies Module
+"""
+
+import logging
+from asyncio import Event, Lock, Queue
+from typing import Any, Dict, List, Set
+
+from api_utils.context_types import QueueItem
+
+
+def get_logger() -> logging.Logger:
+    from api_utils.server_state import state
+
+    return state.logger
+
+
+def get_log_ws_manager():
+    from api_utils.server_state import state
+
+    return state.log_ws_manager
+
+
+def get_request_queue() -> "Queue[QueueItem]":
+    from typing import cast
+
+    from api_utils.server_state import state
+
+    return cast("Queue[QueueItem]", state.request_queue)
+
+
+def get_processing_lock() -> Lock:
+    from typing import cast
+
+    from api_utils.server_state import state
+
+    return cast(Lock, state.processing_lock)
+
+
+def get_worker_task():
+    from api_utils.server_state import state
+
+    return state.worker_task
+
+
+def get_server_state() -> Dict[str, Any]:
+    from api_utils.server_state import state
+
+    # Return immutable snapshot to prevent downstream modifications to global references
+    return dict(
+        is_initializing=state.is_initializing,
+        is_playwright_ready=state.is_playwright_ready,
+        is_browser_connected=state.is_browser_connected,
+        is_page_ready=state.is_page_ready,
+    )
+
+
+def get_page_instance():
+    from api_utils.server_state import state
+
+    return state.page_instance
+
+
+def get_model_list_fetch_event() -> Event:
+    from typing import cast
+
+    from api_utils.server_state import state
+
+    return cast(Event, state.model_list_fetch_event)
+
+
+def get_parsed_model_list() -> List[Dict[str, Any]]:
+    from api_utils.server_state import state
+
+    return state.parsed_model_list
+
+
+def get_excluded_model_ids() -> Set[str]:
+    from api_utils.server_state import state
+
+    return state.excluded_model_ids
+
+
+def get_current_ai_studio_model_id() -> str:
+    from typing import cast
+
+    from api_utils.server_state import state
+
+    return cast(str, state.current_ai_studio_model_id)
+
+
+async def ensure_request_lock():
+    """
+    Dependency that acts as a 'Parking Lot' for requests.
+    If Auth Rotation is in progress (Lock is cleared) or Quota is Exceeded (Rotation imminent),
+    this will pause the request until the system is ready.
+    """
+    import asyncio
+    import time
+
+    from api_utils.server_state import state as server_state
+    from config.global_state import GlobalState
+
+    logger = server_state.logger
+
+    # A request is considered "queued" if it has to wait for the lock.
+    is_waiting = (
+        GlobalState.IS_QUOTA_EXCEEDED or not GlobalState.AUTH_ROTATION_LOCK.is_set()
+    )
+    if is_waiting:
+        GlobalState.queued_request_count += 1
+
+    start_time = time.time()
+    max_total_wait = 60.0  # 60 second hard timeout for request parking
+
+    try:
+        # Wait loop to handle both Lock and Quota states
+        # We wait if:
+        # 1. Lock is NOT set (Rotation in progress)
+        # 2. Quota IS exceeded (Rotation about to start, or we need to wait for it)
+        while (
+            GlobalState.IS_QUOTA_EXCEEDED or not GlobalState.AUTH_ROTATION_LOCK.is_set()
+        ):
+            # Check for total timeout
+            if time.time() - start_time > max_total_wait:
+                logger.error(
+                    f"🚨 Request parking timeout after {max_total_wait}s. Quota={GlobalState.IS_QUOTA_EXCEEDED}, LockSet={GlobalState.AUTH_ROTATION_LOCK.is_set()}"
+                )
+                from fastapi import HTTPException
+
+                raise HTTPException(
+                    status_code=530,  # Custom code for state resolution timeout
+                    detail="System state resolution timeout - please try again later",
+                )
+
+            if not GlobalState.AUTH_ROTATION_LOCK.is_set():
+                # Rotation in progress. Wait for lock to open with timeout.
+                try:
+                    await asyncio.wait_for(
+                        GlobalState.AUTH_ROTATION_LOCK.wait(), timeout=30.0
+                    )
+                except asyncio.TimeoutError:
+                    logger.warning(
+                        "🚨 Lock wait timeout after 30s. Service may be unavailable."
+                    )
+                    from fastapi import HTTPException
+
+                    raise HTTPException(
+                        status_code=503,
+                        detail="Service temporarily unavailable - timeout waiting for system lock",
+                    )
+            else:
+                # Lock is Open, but Quota is still marked Exceeded.
+                # This implies the Watchdog is about to rotate, or we are in a race.
+                # We wait for the recovery event which signals rotation completion.
+                try:
+                    if GlobalState.IS_RECOVERING:
+                        # If recovery is active, wait for it to finish
+                        await asyncio.wait_for(
+                            GlobalState.RECOVERY_EVENT.wait(), timeout=30.0
+                        )
+                    else:
+                        # Watchdog hasn't started yet, wait briefly
+                        await asyncio.sleep(0.1)
+                except asyncio.TimeoutError:
+                    await asyncio.sleep(0.1)
+    finally:
+        if is_waiting:
+            GlobalState.queued_request_count -= 1

api_utils/error_utils.py

@@ -0,0 +1,47 @@
+from typing import Dict, Optional
+
+from fastapi import HTTPException
+
+
+def http_error(
+    status_code: int, detail: str, headers: Optional[Dict[str, str]] = None
+) -> HTTPException:
+    return HTTPException(
+        status_code=status_code, detail=detail, headers=headers or None
+    )
+
+
+def client_cancelled(req_id: str, message: str = "Request cancelled.") -> HTTPException:
+    return http_error(499, f"[{req_id}] {message}")
+
+
+def client_disconnected(req_id: str, stage: str = "") -> HTTPException:
+    suffix = f" during {stage}" if stage else ""
+    return http_error(499, f"[{req_id}] Client disconnected{suffix}.")
+
+
+def processing_timeout(
+    req_id: str, message: str = "Processing timed out."
+) -> HTTPException:
+    return http_error(504, f"[{req_id}] {message}")
+
+
+def bad_request(req_id: str, message: str) -> HTTPException:
+    return http_error(400, f"[{req_id}] {message}")
+
+
+def server_error(req_id: str, message: str) -> HTTPException:
+    return http_error(500, f"[{req_id}] {message}")
+
+
+def upstream_error(req_id: str, message: str) -> HTTPException:
+    # 502 Bad Gateway for upstream/playwright failures
+    return http_error(502, f"[{req_id}] {message}")
+
+
+def service_unavailable(req_id: str, retry_after_seconds: int = 30) -> HTTPException:
+    return http_error(
+        503,
+        f"[{req_id}] Service currently unavailable. Please try again later.",
+        headers={"Retry-After": str(retry_after_seconds)},
+    )

api_utils/mcp_adapter.py

@@ -0,0 +1,57 @@
+import asyncio
+import json
+import os
+from typing import Any, Dict
+
+import httpx
+
+
+def _normalize_endpoint(ep: str) -> str:
+    if not ep:
+        raise RuntimeError("MCP HTTP endpoint not provided")
+    return ep.rstrip("/")
+
+
+async def execute_mcp_tool(name: str, params: Dict[str, Any]) -> str:
+    """
+    Minimal MCP-over-HTTP adapter:
+    - POST {MCP_HTTP_ENDPOINT}/tools/execute with {name, arguments}
+    - Returns JSON string.
+    Compatible with servers exposing MCP-like HTTP interface.
+    """
+    ep = os.environ.get("MCP_HTTP_ENDPOINT")
+    if not ep:
+        raise RuntimeError("MCP_HTTP_ENDPOINT not configured")
+    url = f"{_normalize_endpoint(ep)}/tools/execute"
+    payload = {"name": name, "arguments": params}
+    headers = {"Content-Type": "application/json"}
+    timeout = float(os.environ.get("MCP_HTTP_TIMEOUT", "15"))
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        resp = await client.post(url, json=payload, headers=headers)
+        resp.raise_for_status()
+        try:
+            data = resp.json()
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            data = {"raw": resp.text}
+    return json.dumps(data, ensure_ascii=False)
+
+
+async def execute_mcp_tool_with_endpoint(
+    endpoint: str, name: str, params: Dict[str, Any]
+) -> str:
+    url = f"{_normalize_endpoint(endpoint)}/tools/execute"
+    payload = {"name": name, "arguments": params}
+    headers = {"Content-Type": "application/json"}
+    timeout = float(os.environ.get("MCP_HTTP_TIMEOUT", "15"))
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        resp = await client.post(url, json=payload, headers=headers)
+        resp.raise_for_status()
+        try:
+            data = resp.json()
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            data = {"raw": resp.text}
+    return json.dumps(data, ensure_ascii=False)

api_utils/model_switching.py

@@ -0,0 +1,121 @@
+
+from playwright.async_api import Page as AsyncPage
+
+from api_utils.server_state import state
+from logging_utils import set_request_id
+
+from .context_types import RequestContext
+
+
+async def analyze_model_requirements(
+    req_id: str, context: RequestContext, requested_model: str, proxy_model_name: str
+) -> RequestContext:
+    set_request_id(req_id)
+    logger = context["logger"]
+    current_ai_studio_model_id = context["current_ai_studio_model_id"]
+    parsed_model_list = context["parsed_model_list"]
+
+    if requested_model and requested_model != proxy_model_name:
+        requested_model_id = requested_model.split("/")[-1]
+        logger.info(f"[{req_id}] Requesting model: {requested_model_id}")
+
+        if parsed_model_list:
+            valid_model_ids = [
+                str(m.get("id")) for m in parsed_model_list if m.get("id")
+            ]
+            if requested_model_id not in valid_model_ids:
+                from .error_utils import bad_request
+
+                raise bad_request(
+                    req_id,
+                    f"Invalid model '{requested_model_id}'. Available models: {', '.join(valid_model_ids)}",
+                )
+
+        context["model_id_to_use"] = requested_model_id
+        if current_ai_studio_model_id != requested_model_id:
+            context["needs_model_switching"] = True
+            logger.info(
+                f"[{req_id}] Model switch needed: Current={current_ai_studio_model_id} -> Target={requested_model_id}"
+            )
+
+    return context
+
+
+async def handle_model_switching(
+    req_id: str, context: RequestContext
+) -> RequestContext:
+    set_request_id(req_id)
+    if not context["needs_model_switching"]:
+        return context
+
+    logger = context["logger"]
+    page = context["page"]
+    model_switching_lock = context["model_switching_lock"]
+    model_id_to_use = context["model_id_to_use"]
+
+    # Assert non-None values required for model switching
+    assert page is not None, "Page must be ready for model switching"
+    assert model_id_to_use is not None, "Target model ID must be set"
+
+    async with model_switching_lock:
+        if state.current_ai_studio_model_id != model_id_to_use:
+            logger.info(
+                f"[{req_id}] Preparing to switch model: {state.current_ai_studio_model_id} -> {model_id_to_use}"
+            )
+            from browser_utils import switch_ai_studio_model
+
+            switch_success = await switch_ai_studio_model(page, model_id_to_use, req_id)
+            if switch_success:
+                state.current_ai_studio_model_id = model_id_to_use
+                context["model_actually_switched"] = True
+                context["current_ai_studio_model_id"] = model_id_to_use
+                logger.info(
+                    f"[{req_id}] ✅ Model switched successfully: {state.current_ai_studio_model_id}"
+                )
+            else:
+                # Current model ID should exist when switching fails
+                current_model = state.current_ai_studio_model_id or "unknown"
+                await _handle_model_switch_failure(
+                    req_id,
+                    page,
+                    model_id_to_use,
+                    current_model,
+                    logger,
+                )
+
+    return context
+
+
+async def _handle_model_switch_failure(
+    req_id: str, page: AsyncPage, model_id_to_use: str, model_before_switch: str, logger
+) -> None:
+    logger.warning(f"[{req_id}] ❌ Failed to switch to model {model_id_to_use}.")
+    state.current_ai_studio_model_id = model_before_switch
+    from .error_utils import http_error
+
+    raise http_error(
+        422,
+        f"[{req_id}] Failed to switch to model '{model_id_to_use}'. Ensure model is available.",
+    )
+
+
+async def handle_parameter_cache(req_id: str, context: RequestContext) -> None:
+    set_request_id(req_id)
+    logger = context["logger"]
+    params_cache_lock = context["params_cache_lock"]
+    page_params_cache = context["page_params_cache"]
+    current_ai_studio_model_id = context["current_ai_studio_model_id"]
+    model_actually_switched = context["model_actually_switched"]
+
+    async with params_cache_lock:
+        cached_model_for_params = page_params_cache.get(
+            "last_known_model_id_for_params"
+        )
+        if model_actually_switched or (
+            current_ai_studio_model_id != cached_model_for_params
+        ):
+            logger.info(f"[{req_id}] Model changed, parameter cache invalidated.")
+            page_params_cache.clear()
+            page_params_cache["last_known_model_id_for_params"] = (
+                current_ai_studio_model_id
+            )

api_utils/page_response.py

@@ -0,0 +1,39 @@
+import asyncio
+import logging
+from typing import Callable
+
+from playwright.async_api import Error as PlaywrightAsyncError
+from playwright.async_api import Page as AsyncPage
+from playwright.async_api import expect as expect_async
+
+from config import RESPONSE_CONTAINER_SELECTOR, RESPONSE_TEXT_SELECTOR
+
+
+async def locate_response_elements(
+    page: AsyncPage,
+    req_id: str,
+    logger: logging.Logger,
+    check_client_disconnected: Callable[[str], bool],
+) -> None:
+    """Locate response container and text elements, including timeout and error handling."""
+    logger.info(f"[{req_id}] Locating response elements...")
+    response_container = page.locator(RESPONSE_CONTAINER_SELECTOR).last
+    response_element = response_container.locator(RESPONSE_TEXT_SELECTOR)
+
+    try:
+        await expect_async(response_container).to_be_attached(timeout=20000)
+        check_client_disconnected("After Response Container Attached: ")
+        await expect_async(response_element).to_be_attached(timeout=90000)
+        logger.info(f"[{req_id}] Response elements located.")
+    except (PlaywrightAsyncError, asyncio.TimeoutError) as locate_err:
+        from .error_utils import upstream_error
+
+        raise upstream_error(
+            req_id, f"Failed to locate AI Studio response elements: {locate_err}"
+        )
+    except Exception as locate_exc:
+        from .error_utils import server_error
+
+        raise server_error(
+            req_id, f"Unexpected error while locating response elements: {locate_exc}"
+        )

api_utils/queue_worker.py

@@ -0,0 +1,467 @@
+"""
+Queue Worker Module
+Handles tasks in the request queue
+"""
+
+import asyncio
+import time
+from asyncio import Event, Future, Task
+from typing import Callable, Optional, cast
+
+from fastapi import HTTPException, Request
+from playwright.async_api import Locator
+from playwright.async_api import expect as expect_async
+
+from api_utils.context_types import QueueItem
+from models import QuotaExceededError
+
+from .client_connection import check_client_connection
+
+
+async def queue_worker() -> None:
+    """Queue worker, processes tasks in the request queue"""
+    # Delayed imports to avoid circularity
+    from api_utils.server_state import state
+    from config import RESPONSE_COMPLETION_TIMEOUT
+
+    logger = state.logger
+    request_queue = state.request_queue
+    processing_lock = state.processing_lock
+    model_switching_lock = state.model_switching_lock
+    params_cache_lock = state.params_cache_lock
+    from browser_utils.auth_rotation import perform_auth_rotation
+    from browser_utils.page_controller import PageController
+    from config.global_state import GlobalState
+
+    from .error_utils import (
+        client_cancelled,
+        client_disconnected,
+        server_error,
+    )
+
+    # Internal imports for queue worker logic
+    from .request_processor import (
+        ClientDisconnectedError,
+        _process_request_refactored,
+        _test_client_connection,
+        save_error_snapshot,
+    )
+    from .utils_ext.stream import clear_stream_queue
+
+    logger.info("--- Queue Worker Started ---")
+
+    # Validate that required globals are initialized
+    if request_queue is None:
+        logger.critical("FATAL: request_queue is None! Initialization failed.")
+        raise RuntimeError("request_queue not initialized")
+
+    if processing_lock is None:
+        logger.critical("FATAL: processing_lock is None! Initialization failed.")
+        raise RuntimeError("processing_lock not initialized")
+
+    if model_switching_lock is None:
+        logger.critical("FATAL: model_switching_lock is None! Initialization failed.")
+        raise RuntimeError("model_switching_lock not initialized")
+
+    if params_cache_lock is None:
+        logger.critical("FATAL: params_cache_lock is None! Initialization failed.")
+        raise RuntimeError("params_cache_lock not initialized")
+
+    logger.debug(
+        f"Queue worker initialized with queue={request_queue}, lock={processing_lock}"
+    )
+
+    was_last_request_streaming = False
+    last_request_completion_time = 0.0
+    shutdown_check_interval = 0.1
+
+    while True:
+        request_item: Optional[QueueItem] = None
+        result_future: Optional[Future] = None
+        http_request: Optional[Request] = None
+        req_id: str = "UNKNOWN"
+        completion_event: Optional[Event] = None
+        submit_btn_loc: Optional[Locator] = None
+        client_disco_checker: Optional[Callable[[str], bool]] = None
+        disconnect_monitor_task: Optional[Task] = None
+        client_disconnected_early: bool = False
+
+        try:
+            # [SHUTDOWN] Check shutdown signal
+            if GlobalState.IS_SHUTTING_DOWN.is_set():
+                logger.info("🚨 Queue Worker detected shutdown signal, exiting.")
+                break
+
+            # Clean up disconnected requests in queue
+            queue_size = request_queue.qsize()
+            if queue_size > 0:
+                checked_count = 0
+                items_to_requeue = []
+                processed_ids = set()
+
+                while checked_count < queue_size and checked_count < 10:
+                    if GlobalState.IS_SHUTTING_DOWN.is_set():
+                        break
+                    try:
+                        item = request_queue.get_nowait()
+                        item_req_id = item.get("req_id", "unknown")
+                        if item_req_id in processed_ids:
+                            items_to_requeue.append(item)
+                            continue
+                        processed_ids.add(item_req_id)
+
+                        if not item.get("cancelled", False):
+                            item_http_req = item.get("http_request")
+                            if item_http_req:
+                                try:
+                                    if not await check_client_connection(
+                                        item_req_id, item_http_req
+                                    ):
+                                        logger.info(
+                                            f"[{item_req_id}] (Worker Queue Check) Client disconnect detected."
+                                        )
+                                        item["cancelled"] = True
+                                        item_fut = item.get("result_future")
+                                        if item_fut and not item_fut.done():
+                                            item_fut.set_exception(
+                                                client_disconnected(
+                                                    item_req_id,
+                                                    "Client disconnected while queued.",
+                                                )
+                                            )
+                                except Exception as e:
+                                    logger.error(
+                                        f"[{item_req_id}] (Worker Queue Check) Error: {e}"
+                                    )
+
+                        items_to_requeue.append(item)
+                        checked_count += 1
+                    except asyncio.QueueEmpty:
+                        break
+
+                for item in items_to_requeue:
+                    await request_queue.put(item)
+
+            # [AUTH-ROTATION] Handle quota or rotation needs
+            if GlobalState.IS_QUOTA_EXCEEDED or GlobalState.NEEDS_ROTATION:
+                reason = (
+                    "Quota Exceeded"
+                    if GlobalState.IS_QUOTA_EXCEEDED
+                    else "Graceful Rotation Pending"
+                )
+                logger.info(f"⏸️ Pausing worker for Auth Rotation ({reason})...")
+                GlobalState.start_recovery()
+                try:
+                    current_model_id = state.current_ai_studio_model_id
+                    rotation_success = await perform_auth_rotation(
+                        target_model_id=current_model_id or ""
+                    )
+                    if rotation_success:
+                        GlobalState.NEEDS_ROTATION = False
+                        logger.info("✅ Auth rotation completed successfully.")
+                    else:
+                        logger.error("❌ Auth rotation failed.")
+                        await asyncio.sleep(1)
+                finally:
+                    GlobalState.finish_recovery()
+                if not rotation_success:
+                    continue
+
+            if GlobalState.IS_SHUTTING_DOWN.is_set():
+                break
+
+            # Get next request
+            try:
+                current_timeout = (
+                    shutdown_check_interval
+                    if GlobalState.IS_SHUTTING_DOWN.is_set()
+                    else 5.0
+                )
+                request_item = await asyncio.wait_for(
+                    request_queue.get(), timeout=current_timeout
+                )
+            except asyncio.TimeoutError:
+                continue
+
+            if request_item is None:
+                continue
+
+            req_id = request_item["req_id"]
+            request_data = request_item["request_data"]
+            http_request = request_item["http_request"]
+            result_future = request_item["result_future"]
+
+            GlobalState.CURRENT_STREAM_REQ_ID = req_id
+            logger.info(f"[{req_id}] (Worker) Processing request dequeued.")
+
+            if GlobalState.IS_QUOTA_EXCEEDED:
+                logger.warning(f"[{req_id}] (Worker) ⛔ Quota exceeded, re-queueing.")
+                await request_queue.put(request_item)
+                request_queue.task_done()
+                continue
+
+            if request_item.get("cancelled", False):
+                if result_future and not result_future.done():
+                    result_future.set_exception(
+                        client_cancelled(req_id, "Request cancelled by user")
+                    )
+                request_queue.task_done()
+                continue
+
+            is_streaming_request = request_data.stream
+
+            # Initial connection check
+            if not await _test_client_connection(req_id, http_request):
+                if result_future and not result_future.done():
+                    result_future.set_exception(
+                        HTTPException(status_code=499, detail="Client disconnected")
+                    )
+                request_queue.task_done()
+                continue
+
+            # Streaming delay
+            current_time = time.time()
+            if (
+                was_last_request_streaming
+                and is_streaming_request
+                and (current_time - last_request_completion_time < 1.0)
+            ):
+                await asyncio.sleep(
+                    max(0.5, 1.0 - (current_time - last_request_completion_time))
+                )
+
+            # Wait for lock
+            async with processing_lock:
+                logger.info(f"[{req_id}] (Worker) Lock acquired.")
+
+                if not await _test_client_connection(req_id, http_request):
+                    if result_future and not result_future.done():
+                        result_future.set_exception(
+                            HTTPException(status_code=499, detail="Client disconnected")
+                        )
+                elif result_future and result_future.done():
+                    logger.info(f"[{req_id}] (Worker) Future already done.")
+                else:
+                    try:
+                        returned_value = await _process_request_refactored(
+                            req_id, request_data, http_request, result_future
+                        )
+
+                        if (
+                            isinstance(returned_value, tuple)
+                            and len(returned_value) == 3
+                        ):
+                            completion_event, submit_btn_loc, client_disco_checker = (
+                                returned_value
+                            )
+
+                        if completion_event:
+                            if isinstance(completion_event, dict):
+                                if (
+                                    completion_event.get("done")
+                                    and is_streaming_request
+                                ):
+                                    if state.STREAM_QUEUE:
+                                        await state.STREAM_QUEUE.put(completion_event)
+                                if result_future and not result_future.done():
+                                    result_future.set_result(completion_event)
+                                client_disconnected_early = False
+                            elif hasattr(completion_event, "wait"):
+                                client_disconnected_early = False
+                                comp_ev = cast(Event, completion_event)
+
+                                async def enhanced_disconnect_monitor_fn():
+                                    nonlocal client_disconnected_early
+                                    disco_count = 0
+                                    while not comp_ev.is_set():
+                                        if GlobalState.IS_SHUTTING_DOWN.is_set():
+                                            comp_ev.set()
+                                            break
+                                        if (
+                                            GlobalState.IS_QUOTA_EXCEEDED
+                                            and not GlobalState.IS_RECOVERING
+                                        ):
+                                            # Abort if quota exceeded and not recovering
+                                            client_disconnected_early = True
+                                            comp_ev.set()
+                                            break
+
+                                        if not await _test_client_connection(
+                                            req_id, http_request
+                                        ):
+                                            disco_count += 1
+                                            if disco_count >= 3:
+                                                client_disconnected_early = True
+                                                comp_ev.set()
+                                                break
+                                        else:
+                                            disco_count = 0
+                                        await asyncio.sleep(0.2)
+
+                                disconnect_monitor_task = asyncio.create_task(
+                                    enhanced_disconnect_monitor_fn()
+                                )
+                                await asyncio.wait_for(
+                                    comp_ev.wait(),
+                                    timeout=RESPONSE_COMPLETION_TIMEOUT / 1000 + 60,
+                                )
+                        else:
+                            # Non-streaming
+                            client_disconnected_early = False
+                            res_fut = cast(Future, result_future)
+
+                            async def non_streaming_monitor_fn():
+                                nonlocal client_disconnected_early
+                                while not res_fut.done():
+                                    if GlobalState.IS_SHUTTING_DOWN.is_set():
+                                        res_fut.cancel()
+                                        break
+                                    if not await _test_client_connection(
+                                        req_id, http_request
+                                    ):
+                                        client_disconnected_early = True
+                                        res_fut.set_exception(
+                                            HTTPException(
+                                                status_code=499,
+                                                detail="Client disconnected",
+                                            )
+                                        )
+                                        break
+                                    await asyncio.sleep(0.3)
+
+                            disconnect_monitor_task = asyncio.create_task(
+                                non_streaming_monitor_fn()
+                            )
+                            await asyncio.wait_for(
+                                asyncio.shield(res_fut),
+                                timeout=RESPONSE_COMPLETION_TIMEOUT / 1000 + 60,
+                            )
+
+                        # Post-processing button handling
+                        if client_disconnected_early:
+                            if submit_btn_loc:
+                                try:
+                                    if await submit_btn_loc.is_enabled(timeout=2000):
+                                        await submit_btn_loc.click(
+                                            timeout=5000, force=True
+                                        )
+                                except Exception:
+                                    pass
+                        elif (
+                            submit_btn_loc and client_disco_checker and completion_event
+                        ):
+                            try:
+                                client_disco_checker("Post-stream check")
+                                await asyncio.sleep(0.5)
+                                client_disco_checker("Post-sleep check")
+                                if await submit_btn_loc.is_enabled(timeout=2000):
+                                    await submit_btn_loc.click(timeout=5000, force=True)
+                                await expect_async(submit_btn_loc).to_be_disabled(
+                                    timeout=10000
+                                )
+                            except ClientDisconnectedError:
+                                pass
+                            except Exception:
+                                await save_error_snapshot(f"button_timeout_{req_id}")
+
+                    except QuotaExceededError:
+                        raise
+                    except Exception as e:
+                        logger.error(f"[{req_id}] (Worker) Error: {e}")
+                        if result_future and not result_future.done():
+                            result_future.set_exception(
+                                server_error(req_id, f"Error: {e}")
+                            )
+                    finally:
+                        if (
+                            disconnect_monitor_task
+                            and not disconnect_monitor_task.done()
+                        ):
+                            disconnect_monitor_task.cancel()
+                            try:
+                                await disconnect_monitor_task
+                            except asyncio.CancelledError:
+                                pass
+
+            # [ROTATION] Post-request rotation check
+            just_rotated = False
+            if GlobalState.NEEDS_ROTATION:
+                current_model_id_rot = state.current_ai_studio_model_id
+                if await perform_auth_rotation(
+                    target_model_id=current_model_id_rot or ""
+                ):
+                    GlobalState.NEEDS_ROTATION = False
+                    just_rotated = True
+
+            # [CLEANUP]
+            try:
+                await clear_stream_queue()
+
+                # [COOKIE-REFRESH] Save cookies after successful requests
+                if not client_disconnected_early and not GlobalState.IS_QUOTA_EXCEEDED:
+                    try:
+                        from browser_utils.cookie_refresh import (
+                            maybe_refresh_on_request,
+                        )
+
+                        await maybe_refresh_on_request()
+                    except Exception as cookie_err:
+                        logger.debug(
+                            f"[{req_id}] Cookie refresh error (non-critical): {cookie_err}"
+                        )
+
+                if (
+                    not GlobalState.IS_QUOTA_EXCEEDED
+                    and not just_rotated
+                    and not GlobalState.IS_SHUTTING_DOWN.is_set()
+                ):
+                    if submit_btn_loc and client_disco_checker:
+                        s_page = state.page_instance
+                        s_ready = state.is_page_ready
+                        s_browser = state.browser_instance
+
+                        if (
+                            s_page
+                            and s_ready
+                            and s_browser
+                            and s_browser.is_connected()
+                        ):
+                            try:
+                                controller = PageController(s_page, logger, req_id)
+                                await controller.clear_chat_history(lambda stage: False)
+                            except Exception:
+                                try:
+                                    await s_page.reload()
+                                except Exception:
+                                    pass
+            except Exception as e:
+                logger.error(f"[{req_id}] Cleanup error: {e}")
+
+            was_last_request_streaming = is_streaming_request
+            last_request_completion_time = time.time()
+
+        except asyncio.CancelledError:
+            if result_future and not result_future.done():
+                result_future.cancel()
+            break
+        except QuotaExceededError:
+            try:
+                if await _test_client_connection(req_id, http_request):
+                    request_queue.put_nowait(request_item)
+                elif result_future and not result_future.done():
+                    result_future.set_exception(
+                        HTTPException(
+                            status_code=499, detail="Disconnected during quota error"
+                        )
+                    )
+            except Exception:
+                pass
+        except Exception as e:
+            logger.error(f"[{req_id}] Unexpected error: {e}", exc_info=True)
+            if result_future and not result_future.done():
+                result_future.set_exception(server_error(req_id, f"Error: {e}"))
+        finally:
+            if request_item:
+                request_queue.task_done()
+
+    logger.info("--- Queue Worker Stopped ---")

api_utils/request_processor.py

@@ -0,0 +1,975 @@
+"""
+Request Processor Module
+Contains core request processing logic
+"""
+
+import asyncio
+import json
+import os
+import shutil
+from asyncio import Event, Future
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+from fastapi import HTTPException, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+from playwright.async_api import (
+    Error as PlaywrightAsyncError,
+)
+from playwright.async_api import (
+    Locator,
+)
+from playwright.async_api import (
+    Page as AsyncPage,
+)
+
+# --- browser_utils Module Imports ---
+from browser_utils import (
+    save_error_snapshot,
+)
+from browser_utils.page_controller import PageController
+
+# --- Configuration Module Imports ---
+from config import (
+    MODEL_NAME,
+    RESPONSE_COMPLETION_TIMEOUT,
+    SUBMIT_BUTTON_SELECTOR,
+    UPLOAD_FILES_DIR,
+    get_environment_variable,
+)
+from config.global_state import GlobalState
+
+# --- logging_utils Module Imports ---
+from logging_utils import log_context
+
+# --- models Module Imports ---
+from models import (
+    ChatCompletionRequest,
+    ClientDisconnectedError,
+    QuotaExceededError,
+    QuotaExceededRetry,
+)
+
+from .client_connection import (
+    check_client_connection as _check_client_connection,
+)
+from .client_connection import (
+    setup_disconnect_monitoring as _setup_disconnect_monitoring,
+)
+from .common_utils import random_id as _random_id
+from .context_init import initialize_request_context as _init_request_context
+from .context_types import RequestContext
+from .error_utils import (
+    bad_request,
+    client_disconnected,
+    server_error,
+    upstream_error,
+)
+from .model_switching import (
+    analyze_model_requirements as ms_analyze,
+)
+from .model_switching import (
+    handle_model_switching as ms_switch,
+)
+from .model_switching import (
+    handle_parameter_cache as ms_param_cache,
+)
+from .page_response import locate_response_elements
+from .response_generators import (
+    gen_sse_from_aux_stream,
+    gen_sse_from_playwright,
+    resilient_stream_generator,
+)
+from .response_payloads import build_chat_completion_response_json
+
+# --- api_utils Module Imports ---
+from .utils import (
+    maybe_execute_tools,
+    prepare_combined_prompt,
+)
+from .utils_ext.files import collect_and_validate_attachments
+from .utils_ext.function_calling_orchestrator import (
+    FunctionCallingState,
+    get_function_calling_orchestrator,
+)
+from .utils_ext.stream import use_stream_response
+from .utils_ext.tokens import calculate_usage_stats
+from .utils_ext.usage_tracker import increment_profile_usage
+from .utils_ext.validation import validate_chat_request
+
+_initialize_request_context = _init_request_context
+
+
+# Wrapper function for backward compatibility
+async def _test_client_connection(req_id: str, http_request) -> bool:
+    """Test if client is still connected - wrapper for _check_client_connection"""
+    return await _check_client_connection(req_id, http_request)
+
+
+async def _analyze_model_requirements(
+    req_id: str, context: RequestContext, request: ChatCompletionRequest
+) -> RequestContext:
+    """Proxy to model_switching.analyze_model_requirements"""
+    return await ms_analyze(req_id, context, request.model, MODEL_NAME)
+
+
+async def _validate_page_status(
+    req_id: str, context: RequestContext, check_client_disconnected: Callable
+) -> None:
+    """Validate page status"""
+    page = context["page"]
+    is_page_ready = context["is_page_ready"]
+
+    if not page or page.is_closed() or not is_page_ready:
+        raise HTTPException(
+            status_code=503,
+            detail=f"[{req_id}] AI Studio page lost or not ready.",
+            headers={"Retry-After": "30"},
+        )
+
+    check_client_disconnected("Initial Page Check")
+
+
+async def _handle_model_switching(
+    req_id: str, context: RequestContext, check_client_disconnected: Callable
+) -> RequestContext:
+    """Proxy to model_switching.handle_model_switching"""
+    return await ms_switch(req_id, context)
+
+
+async def _handle_model_switch_failure(
+    req_id: str, page: AsyncPage, model_id_to_use: str, model_before_switch: str, logger
+) -> None:
+    """Handle model switch failure"""
+    from api_utils.server_state import state
+
+    logger.warning(f"[{req_id}] Failed to switch model to {model_id_to_use}.")
+    # Attempt to restore global state
+    state.current_ai_studio_model_id = model_before_switch
+
+    raise HTTPException(
+        status_code=422,
+        detail=f"[{req_id}] Failed to switch to model '{model_id_to_use}'. Ensure model is available.",
+    )
+
+
+async def _handle_parameter_cache(req_id: str, context: RequestContext) -> None:
+    """Proxy to model_switching.handle_parameter_cache"""
+    await ms_param_cache(req_id, context)
+
+
+async def _prepare_and_validate_request(
+    req_id: str,
+    request: ChatCompletionRequest,
+    check_client_disconnected: Callable,
+    fc_state: Optional[FunctionCallingState] = None,
+) -> Tuple[str, List[str], Optional[List[Dict[str, Any]]]]:
+    """Prepare and validate request, return (combined prompt, attachment path list, tool_exec_results)."""
+    try:
+        validate_chat_request(request.messages, req_id)
+    except ValueError as e:
+        raise bad_request(req_id, f"Invalid request: {e}")
+
+    prepared_prompt, attachments_list = prepare_combined_prompt(
+        request.messages,
+        req_id,
+        getattr(request, "tools", None),
+        getattr(request, "tool_choice", None),
+        fc_state=fc_state,
+    )
+    # Active function execution based on tools/tool_choice (supports per-request MCP endpoints)
+    try:
+        # Inject mcp_endpoint into utils.maybe_execute_tools registration logic
+        if hasattr(request, "mcp_endpoint") and request.mcp_endpoint:
+            from .tools_registry import register_runtime_tools
+
+            register_runtime_tools(
+                getattr(request, "tools", None), request.mcp_endpoint
+            )
+        tool_exec_results = await maybe_execute_tools(
+            request.messages, request.tools, getattr(request, "tool_choice", None)
+        )
+    except asyncio.CancelledError:
+        raise
+    except Exception:
+        tool_exec_results = None
+
+    check_client_disconnected("After Prompt Prep")
+    # Inline results at the end of the prompt for submission together
+    if tool_exec_results:
+        try:
+            for res in tool_exec_results:
+                name = res.get("name")
+                args = res.get("arguments")
+                result_str = res.get("result")
+                prepared_prompt += f"\n---\nTool Execution: {name}\nArguments:\n{args}\nResult:\n{result_str}\n"
+        except Exception:
+            pass
+
+    # Process and validate attachments
+    # Acceptance criteria: Only accept data:/file:/absolute paths provided by current request
+    final_attachments = collect_and_validate_attachments(
+        request, req_id, attachments_list
+    )
+
+    return prepared_prompt, final_attachments, tool_exec_results
+
+
+async def _handle_response_processing(
+    req_id: str,
+    request: ChatCompletionRequest,
+    page: Optional[AsyncPage],
+    context: RequestContext,
+    result_future: Future,
+    submit_button_locator: Locator,
+    check_client_disconnected: Callable,
+    prompt_length: int,
+    timeout: float,
+    silence_threshold: float = 60.0,
+) -> Optional[Tuple[Event, Locator, Callable]]:
+    """Handle response generation"""
+    stream_port = get_environment_variable("STREAM_PORT")
+    use_stream = stream_port != "0"
+
+    if use_stream:
+        return await _handle_auxiliary_stream_response(
+            req_id,
+            request,
+            context,
+            result_future,
+            submit_button_locator,
+            check_client_disconnected,
+            timeout=timeout,
+            silence_threshold=silence_threshold,
+        )
+    else:
+        return await _handle_playwright_response(
+            req_id,
+            request,
+            page,
+            context,
+            result_future,
+            submit_button_locator,
+            check_client_disconnected,
+            prompt_length,
+            timeout=timeout,
+        )
+
+
+async def _handle_auxiliary_stream_response(
+    req_id: str,
+    request: ChatCompletionRequest,
+    context: RequestContext,
+    result_future: Future[Union[StreamingResponse, JSONResponse]],
+    submit_button_locator: Locator,
+    check_client_disconnected: Callable,
+    timeout: float,
+    silence_threshold: float = 60.0,
+) -> Optional[Tuple[Event, Locator, Callable]]:
+    """Auxiliary stream response processing path"""
+    from api_utils.server_state import state
+
+    logger = state.logger
+
+    is_streaming = request.stream
+    current_ai_studio_model_id = context.get("current_ai_studio_model_id")
+
+    if is_streaming:
+        try:
+            completion_event = Event()
+            page = context["page"]
+
+            # [RESILIENT-WRAPPER] Wrap the stream generator with retry/rotation logic
+            def aux_stream_factory(event_to_signal: Event):
+                return gen_sse_from_aux_stream(
+                    req_id,
+                    request,
+                    current_ai_studio_model_id or MODEL_NAME,
+                    check_client_disconnected,
+                    event_to_signal,
+                    timeout=timeout,
+                    silence_threshold=silence_threshold,
+                    page=page,  # <--- CRITICAL: This enables the auto-scroll logic in stream.py
+                )
+
+            resilient_gen = resilient_stream_generator(
+                req_id,
+                current_ai_studio_model_id or MODEL_NAME,
+                aux_stream_factory,
+                completion_event,
+            )
+
+            if not result_future.done():
+                result_future.set_result(
+                    StreamingResponse(resilient_gen, media_type="text/event-stream")
+                )
+            else:
+                if not completion_event.is_set():
+                    completion_event.set()
+
+            return (
+                completion_event,
+                submit_button_locator,
+                check_client_disconnected,
+            )
+
+        except asyncio.CancelledError:
+            if completion_event and not completion_event.is_set():
+                completion_event.set()
+            raise
+        except Exception as e:
+            logger.error(
+                f"[{req_id}] Error getting stream data from queue: {e}", exc_info=True
+            )
+            raise
+    else:
+        # Non-streaming logic using auxiliary stream
+        content = None
+        reasoning_content = None
+        functions = None
+        final_data_from_aux_stream = None
+
+        page = context["page"]
+        # Disable silence detection for non-streaming requests to prevent premature timeouts
+        async for raw_data in use_stream_response(
+            req_id,
+            page=page,
+            check_client_disconnected=check_client_disconnected,
+            timeout=timeout,
+            silence_threshold=silence_threshold,
+            enable_silence_detection=False,
+        ):
+            check_client_disconnected(f"Non-streaming aux stream - loop ({req_id}): ")
+
+            if isinstance(raw_data, str):
+                try:
+                    data = json.loads(raw_data)
+                except json.JSONDecodeError:
+                    logger.warning(
+                        f"[{req_id}] Failed to parse non-stream data JSON: {raw_data}"
+                    )
+                    continue
+            elif isinstance(raw_data, dict):
+                data = raw_data
+            else:
+                continue
+
+            if not isinstance(data, dict):
+                continue
+
+            final_data_from_aux_stream = data
+            if data.get("done"):
+                content = data.get("body")
+                reasoning_content = data.get("reason")
+                functions = data.get("function")
+                break
+
+        if (
+            final_data_from_aux_stream
+            and final_data_from_aux_stream.get("reason") == "internal_timeout"
+        ):
+            logger.error(
+                f"[{req_id}] Non-stream request failed via aux stream: Internal Timeout"
+            )
+            raise HTTPException(
+                status_code=502,
+                detail=f"[{req_id}] Aux stream processing error (Internal Timeout)",
+            )
+
+        if (
+            final_data_from_aux_stream
+            and final_data_from_aux_stream.get("done") is True
+            and content is None
+        ):
+            logger.error(
+                f"[{req_id}] Non-stream request completed via aux stream but no content provided"
+            )
+            raise HTTPException(
+                status_code=502,
+                detail=f"[{req_id}] Aux stream completed but no content provided",
+            )
+
+        model_name_for_json = current_ai_studio_model_id or MODEL_NAME
+
+        # Consolidate reasoning content with body content
+        consolidated_content = ""
+        if reasoning_content and reasoning_content.strip():
+            consolidated_content += reasoning_content.strip()
+        if content and content.strip():
+            if consolidated_content:
+                consolidated_content += "\n\n"
+            consolidated_content += content.strip()
+
+        message_payload = {"role": "assistant", "content": consolidated_content}
+        finish_reason_val = "stop"
+
+        if functions and len(functions) > 0:
+            tool_calls_list: List[Dict[str, Any]] = []
+            for func_idx, function_call_data in enumerate(functions):
+                tool_calls_list.append(
+                    {
+                        "id": f"call_{_random_id()}",
+                        "index": func_idx,
+                        "type": "function",
+                        "function": {
+                            "name": function_call_data["name"],
+                            "arguments": json.dumps(function_call_data["params"]),
+                        },
+                    }
+                )
+            message_payload["tool_calls"] = tool_calls_list
+            finish_reason_val = "tool_calls"
+            message_payload["content"] = None
+
+        usage_stats = calculate_usage_stats(
+            [msg.model_dump() for msg in request.messages],
+            consolidated_content or "",
+            "",
+        )
+
+        total_tokens = usage_stats.get("total_tokens", 0)
+        GlobalState.increment_token_count(total_tokens)
+
+        from api_utils.server_state import state
+
+        if (
+            hasattr(state, "current_auth_profile_path")
+            and state.current_auth_profile_path
+        ):
+            await increment_profile_usage(state.current_auth_profile_path, total_tokens)
+
+        response_payload = build_chat_completion_response_json(
+            req_id,
+            model_name_for_json,
+            message_payload,
+            finish_reason_val,
+            usage_stats,
+            system_fingerprint="camoufox-proxy",
+            seed=request.seed
+            if hasattr(request, "seed") and request.seed is not None
+            else 0,
+            response_format=(
+                request.response_format
+                if hasattr(request, "response_format")
+                and isinstance(request.response_format, dict)
+                else {}
+            ),
+        )
+
+        if not result_future.done():
+            response_json_str = json.dumps(response_payload, ensure_ascii=False)
+            if len(response_json_str) > 10000:  # 10KB threshold
+                logger.info(
+                    f"[{req_id}] Large response detected ({len(response_json_str)} chars), using efficient chunking"
+                )
+
+                async def generate_json_chunks():
+                    chunk_size = 8192  # 8KB chunks
+                    for i in range(0, len(response_json_str), chunk_size):
+                        chunk = response_json_str[i : i + chunk_size]
+                        yield chunk
+                        await asyncio.sleep(0.01)
+
+                result_future.set_result(
+                    StreamingResponse(
+                        generate_json_chunks(), media_type="application/json"
+                    )
+                )
+            else:
+                result_future.set_result(JSONResponse(content=response_payload))
+        return response_payload
+
+
+async def _handle_playwright_response(
+    req_id: str,
+    request: ChatCompletionRequest,
+    page: AsyncPage,
+    context: dict,
+    result_future: Future,
+    submit_button_locator: Locator,
+    check_client_disconnected: Callable,
+    prompt_length: int,
+    timeout: float,
+) -> Optional[Tuple[Event, Locator, Callable]]:
+    """Handle response using Playwright - Enhanced version with integrity verification"""
+    from api_utils.server_state import state
+
+    logger = state.logger
+
+    is_streaming = request.stream
+    current_ai_studio_model_id = context.get("current_ai_studio_model_id")
+
+    await locate_response_elements(page, req_id, logger, check_client_disconnected)
+    check_client_disconnected("After Response Element Located: ")
+
+    if is_streaming:
+        completion_event = Event()
+
+        def playwright_stream_factory(event_to_signal: Event):
+            return gen_sse_from_playwright(
+                page,
+                logger,
+                req_id,
+                current_ai_studio_model_id or MODEL_NAME,
+                request,
+                check_client_disconnected,
+                event_to_signal,
+                prompt_length=prompt_length,
+                timeout=timeout,
+            )
+
+        resilient_gen = resilient_stream_generator(
+            req_id,
+            current_ai_studio_model_id or MODEL_NAME,
+            playwright_stream_factory,
+            completion_event,
+        )
+
+        if not result_future.done():
+            result_future.set_result(
+                StreamingResponse(resilient_gen, media_type="text/event-stream")
+            )
+
+        return completion_event, submit_button_locator, check_client_disconnected
+    else:
+        page_controller = PageController(page, logger, req_id)
+        response_data = await page_controller.get_response_with_integrity_check(
+            check_client_disconnected, prompt_length, timeout=timeout
+        )
+
+        final_content = response_data.get("content", "")
+        reasoning_content = response_data.get("reasoning_content", "")
+        recovery_method = response_data.get("recovery_method", "direct")
+
+        if recovery_method == "integrity_verification":
+            logger.info(
+                f"[{req_id}] Successfully recovered content via integrity verification ({len(final_content)} chars)"
+            )
+            await save_error_snapshot(
+                f"integrity_recovery_success_{req_id}",
+                extra_context={
+                    "content_length": len(final_content),
+                    "reasoning_length": len(reasoning_content),
+                    "recovery_trigger": response_data.get("trigger_reason", ""),
+                },
+            )
+        elif recovery_method == "direct":
+            logger.info(
+                f"[{req_id}] Successfully retrieved content directly ({len(final_content)} chars)"
+            )
+
+        consolidated_content = ""
+        if reasoning_content and reasoning_content.strip():
+            consolidated_content += reasoning_content.strip()
+        if final_content and final_content.strip():
+            if consolidated_content:
+                consolidated_content += "\n\n"
+            consolidated_content += final_content.strip()
+
+        usage_stats = calculate_usage_stats(
+            [msg.model_dump() for msg in request.messages],
+            consolidated_content,
+            "",
+        )
+        logger.info(f"[{req_id}] Token usage stats: {usage_stats}")
+
+        total_tokens = usage_stats.get("total_tokens", 0)
+        GlobalState.increment_token_count(total_tokens)
+
+        from api_utils.server_state import state
+
+        if (
+            hasattr(state, "current_auth_profile_path")
+            and state.current_auth_profile_path
+        ):
+            await increment_profile_usage(state.current_auth_profile_path, total_tokens)
+
+        model_name_for_json = current_ai_studio_model_id or MODEL_NAME
+
+        # Handle function calls if detected
+        if response_data.get("has_function_calls"):
+            from api_utils.utils_ext.function_calling_orchestrator import (
+                get_function_calling_orchestrator,
+            )
+
+            orchestrator = get_function_calling_orchestrator()
+            message_payload, finish_reason_val = (
+                orchestrator.format_function_calls_for_response(
+                    response_data.get("function_calls", []), consolidated_content
+                )
+            )
+        else:
+            message_payload = {"role": "assistant", "content": consolidated_content}
+            finish_reason_val = "stop"
+
+        response_payload = build_chat_completion_response_json(
+            req_id,
+            model_name_for_json,
+            message_payload,
+            finish_reason_val,
+            usage_stats,
+            system_fingerprint="camoufox-proxy",
+            seed=request.seed
+            if hasattr(request, "seed") and request.seed is not None
+            else 0,
+            response_format=(
+                request.response_format
+                if hasattr(request, "response_format")
+                and isinstance(request.response_format, dict)
+                else {}
+            ),
+        )
+
+        if not result_future.done():
+            response_json_str = json.dumps(response_payload, ensure_ascii=False)
+            if len(response_json_str) > 10000:
+
+                async def generate_json_chunks():
+                    chunk_size = 8192
+                    for i in range(0, len(response_json_str), chunk_size):
+                        yield response_json_str[i : i + chunk_size]
+                        await asyncio.sleep(0.01)
+
+                result_future.set_result(
+                    StreamingResponse(
+                        generate_json_chunks(), media_type="application/json"
+                    )
+                )
+            else:
+                result_future.set_result(JSONResponse(content=response_payload))
+
+        return response_payload
+
+
+async def _cleanup_request_resources(
+    req_id: str,
+    disconnect_check_task: Optional[asyncio.Task],
+    completion_event: Optional[Event],
+    result_future: Future,
+    is_streaming: bool,
+) -> None:
+    """Cleanup request resources"""
+    from api_utils.server_state import state
+
+    logger = state.logger
+
+    if disconnect_check_task and not disconnect_check_task.done():
+        disconnect_check_task.cancel()
+        try:
+            await disconnect_check_task
+        except asyncio.CancelledError:
+            pass
+
+    # Clean up upload subdirectory
+    try:
+        req_dir = os.path.join(UPLOAD_FILES_DIR, req_id)
+        if os.path.isdir(req_dir):
+            shutil.rmtree(req_dir, ignore_errors=True)
+            logger.debug(f"Cleaned up request upload directory: {req_dir}")
+    except asyncio.CancelledError:
+        raise
+    except Exception as clean_err:
+        logger.warning(f"[{req_id}] Failed to clean up upload directory: {clean_err}")
+
+    if (
+        is_streaming
+        and completion_event
+        and not completion_event.is_set()
+        and (result_future.done() and result_future.exception() is not None)
+    ):
+        logger.warning(
+            f"[{req_id}] Stream request exception, ensuring completion event is set."
+        )
+        completion_event.set()
+
+
+async def process_request_with_retry(
+    req_id: str,
+    request: ChatCompletionRequest,
+    http_request: Request,
+    result_future: Future,
+) -> Optional[Tuple[Event, Locator, Callable[[str], bool]]]:
+    """Wrapper around _process_request_refactored with retry mechanism for quota"""
+    from api_utils.server_state import state
+
+    logger = state.logger
+
+    max_retries = 3
+    attempt = 0
+    while attempt < max_retries:
+        attempt += 1
+        try:
+            return await _process_request_refactored(
+                req_id, request, http_request, result_future
+            )
+        except QuotaExceededRetry:
+            logger.warning(
+                f"[{req_id}] Quota wall hit (attempt {attempt}/{max_retries}). Waiting for rotation..."
+            )
+            await GlobalState.rotation_complete_event.wait()
+            logger.info(f"[{req_id}] Rotation complete. Retrying request.")
+            continue
+    logger.error(f"[{req_id}] Request failed after {max_retries} retries due to quota.")
+    raise Exception(f"Request failed after {max_retries} retries due to quota issues.")
+
+
+async def process_request(
+    req_id: str,
+    request: ChatCompletionRequest,
+    http_request: Request,
+    result_future: Future,
+) -> Optional[Tuple[Event, Locator, Callable[[str], bool]]]:
+    """Main entry point for request processing"""
+    return await process_request_with_retry(
+        req_id, request, http_request, result_future
+    )
+
+
+async def _process_request_refactored(
+    req_id: str,
+    request: ChatCompletionRequest,
+    http_request: Request,
+    result_future: Future,
+) -> Optional[Tuple[Event, Locator, Callable[[str], bool]]]:
+    """Core Request Processing Function - Refactored Version"""
+    from api_utils.server_state import state
+
+    logger = state.logger
+
+    # 0. Check Auth Rotation Lock
+    if not GlobalState.AUTH_ROTATION_LOCK.is_set():
+        logger.info(f"[{req_id}] Request held: Waiting for auth rotation...")
+        await GlobalState.AUTH_ROTATION_LOCK.wait()
+        logger.info(f"[{req_id}] ▶️ Resuming after Auth Rotation.")
+
+    # [GR-03] Pre-Flight Graceful Rotation Check
+    if GlobalState.NEEDS_ROTATION:
+        logger.info(f"[{req_id}] 🔄 Graceful Rotation Pending. Initiating rotation...")
+        from api_utils.server_state import state
+
+        current_model_id = state.current_ai_studio_model_id
+        from browser_utils.auth_rotation import perform_auth_rotation
+
+        if await perform_auth_rotation(target_model_id=current_model_id):
+            GlobalState.NEEDS_ROTATION = False
+            logger.info(f"[{req_id}] ✅ Pre-flight rotation complete.")
+
+    is_connected = await _test_client_connection(req_id, http_request)
+    if not is_connected:
+        logger.info(f"[{req_id}] Client disconnected before processing.")
+        if not result_future.done():
+            result_future.set_exception(
+                HTTPException(status_code=499, detail="Client disconnected")
+            )
+        return None
+
+    stream_port = get_environment_variable("STREAM_PORT")
+    use_stream = stream_port != "0"
+    if use_stream:
+        try:
+            from api_utils import clear_stream_queue
+
+            await clear_stream_queue()
+        except asyncio.CancelledError:
+            raise
+        except Exception as clear_err:
+            logger.warning(f"[Stream] Error clearing queue: {clear_err}")
+
+    context = await _initialize_request_context(req_id, request)
+    context = await _analyze_model_requirements(req_id, context, request)
+
+    (
+        _,
+        disconnect_check_task,
+        check_client_disconnected,
+    ) = await _setup_disconnect_monitoring(req_id, http_request, result_future)
+
+    page = context["page"]
+    submit_button_locator = page.locator(SUBMIT_BUTTON_SELECTOR) if page else None
+    completion_event = None
+
+    try:
+        await _validate_page_status(req_id, context, check_client_disconnected)
+        if page is None:
+            raise server_error(req_id, "Page is None")
+
+        page_controller = PageController(page, context["logger"], req_id)
+        await _handle_model_switching(req_id, context, check_client_disconnected)
+        await _handle_parameter_cache(req_id, context)
+
+        # --- Native Function Calling Setup (Phase 3) ---
+        # Configure native function calling if mode is native/auto and tools are present
+        fc_orchestrator = get_function_calling_orchestrator()
+        fc_state: Optional[FunctionCallingState] = None
+
+        if getattr(request, "tools", None):
+            try:
+                fc_state = await fc_orchestrator.prepare_request(
+                    tools=request.tools,
+                    tool_choice=getattr(request, "tool_choice", None),
+                    page_controller=page_controller,
+                    check_client_disconnected=check_client_disconnected,
+                    req_id=req_id,
+                )
+            except Exception as fc_err:
+                logger.warning(
+                    f"[{req_id}] Function calling setup failed: {fc_err}, continuing with emulated mode"
+                )
+                # Continue with request - fallback to emulated mode happens in prepare_combined_prompt
+
+        (
+            prepared_prompt,
+            attachments_list,
+            tool_exec_results,
+        ) = await _prepare_and_validate_request(
+            req_id, request, check_client_disconnected, fc_state=fc_state
+        )
+
+        # [TOOL-FORCED] If tool was executed locally (forced), return immediately bypassing AI Studio flow
+        if tool_exec_results:
+            logger.info(
+                f"[{req_id}] Active tool execution detected, returning results immediately."
+            )
+            tool_calls_list = []
+            for res in tool_exec_results:
+                tool_calls_list.append(
+                    {
+                        "id": f"call_{_random_id()}",
+                        "type": "function",
+                        "function": {
+                            "name": res["name"],
+                            "arguments": res["arguments"],
+                        },
+                    }
+                )
+
+            message_payload = {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": tool_calls_list,
+            }
+
+            usage_stats = calculate_usage_stats(
+                [msg.model_dump() for msg in request.messages],
+                "",
+                "",
+            )
+
+            response_payload = build_chat_completion_response_json(
+                req_id,
+                request.model or MODEL_NAME,
+                message_payload,
+                "tool_calls",
+                usage_stats,
+                seed=request.seed
+                if hasattr(request, "seed") and request.seed is not None
+                else 0,
+            )
+
+            if not result_future.done():
+                result_future.set_result(JSONResponse(content=response_payload))
+
+            # Return dummy event for forced tool execution to satisfy type requirement
+            dummy_event = Event()
+            dummy_event.set()
+            return dummy_event, submit_button_locator, check_client_disconnected
+
+        request_params = request.model_dump(exclude_none=True)
+        if "stop" in request.model_fields_set and request.stop is None:
+            request_params["stop"] = None
+
+        with log_context("Adjusting Parameters", context["logger"], silent=True):
+            await page_controller.adjust_parameters(
+                request_params,
+                context["page_params_cache"],
+                context["params_cache_lock"],
+                context["model_id_to_use"],
+                context["parsed_model_list"],
+                check_client_disconnected,
+            )
+
+        check_client_disconnected("Final check before submitting prompt")
+
+        with log_context("Execution", context["logger"], silent=True):
+            await page_controller.submit_prompt(
+                prepared_prompt, attachments_list, check_client_disconnected
+            )
+
+        # Sync page reference if changed
+        if page_controller.page != page:
+            logger.info(f"[{req_id}] Page updated, syncing references...")
+            page = page_controller.page
+            context["page"] = page
+            submit_button_locator = page.locator(SUBMIT_BUTTON_SELECTOR)
+
+        calc_timeout = 5.0 + (len(prepared_prompt) / 1000.0)
+        config_timeout = RESPONSE_COMPLETION_TIMEOUT / 1000.0
+        dynamic_timeout = max(calc_timeout, config_timeout)
+        dynamic_silence_threshold = max(60.0, dynamic_timeout / 2.0)
+
+        logger.info(
+            f"[{req_id}] Dynamic timeout: {dynamic_timeout:.2f}s, silence threshold: {dynamic_silence_threshold:.2f}s"
+        )
+
+        response_result = await _handle_response_processing(
+            req_id,
+            request,
+            page,
+            context,
+            result_future,
+            submit_button_locator,
+            check_client_disconnected,
+            len(prepared_prompt),
+            timeout=dynamic_timeout,
+            silence_threshold=dynamic_silence_threshold,
+        )
+
+        if response_result:
+            if isinstance(response_result, dict):
+                return response_result, submit_button_locator, check_client_disconnected
+            if isinstance(response_result, tuple):
+                completion_event, _, _ = response_result
+                return (
+                    completion_event,
+                    submit_button_locator,
+                    check_client_disconnected,
+                )
+
+        return completion_event, submit_button_locator, check_client_disconnected
+
+    except ClientDisconnectedError as disco_err:
+        logger.info(f"[{req_id}] Client disconnected: {disco_err}")
+        if not result_future.done():
+            result_future.set_exception(client_disconnected(req_id, "Disconnected"))
+        return completion_event, submit_button_locator, check_client_disconnected
+    except HTTPException as http_err:
+        logger.warning(f"[{req_id}] HTTP exception: {http_err.status_code}")
+        if not result_future.done():
+            result_future.set_exception(http_err)
+        return completion_event, submit_button_locator, check_client_disconnected
+    except QuotaExceededError as quota_err:
+        logger.warning(f"[{req_id}] Quota Exceeded: {quota_err}")
+        if not GlobalState.IS_QUOTA_EXCEEDED:
+            GlobalState.set_quota_exceeded(message=str(quota_err))
+        raise quota_err
+    except PlaywrightAsyncError as pw_err:
+        logger.error(f"[{req_id}] Playwright error: {pw_err}")
+        await save_error_snapshot(f"process_pw_error_{req_id}")
+        if not result_future.done():
+            result_future.set_exception(
+                upstream_error(req_id, f"Interaction failed: {pw_err}")
+            )
+        return completion_event, submit_button_locator, check_client_disconnected
+    except Exception as e:
+        logger.exception(f"[{req_id}] Unexpected error")
+        await save_error_snapshot(f"process_error_{req_id}")
+        if not result_future.done():
+            result_future.set_exception(server_error(req_id, str(e)))
+        return completion_event, submit_button_locator, check_client_disconnected
+    finally:
+        await _cleanup_request_resources(
+            req_id,
+            disconnect_check_task,
+            completion_event,
+            result_future,
+            request.stream or False,
+        )

api_utils/response_generators.py

@@ -0,0 +1,613 @@
+import asyncio
+import json
+import logging
+import random
+import re
+import time
+from asyncio import Event
+from typing import Any, AsyncGenerator, Callable, Dict, List, Optional, cast
+
+from playwright.async_api import Page as AsyncPage
+
+from api_utils.utils_ext.usage_tracker import increment_profile_usage
+from config import CHAT_COMPLETION_ID_PREFIX
+from config.global_state import GlobalState
+from logging_utils import set_request_id
+from models import (
+    ChatCompletionRequest,
+    ClientDisconnectedError,
+    QuotaExceededError,
+    QuotaExceededRetry,
+)
+
+from .common_utils import random_id
+from .sse import generate_sse_chunk, generate_sse_stop_chunk
+from .utils_ext.stream import use_stream_response
+from .utils_ext.tokens import calculate_usage_stats
+
+# Pattern to strip emulated function call text from body content
+# This prevents "Request function call: ..." from being sent as text content
+_FUNCTION_CALL_TEXT_PATTERN = re.compile(
+    r"Request\s+function\s+call:\s*[^\n]+(?:\n(?:Parameters:\s*)?\s*\{[\s\S]*?\})?",
+    re.IGNORECASE,
+)
+
+# Pattern to strip control characters like <ctrl46> from body content
+# These appear in AI Studio's wire format as string delimiters
+# Also captures trailing } or { that may follow control chars (JSON leak artifacts)
+_CONTROL_CHAR_PATTERN = re.compile(r"<ctrl\d+>[\}\{]?")
+
+
+def _clean_body_text(body: str) -> str:
+    """Clean body text by removing control characters and JSON artifacts."""
+    if not body:
+        return body
+    return _CONTROL_CHAR_PATTERN.sub("", body)
+
+
+async def resilient_stream_generator(
+    req_id: str,
+    model_name: str,
+    generator_factory: Callable[[Event], AsyncGenerator[str, None]],
+    completion_event: Event,
+) -> AsyncGenerator[str, None]:
+    """
+    Wraps a stream generator with resiliency logic.
+    Handles QuotaExceededError by triggering auth rotation and retrying.
+    """
+    from api_utils.server_state import state
+
+    logger = state.logger
+    from browser_utils.auth_rotation import perform_auth_rotation
+
+    max_retries = 3
+    retry_count = 0
+
+    inner_event = Event()
+
+    try:
+        while retry_count <= max_retries:
+            try:
+                if inner_event.is_set():
+                    inner_event.clear()
+
+                async for chunk in generator_factory(inner_event):
+                    yield chunk
+
+                return
+
+            except (QuotaExceededError, QuotaExceededRetry) as e:
+                retry_count += 1
+                if retry_count > max_retries:
+                    logger.error(
+                        f"[{req_id}] Max retries ({max_retries}) exhausted for quota recovery."
+                    )
+                    yield f"data: {json.dumps({'error': 'Max retries exhausted for quota recovery.'}, ensure_ascii=False)}\n\n"
+                    return
+
+                logger.warning(
+                    f"[{req_id}] Quota limit hit during stream: {str(e)}. Initiating rotation (Attempt {retry_count}/{max_retries})..."
+                )
+                yield f": processing auth rotation (attempt {retry_count})...\n\n"
+
+                rotation_task = asyncio.create_task(
+                    perform_auth_rotation(target_model_id=model_name)
+                )
+
+                rotation_start = time.time()
+                while not rotation_task.done():
+                    if time.time() - rotation_start > 120:
+                        logger.error(f"[{req_id}] Rotation timed out.")
+                        yield f"data: {json.dumps({'error': 'Auth rotation timed out.'}, ensure_ascii=False)}\n\n"
+                        return
+
+                    yield ": processing auth rotation...\n\n"
+                    await asyncio.sleep(2)
+
+                success = await rotation_task
+                if success:
+                    logger.info(
+                        f"[{req_id}] Auth rotation successful. Retrying stream generation..."
+                    )
+                    yield ": auth rotation complete, retrying...\n\n"
+                    continue
+                else:
+                    logger.error(f"[{req_id}] Auth rotation failed.")
+                    yield f"data: {json.dumps({'error': 'Auth rotation failed.'}, ensure_ascii=False)}\n\n"
+                    return
+            except Exception:
+                raise
+    finally:
+        if not completion_event.is_set():
+            completion_event.set()
+            logger.info(f"[{req_id}] Resilient stream completion event set")
+
+
+async def gen_sse_from_aux_stream(
+    req_id: str,
+    request: ChatCompletionRequest,
+    model_name_for_stream: str,
+    check_client_disconnected: Callable[[str], bool],
+    event_to_set: Event,
+    timeout: float,
+    silence_threshold: float = 60.0,
+    page: Optional[AsyncPage] = None,
+    stream_state: Optional[Dict[str, Any]] = None,
+) -> AsyncGenerator[str, None]:
+    """Auxiliary stream queue -> OpenAI compatible SSE generator."""
+    logger = logging.getLogger("AIStudioProxyServer")
+    set_request_id(req_id)
+
+    last_reason_pos = 0
+    last_body_pos = 0
+    chat_completion_id = f"{CHAT_COMPLETION_ID_PREFIX}{req_id}-{int(time.time())}-{random.randint(100, 999)}"
+    created_timestamp = int(time.time())
+
+    full_reasoning_content = ""
+    full_body_content = ""
+    data_receiving = False
+    is_response_finalized = False
+    finish_reason = "stop"
+
+    has_started_body = False
+
+    try:
+        async for raw_data in use_stream_response(
+            req_id,
+            timeout=timeout,
+            silence_threshold=silence_threshold,
+            page=page,
+            check_client_disconnected=check_client_disconnected,
+            enable_silence_detection=True,
+        ):
+            data_receiving = True
+
+            if (
+                GlobalState.CURRENT_STREAM_REQ_ID
+                and GlobalState.CURRENT_STREAM_REQ_ID != req_id
+            ):
+                logger.warning(f"[{req_id}] 🧟 Zombie Stream Detected! Terminating.")
+                break
+
+            if GlobalState.QUOTA_EXCEEDED_EVENT.is_set():
+                raise QuotaExceededRetry("Quota exceeded detected mid-stream.")
+
+            if is_response_finalized:
+                logger.warning(
+                    f"[{req_id}] ⚠️ Extraneous message received after response finalization. Ignoring."
+                )
+                continue
+
+            # Holding Pattern for Recovery
+            if GlobalState.IS_RECOVERING:
+                logger.info(
+                    f"[{req_id}] ⏸️ System in Recovery Mode. Holding stream open..."
+                )
+                recovery_wait_start = time.time()
+                while GlobalState.IS_RECOVERING:
+                    if time.time() - recovery_wait_start > 120.0:
+                        logger.error(f"[{req_id}] ❌ Recovery Timed Out. Aborting.")
+                        yield generate_sse_chunk(
+                            "\n\n[SYSTEM: Service Recovery Failed. Please retry.]",
+                            req_id,
+                            model_name_for_stream,
+                        )
+                        yield generate_sse_stop_chunk(req_id, model_name_for_stream)
+                        break
+                    yield ": heartbeat\n\n"
+                    await asyncio.sleep(1.0)
+
+                if GlobalState.IS_RECOVERING:
+                    break
+                logger.info(f"[{req_id}] ▶️ Recovery Complete. Resuming stream.")
+
+            if GlobalState.IS_QUOTA_EXCEEDED and not GlobalState.IS_RECOVERING:
+                logger.warning(
+                    f"[{req_id}] ⚠️ Quota exceeded detected. Waiting for recovery initiation..."
+                )
+                await asyncio.sleep(1)
+                if GlobalState.IS_RECOVERING:
+                    continue
+                logger.warning(
+                    f"[{req_id}] ⛔ Quota exceeded, waiting for worker to pick up signal..."
+                )
+                await asyncio.sleep(2)
+                continue
+
+            try:
+                check_client_disconnected(f"Stream generator loop ({req_id}): ")
+            except ClientDisconnectedError:
+                logger.info(
+                    f"[{req_id}] Client disconnected, terminating stream generation"
+                )
+                if data_receiving and not event_to_set.is_set():
+                    event_to_set.set()
+                break
+
+            data: Any
+            if isinstance(raw_data, str):
+                try:
+                    data = json.loads(raw_data)
+                except json.JSONDecodeError:
+                    logger.warning(
+                        f"[{req_id}] Failed to parse stream data JSON: {raw_data}"
+                    )
+                    continue
+            elif isinstance(raw_data, dict):
+                data = cast(Dict[str, Any], raw_data)
+            else:
+                continue
+
+            if not isinstance(data, dict):
+                continue
+
+            typed_data: Dict[str, Any] = cast(Dict[str, Any], data)
+            reason = str(typed_data.get("reason", ""))
+            body = _clean_body_text(str(typed_data.get("body", "")))
+            done = bool(typed_data.get("done", False))
+            function = cast(List[Any], typed_data.get("function", []))
+
+            if reason:
+                full_reasoning_content = reason
+            if body:
+                full_body_content = body
+
+            # The Latch: Reasoning Handling
+            if len(reason) > last_reason_pos:
+                reason_delta = reason[last_reason_pos:]
+                if not has_started_body:
+                    output = {
+                        "id": chat_completion_id,
+                        "object": "chat.completion.chunk",
+                        "model": model_name_for_stream,
+                        "created": created_timestamp,
+                        "choices": [
+                            {
+                                "index": 0,
+                                "delta": {
+                                    "role": "assistant",
+                                    "content": None,
+                                    "reasoning_content": reason_delta,
+                                },
+                                "finish_reason": None,
+                            }
+                        ],
+                    }
+                    yield f"data: {json.dumps(output, ensure_ascii=False, separators=(',', ':'))}\n\n"
+                last_reason_pos = len(reason)
+
+            # The Latch: Body Handling
+            # ALWAYS strip "Request function call:..." text from body
+            # This prevents emulated FC text from appearing as content to clients
+            # even when function call detection fails (race condition protection)
+            original_body = body
+            if body:
+                body = _FUNCTION_CALL_TEXT_PATTERN.sub("", body).strip()
+                if body != original_body:
+                    full_body_content = body
+                    # If we stripped FC text but function is empty, try parsing from the original
+                    if not function:
+                        from api_utils.utils_ext.function_call_response_parser import (
+                            parse_emulated_function_calls_static,
+                        )
+
+                        parsed_fc = parse_emulated_function_calls_static(original_body)
+                        if parsed_fc:
+                            function = parsed_fc
+                            # Demoted from INFO to DEBUG - this is normal fallback behavior
+                            # when model outputs text format instead of native FC
+                            logger.debug(
+                                f"[{req_id}] Recovered function calls from emulated text"
+                            )
+
+            if len(body) > last_body_pos:
+                body_delta = body[last_body_pos:]
+                # Only stream body content if there's actual content after stripping
+                if body_delta.strip():
+                    has_started_body = True
+                    output = {
+                        "id": chat_completion_id,
+                        "object": "chat.completion.chunk",
+                        "model": model_name_for_stream,
+                        "created": created_timestamp,
+                        "choices": [
+                            {
+                                "index": 0,
+                                "delta": {
+                                    "role": "assistant",
+                                    "content": body_delta,
+                                },
+                                "finish_reason": None,
+                            }
+                        ],
+                    }
+                    yield f"data: {json.dumps(output, ensure_ascii=False, separators=(',', ':'))}\n\n"
+                last_body_pos = len(body)
+
+            if done:
+                is_recovering = GlobalState.IS_RECOVERING
+                is_quota_exceeded = GlobalState.IS_QUOTA_EXCEEDED
+
+                if (
+                    done
+                    and not has_started_body
+                    and not is_recovering
+                    and not is_quota_exceeded
+                ):
+                    try:
+                        from browser_utils.operations import check_quota_limit
+
+                        if page:
+                            await check_quota_limit(page, req_id)
+                    except Exception:
+                        pass
+                    await asyncio.sleep(2.0)
+                    is_quota_exceeded = GlobalState.IS_QUOTA_EXCEEDED
+                    is_recovering = GlobalState.IS_RECOVERING
+
+                if (
+                    not has_started_body
+                    and not is_recovering
+                    and not is_quota_exceeded
+                    and not function
+                ):
+                    # Only show synthetic message when there's truly no content AND no function calls
+                    # In native FC mode, empty body with function calls is expected
+                    fallback_text = (
+                        "\n\n*(Model finished thinking but generated no output.)*"
+                    )
+                    output = {
+                        "id": chat_completion_id,
+                        "object": "chat.completion.chunk",
+                        "model": model_name_for_stream,
+                        "created": created_timestamp,
+                        "choices": [
+                            {
+                                "index": 0,
+                                "delta": {
+                                    "role": "assistant",
+                                    "content": fallback_text,
+                                },
+                                "finish_reason": None,
+                            }
+                        ],
+                    }
+                    yield f"data: {json.dumps(output, ensure_ascii=False, separators=(',', ':'))}\n\n"
+                    full_body_content += fallback_text
+                    has_started_body = True
+                elif is_recovering or is_quota_exceeded:
+                    while GlobalState.IS_QUOTA_EXCEEDED or GlobalState.IS_RECOVERING:
+                        yield ": heartbeat\n\n"
+                        await asyncio.sleep(1.0)
+
+                if function:
+                    finish_reason = "tool_calls"
+                    tool_calls_list = []
+                    for func_idx, function_call_data in enumerate(function):
+                        if isinstance(function_call_data, dict):
+                            tool_calls_list.append(
+                                {
+                                    "id": f"call_{random_id()}",
+                                    "index": func_idx,
+                                    "type": "function",
+                                    "function": {
+                                        "name": function_call_data.get("name", ""),
+                                        "arguments": json.dumps(
+                                            function_call_data.get("params", {})
+                                        ),
+                                    },
+                                }
+                            )
+                    choice_item = {
+                        "index": 0,
+                        "delta": {
+                            "tool_calls": tool_calls_list,
+                        },
+                        "finish_reason": None,
+                    }
+                else:
+                    finish_reason = "stop"
+                    choice_item = {
+                        "index": 0,
+                        "delta": {},
+                        "finish_reason": None,
+                    }
+
+                output = {
+                    "id": chat_completion_id,
+                    "object": "chat.completion.chunk",
+                    "model": model_name_for_stream,
+                    "created": created_timestamp,
+                    "choices": [choice_item],
+                }
+                yield f"data: {json.dumps(output, ensure_ascii=False, separators=(',', ':'))}\n\n"
+                is_response_finalized = True
+                break
+
+    except (QuotaExceededError, QuotaExceededRetry):
+        raise
+    except ClientDisconnectedError:
+        logger.info(f"[{req_id}] Client disconnected in stream generator")
+        if data_receiving and not event_to_set.is_set():
+            event_to_set.set()
+    except asyncio.CancelledError:
+        if not event_to_set.is_set():
+            event_to_set.set()
+        raise
+    except Exception as e:
+        logger.error(f"[{req_id}] Error in stream generator: {e}", exc_info=True)
+        try:
+            error_chunk = {
+                "id": chat_completion_id,
+                "object": "chat.completion.chunk",
+                "model": model_name_for_stream,
+                "created": created_timestamp,
+                "choices": [
+                    {
+                        "index": 0,
+                        "delta": {
+                            "role": "assistant",
+                            "content": f"\n\n[Error: {str(e)}]",
+                        },
+                        "finish_reason": "stop",
+                    }
+                ],
+            }
+            yield f"data: {json.dumps(error_chunk, ensure_ascii=False, separators=(',', ':'))}\n\n"
+        except Exception:
+            pass
+    finally:
+        try:
+            usage_stats = calculate_usage_stats(
+                [msg.model_dump() for msg in request.messages],
+                full_body_content,
+                full_reasoning_content,
+            )
+            total_tokens = usage_stats.get("total_tokens", 0)
+            GlobalState.increment_token_count(total_tokens)
+            from api_utils.server_state import state
+
+            if (
+                hasattr(state, "current_auth_profile_path")
+                and state.current_auth_profile_path
+            ):
+                await increment_profile_usage(
+                    state.current_auth_profile_path, total_tokens
+                )
+
+            final_chunk = {
+                "id": chat_completion_id,
+                "object": "chat.completion.chunk",
+                "model": model_name_for_stream,
+                "created": created_timestamp,
+                "choices": [{"index": 0, "delta": {}, "finish_reason": finish_reason}],
+                "usage": usage_stats,
+            }
+            yield f"data: {json.dumps(final_chunk, ensure_ascii=False, separators=(',', ':'))}\n\n"
+        except Exception as usage_err:
+            logger.error(f"[{req_id}] Error sending usage stats: {usage_err}")
+
+        yield "data: [DONE]\n\n"
+        if not event_to_set.is_set():
+            event_to_set.set()
+
+        if stream_state is not None:
+            stream_state["has_content"] = bool(
+                full_body_content or full_reasoning_content
+            )
+
+
+async def gen_sse_from_playwright(
+    page: AsyncPage,
+    logger: logging.Logger,
+    req_id: str,
+    model_name_for_stream: str,
+    request: ChatCompletionRequest,
+    check_client_disconnected: Callable[[str], bool],
+    completion_event: Event,
+    prompt_length: int,
+    timeout: float,
+) -> AsyncGenerator[str, None]:
+    """Playwright response -> OpenAI compatible SSE generator."""
+    from browser_utils.page_controller import PageController
+    from models import ClientDisconnectedError
+
+    set_request_id(req_id)
+    data_receiving = False
+    try:
+        page_controller = PageController(page, logger, req_id)
+        # Use get_response_with_function_calls which handles both content and functions
+        response_data = await page_controller.get_response_with_function_calls(
+            check_client_disconnected, prompt_length=prompt_length, timeout=timeout
+        )
+        final_content = response_data.get("content", "")
+        function_calls = response_data.get("function_calls", [])
+
+        data_receiving = True
+        lines = final_content.split("\n")
+        for line_idx, line in enumerate(lines):
+            try:
+                check_client_disconnected(
+                    f"Playwright stream generator loop ({req_id}): "
+                )
+            except ClientDisconnectedError:
+                if data_receiving and not completion_event.is_set():
+                    completion_event.set()
+                break
+            if line:
+                chunk_size = 5
+                for i in range(0, len(line), chunk_size):
+                    yield generate_sse_chunk(
+                        line[i : i + chunk_size], req_id, model_name_for_stream
+                    )
+                    await asyncio.sleep(0.03)
+            if line_idx < len(lines) - 1:
+                yield generate_sse_chunk("\n", req_id, model_name_for_stream)
+                await asyncio.sleep(0.01)
+
+        usage_stats = calculate_usage_stats(
+            [msg.model_dump() for msg in request.messages], final_content, ""
+        )
+        total_tokens = usage_stats.get("total_tokens", 0)
+        GlobalState.increment_token_count(total_tokens)
+        from api_utils.server_state import state
+
+        if (
+            hasattr(state, "current_auth_profile_path")
+            and state.current_auth_profile_path
+        ):
+            await increment_profile_usage(state.current_auth_profile_path, total_tokens)
+
+        if function_calls:
+            from api_utils.utils_ext.function_calling_orchestrator import (
+                get_function_calling_orchestrator,
+            )
+
+            orchestrator = get_function_calling_orchestrator()
+            tool_calls_deltas = orchestrator.format_streaming_tool_calls(function_calls)
+            for delta in tool_calls_deltas:
+                chunk = {
+                    "id": f"chatcmpl-{req_id}",
+                    "object": "chat.completion.chunk",
+                    "created": int(time.time()),
+                    "model": model_name_for_stream,
+                    "choices": [
+                        {
+                            "index": 0,
+                            "delta": {"tool_calls": [delta]},
+                            "finish_reason": None,
+                        }
+                    ],
+                }
+                yield f"data: {json.dumps(chunk, ensure_ascii=False, separators=(',', ':'))}\n\n"
+
+            yield generate_sse_stop_chunk(
+                req_id, model_name_for_stream, "tool_calls", usage_stats
+            )
+        else:
+            yield generate_sse_stop_chunk(
+                req_id, model_name_for_stream, "stop", usage_stats
+            )
+    except (QuotaExceededError, QuotaExceededRetry):
+        raise
+    except ClientDisconnectedError:
+        if data_receiving and not completion_event.is_set():
+            completion_event.set()
+    except asyncio.CancelledError:
+        if not completion_event.is_set():
+            completion_event.set()
+        raise
+    except Exception as e:
+        logger.error(
+            f"[{req_id}] Error in Playwright stream generator: {e}", exc_info=True
+        )
+        try:
+            yield generate_sse_chunk(
+                f"\n\n[Error: {str(e)}]", req_id, model_name_for_stream
+            )
+            yield generate_sse_stop_chunk(req_id, model_name_for_stream)
+        except Exception:
+            pass
+    finally:
+        if not completion_event.is_set():
+            completion_event.set()

api_utils/response_payloads.py

@@ -0,0 +1,39 @@
+import time
+from typing import Any, Dict, Optional
+
+from config import CHAT_COMPLETION_ID_PREFIX
+
+
+def build_chat_completion_response_json(
+    req_id: str,
+    model_name: str,
+    message_payload: Dict[str, Any],
+    finish_reason: str,
+    usage_stats: Dict[str, int],
+    system_fingerprint: str = "camoufox-proxy",
+    seed: Optional[int] = None,
+    response_format: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Construct an OpenAI-compatible non-streaming chat.completion JSON response."""
+    created_ts = int(time.time())
+    resp: Dict[str, Any] = {
+        "id": f"{CHAT_COMPLETION_ID_PREFIX}{req_id}-{created_ts}",
+        "object": "chat.completion",
+        "created": created_ts,
+        "model": model_name,
+        "choices": [
+            {
+                "index": 0,
+                "message": message_payload,
+                "finish_reason": finish_reason,
+                "native_finish_reason": finish_reason,
+            }
+        ],
+        "usage": usage_stats,
+        "system_fingerprint": system_fingerprint,
+    }
+    if seed is not None:
+        resp["seed"] = seed
+    if response_format is not None:
+        resp["response_format"] = response_format
+    return resp

api_utils/routers/__init__.py

@@ -0,0 +1,42 @@
+"""
+Modular FastAPI routers for api_utils.
+Each module defines focused endpoint handlers. This package aggregates them.
+"""
+
+# Re-export handlers for convenient imports
+from .api_keys import add_api_key, delete_api_key, get_api_keys, test_api_key
+from .auth_files import router as auth_files_router
+from .chat import chat_completions
+from .health import health_check
+from .helper import router as helper_router
+from .info import get_api_info
+from .logs_ws import websocket_log_endpoint
+from .model_capabilities import router as model_capabilities_router
+from .models import list_models
+from .ports import router as ports_router
+from .proxy import router as proxy_router
+from .queue import cancel_request, get_queue_status
+from .server import router as server_router
+from .static import read_index, serve_react_assets
+
+__all__ = [
+    "read_index",
+    "serve_react_assets",
+    "get_api_info",
+    "health_check",
+    "list_models",
+    "model_capabilities_router",
+    "chat_completions",
+    "cancel_request",
+    "get_queue_status",
+    "websocket_log_endpoint",
+    "get_api_keys",
+    "add_api_key",
+    "test_api_key",
+    "delete_api_key",
+    "proxy_router",
+    "auth_files_router",
+    "ports_router",
+    "server_router",
+    "helper_router",
+]

api_utils/routers/api_keys.py

@@ -0,0 +1,122 @@
+import logging
+
+from fastapi import Depends, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from ..dependencies import get_logger
+
+
+class ApiKeyRequest(BaseModel):
+    key: str
+
+
+class ApiKeyTestRequest(BaseModel):
+    key: str
+
+
+async def get_api_keys(logger: logging.Logger = Depends(get_logger)):
+    from .. import auth_utils
+
+    try:
+        auth_utils.initialize_keys()
+        keys_info = list(auth_utils.API_KEYS)
+        return JSONResponse(
+            content={"success": True, "keys": keys_info, "total_count": len(keys_info)}
+        )
+    except Exception as e:
+        logger.error(f"Failed to get API key list: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+async def add_api_key(
+    request: ApiKeyRequest, logger: logging.Logger = Depends(get_logger)
+):
+    from .. import auth_utils
+
+    key_value = request.key.strip()
+    if not key_value or len(key_value) < 8:
+        raise HTTPException(status_code=400, detail="Invalid API key format.")
+
+    auth_utils.initialize_keys()
+    if key_value in auth_utils.API_KEYS:
+        raise HTTPException(status_code=400, detail="API key already exists.")
+
+    try:
+        key_file_path = auth_utils.KEY_FILE_PATH
+        with open(key_file_path, "a+", encoding="utf-8") as f:
+            f.seek(0)
+            if f.read():
+                f.write("\n")
+            f.write(key_value)
+
+        auth_utils.initialize_keys()
+        logger.info(f"API key added: {key_value[:4]}...{key_value[-4:]}")
+        return JSONResponse(
+            content={
+                "success": True,
+                "message": "API key added successfully",
+                "key_count": len(auth_utils.API_KEYS),
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to add API key: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+async def test_api_key(
+    request: ApiKeyTestRequest, logger: logging.Logger = Depends(get_logger)
+):
+    from .. import auth_utils
+
+    key_value = request.key.strip()
+    if not key_value:
+        raise HTTPException(status_code=400, detail="API key cannot be empty.")
+
+    auth_utils.initialize_keys()
+    is_valid = auth_utils.verify_api_key(key_value)
+    logger.info(
+        f"API key test: {key_value[:4]}...{key_value[-4:]} - {'Valid' if is_valid else 'Invalid'}"
+    )
+    return JSONResponse(
+        content={
+            "success": True,
+            "valid": is_valid,
+            "message": "Key valid" if is_valid else "Key invalid or non-existent",
+        }
+    )
+
+
+async def delete_api_key(
+    request: ApiKeyRequest, logger: logging.Logger = Depends(get_logger)
+):
+    from .. import auth_utils
+
+    key_value = request.key.strip()
+    if not key_value:
+        raise HTTPException(status_code=400, detail="API key cannot be empty.")
+
+    auth_utils.initialize_keys()
+    if key_value not in auth_utils.API_KEYS:
+        raise HTTPException(status_code=404, detail="API key does not exist.")
+
+    try:
+        key_file_path = auth_utils.KEY_FILE_PATH
+        with open(key_file_path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+
+        with open(key_file_path, "w", encoding="utf-8") as f:
+            f.writelines(line for line in lines if line.strip() != key_value)
+
+        auth_utils.initialize_keys()
+        logger.info(f"API key deleted: {key_value[:4]}...{key_value[-4:]}")
+        return JSONResponse(
+            content={
+                "success": True,
+                "message": "API key deleted successfully",
+                "key_count": len(auth_utils.API_KEYS),
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to delete API key: {e}")
+        raise HTTPException(status_code=500, detail=str(e))

api_utils/routers/auth_files.py

@@ -0,0 +1,152 @@
+"""
+Authentication Files API Router
+
+Endpoints for managing authentication profile files.
+"""
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from config.settings import ACTIVE_AUTH_DIR, SAVED_AUTH_DIR
+
+router = APIRouter(prefix="/api/auth", tags=["auth"])
+
+
+class AuthFileInfo(BaseModel):
+    """Information about an auth file."""
+
+    name: str
+    path: str
+    size_bytes: int
+    is_active: bool = False
+
+
+class ActivateRequest(BaseModel):
+    """Request to activate an auth file."""
+
+    filename: str = Field(..., description="The name of the auth file to activate")
+
+
+class AuthFilesResponse(BaseModel):
+    """Response containing list of auth files."""
+
+    saved_files: list[AuthFileInfo]
+    active_file: Optional[str] = None
+
+
+def _ensure_dirs() -> None:
+    """Ensure auth directories exist."""
+    Path(ACTIVE_AUTH_DIR).mkdir(parents=True, exist_ok=True)
+    Path(SAVED_AUTH_DIR).mkdir(parents=True, exist_ok=True)
+
+
+def _get_active_file() -> Optional[str]:
+    """Get the currently active auth file name."""
+    active_dir = Path(ACTIVE_AUTH_DIR)
+    if not active_dir.exists():
+        return None
+    json_files = list(active_dir.glob("*.json"))
+    if json_files:
+        return sorted(json_files)[0].name
+    return None
+
+
+def _list_saved_files() -> list[AuthFileInfo]:
+    """List all saved auth files."""
+    saved_dir = Path(SAVED_AUTH_DIR)
+    active_file = _get_active_file()
+    files: list[AuthFileInfo] = []
+
+    if saved_dir.exists():
+        for f in sorted(saved_dir.glob("*.json")):
+            files.append(
+                AuthFileInfo(
+                    name=f.name,
+                    path=str(f),
+                    size_bytes=f.stat().st_size,
+                    is_active=(f.name == active_file),
+                )
+            )
+    return files
+
+
+@router.get("/files")
+async def list_auth_files() -> JSONResponse:
+    """List all saved auth files."""
+    _ensure_dirs()
+    files = _list_saved_files()
+    active = _get_active_file()
+    return JSONResponse(
+        content=AuthFilesResponse(
+            saved_files=files,  # type: ignore[arg-type]
+            active_file=active,
+        ).model_dump()
+    )
+
+
+@router.get("/active")
+async def get_active_auth() -> JSONResponse:
+    """Get the currently active auth file."""
+    _ensure_dirs()
+    active = _get_active_file()
+    return JSONResponse(content={"active_file": active})
+
+
+@router.post("/activate")
+async def activate_auth_file(request: ActivateRequest) -> JSONResponse:
+    """Activate the specified auth file."""
+    _ensure_dirs()
+    filename = request.filename
+
+    # Find source file
+    source_path: Optional[Path] = None
+    for search_dir in [SAVED_AUTH_DIR, ACTIVE_AUTH_DIR]:
+        candidate = Path(search_dir) / filename
+        if candidate.exists() and candidate.is_file():
+            source_path = candidate
+            break
+
+    if not source_path:
+        raise HTTPException(status_code=404, detail=f"Auth file '{filename}' not found")
+
+    # Clear existing active files
+    active_dir = Path(ACTIVE_AUTH_DIR)
+    for existing in active_dir.glob("*.json"):
+        existing.unlink()
+
+    # Copy to active directory
+    dest_path = active_dir / filename
+    shutil.copy2(source_path, dest_path)
+
+    return JSONResponse(
+        content={
+            "success": True,
+            "message": f"Auth file '{filename}' activated",
+            "active_file": filename,
+        }
+    )
+
+
+@router.delete("/deactivate")
+async def deactivate_auth() -> JSONResponse:
+    """Remove the currently active auth."""
+    _ensure_dirs()
+    active_dir = Path(ACTIVE_AUTH_DIR)
+    removed_count = 0
+
+    for f in active_dir.glob("*.json"):
+        f.unlink()
+        removed_count += 1
+
+    return JSONResponse(
+        content={
+            "success": True,
+            "message": f"Removed {removed_count} auth file(s)",
+            "active_file": None,
+        }
+    )

api_utils/routers/chat.py

@@ -0,0 +1,92 @@
+import asyncio
+import logging
+import random
+import time
+from asyncio import Future, Queue
+
+from fastapi import Depends, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+from config import RESPONSE_COMPLETION_TIMEOUT, get_environment_variable
+from logging_utils import set_request_id, set_source
+from models import ChatCompletionRequest
+
+from ..dependencies import (
+    ensure_request_lock,
+    get_logger,
+    get_request_queue,
+    get_server_state,
+    get_worker_task,
+)
+from ..error_utils import service_unavailable
+
+
+async def chat_completions(
+    request: ChatCompletionRequest,
+    http_request: Request,
+    logger: logging.Logger = Depends(get_logger),
+    request_queue: Queue = Depends(get_request_queue),
+    server_state: dict = Depends(get_server_state),
+    worker_task=Depends(get_worker_task),
+    _lock: None = Depends(ensure_request_lock),
+) -> JSONResponse:
+    req_id = "".join(random.choices("abcdefghijklmnopqrstuvwxyz0123456789", k=7))
+
+    # Set log context (Grid Logger)
+    set_request_id(req_id)
+    set_source("API")
+
+    logger.info(f"Received /v1/chat/completions request (Stream={request.stream})")
+
+    launch_mode = get_environment_variable("LAUNCH_MODE", "unknown")
+    browser_page_critical = launch_mode != "direct_debug_no_browser"
+
+    is_service_unavailable = (
+        server_state["is_initializing"]
+        or not server_state["is_playwright_ready"]
+        or (
+            browser_page_critical
+            and (
+                not server_state["is_page_ready"]
+                or not server_state["is_browser_connected"]
+            )
+        )
+        or not worker_task
+        or worker_task.done()
+    )
+
+    if is_service_unavailable:
+        raise service_unavailable(req_id)
+
+    result_future = Future()
+    queue_item = {
+        "req_id": req_id,
+        "request_data": request,
+        "http_request": http_request,
+        "result_future": result_future,
+        "enqueue_time": time.time(),
+        "cancelled": False,
+    }
+    await request_queue.put(queue_item)
+
+    try:
+        timeout_seconds = RESPONSE_COMPLETION_TIMEOUT / 1000 + 120
+        return await asyncio.wait_for(result_future, timeout=timeout_seconds)
+    except asyncio.TimeoutError:
+        raise HTTPException(
+            status_code=504, detail=f"[{req_id}] Request processing timed out."
+        )
+    except asyncio.CancelledError:
+        logger.info(f"Request cancelled by client: {req_id}")
+        raise
+    except HTTPException as http_exc:
+        if http_exc.status_code == 499:
+            logger.info(f"Client disconnected: {http_exc.detail}")
+        else:
+            logger.warning(f"HTTP exception: {http_exc.detail}")
+        raise http_exc
+    except Exception as e:
+        logger.exception("Error waiting for Worker response")
+        raise HTTPException(
+            status_code=500, detail=f"[{req_id}] Internal server error: {e}"
+        )

api_utils/routers/health.py

@@ -0,0 +1,66 @@
+from asyncio import Queue
+from typing import Any, Dict
+
+from fastapi import Depends
+from fastapi.responses import JSONResponse
+
+from config import get_environment_variable
+
+from ..dependencies import get_request_queue, get_server_state, get_worker_task
+
+
+async def health_check(
+    server_state: Dict[str, Any] = Depends(get_server_state),
+    worker_task=Depends(get_worker_task),
+    request_queue: Queue = Depends(get_request_queue),
+) -> JSONResponse:
+    is_worker_running = bool(worker_task and not worker_task.done())
+    launch_mode = get_environment_variable("LAUNCH_MODE", "unknown")
+    browser_page_critical = launch_mode != "direct_debug_no_browser"
+
+    core_ready_conditions = [
+        not server_state["is_initializing"],
+        server_state["is_playwright_ready"],
+    ]
+    if browser_page_critical:
+        core_ready_conditions.extend(
+            [server_state["is_browser_connected"], server_state["is_page_ready"]]
+        )
+
+    is_core_ready = all(core_ready_conditions)
+    status_val = "OK" if is_core_ready and is_worker_running else "Error"
+    q_size = request_queue.qsize() if request_queue else -1
+
+    status_message_parts = []
+    if server_state["is_initializing"]:
+        status_message_parts.append("Initialization in progress")
+    if not server_state["is_playwright_ready"]:
+        status_message_parts.append("Playwright not ready")
+    if browser_page_critical:
+        if not server_state["is_browser_connected"]:
+            status_message_parts.append("Browser not connected")
+        if not server_state["is_page_ready"]:
+            status_message_parts.append("Page not ready")
+    if not is_worker_running:
+        status_message_parts.append("Worker not running")
+
+    status = {
+        "status": status_val,
+        "message": "",
+        "details": {
+            **server_state,
+            "workerRunning": is_worker_running,
+            "queueLength": q_size,
+            "launchMode": launch_mode,
+            "browserAndPageCritical": browser_page_critical,
+        },
+    }
+
+    if status_val == "OK":
+        status["message"] = f"Service running; Queue length: {q_size}."
+        return JSONResponse(content=status, status_code=200)
+    else:
+        status["message"] = (
+            f"Service unavailable; Issue: {(', '.join(status_message_parts) or 'Unknown reason')}. Queue length: {q_size}."
+        )
+        return JSONResponse(content=status, status_code=503)

api_utils/routers/helper.py

@@ -0,0 +1,79 @@
+"""
+Helper Configuration API Router
+
+Manages the Helper endpoint configuration.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger("CamoufoxLauncher")
+
+router = APIRouter(prefix="/api/helper", tags=["helper"])
+
+# Config file path
+_CONFIG_DIR = Path(__file__).parent.parent.parent / "config"
+_HELPER_CONFIG_FILE = _CONFIG_DIR / "helper_config.json"
+
+
+class HelperConfig(BaseModel):
+    """Helper configuration."""
+
+    enabled: bool = False
+    endpoint: str = Field(default="", description="Helper endpoint URL")
+    sapisid: Optional[str] = Field(
+        default=None, description="SAPISID value (auto-extracted)"
+    )
+
+
+def _load_config() -> HelperConfig:
+    """Load helper configuration from file."""
+    if _HELPER_CONFIG_FILE.exists():
+        try:
+            data = json.loads(_HELPER_CONFIG_FILE.read_text(encoding="utf-8"))
+            return HelperConfig(**data)
+        except Exception as e:
+            logger.warning(f"[Helper] Failed to load config: {e}")
+    return HelperConfig()
+
+
+def _save_config(config: HelperConfig) -> None:
+    """Save helper configuration to file."""
+    try:
+        _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        _HELPER_CONFIG_FILE.write_text(
+            json.dumps(config.model_dump(), indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+    except Exception as e:
+        logger.error(f"[Helper] Failed to save config: {e}")
+
+
+@router.get("/config")
+async def get_helper_config() -> JSONResponse:
+    """Get Helper configuration."""
+    config = _load_config()
+    return JSONResponse(content=config.model_dump())
+
+
+@router.post("/config")
+async def update_helper_config(config: HelperConfig) -> JSONResponse:
+    """Update Helper configuration."""
+    _save_config(config)
+    logger.info(
+        f"[Helper] Config updated: enabled={config.enabled}, endpoint={config.endpoint}"
+    )
+
+    return JSONResponse(
+        content={
+            "success": True,
+            "message": "Helper configuration saved",
+            "config": config.model_dump(),
+        }
+    )

api_utils/routers/info.py

@@ -0,0 +1,49 @@
+from fastapi import Depends, Request
+from fastapi.responses import JSONResponse
+
+from config import MODEL_NAME, get_environment_variable
+
+from ..dependencies import get_current_ai_studio_model_id
+
+
+async def get_api_info(
+    request: Request,
+    current_ai_studio_model_id: str = Depends(get_current_ai_studio_model_id),
+) -> JSONResponse:
+    from .. import auth_utils
+
+    server_port = request.url.port or get_environment_variable(
+        "SERVER_PORT_INFO", "8000"
+    )
+    host = request.headers.get("host") or f"127.0.0.1:{server_port}"
+    scheme = request.headers.get("x-forwarded-proto") or request.url.scheme or "http"
+    base_url = f"{scheme}://{host}"
+    api_base = f"{base_url}/v1"
+    effective_model_name = current_ai_studio_model_id or MODEL_NAME
+
+    api_key_required = bool(auth_utils.API_KEYS)
+    api_key_count = len(auth_utils.API_KEYS)
+
+    message = (
+        f"API Key is required. {api_key_count} valid key(s) configured."
+        if api_key_required
+        else "API Key is not required."
+    )
+
+    return JSONResponse(
+        content={
+            "model_name": effective_model_name,
+            "api_base_url": api_base,
+            "server_base_url": base_url,
+            "api_key_required": api_key_required,
+            "api_key_count": api_key_count,
+            "auth_header": "Authorization: Bearer <token> or X-API-Key: <token>"
+            if api_key_required
+            else None,
+            "openai_compatible": True,
+            "supported_auth_methods": ["Authorization: Bearer", "X-API-Key"]
+            if api_key_required
+            else [],
+            "message": message,
+        }
+    )

api_utils/routers/logs_ws.py

@@ -0,0 +1,36 @@
+import asyncio
+import logging
+import uuid
+
+from fastapi import Depends, WebSocket, WebSocketDisconnect
+
+from models import WebSocketConnectionManager
+
+from ..dependencies import get_log_ws_manager, get_logger
+
+
+async def websocket_log_endpoint(
+    websocket: WebSocket,
+    logger: logging.Logger = Depends(get_logger),
+    log_ws_manager: WebSocketConnectionManager = Depends(get_log_ws_manager),
+):
+    if not log_ws_manager:
+        await websocket.close(code=1011)
+        return
+
+    client_id = str(uuid.uuid4())
+    try:
+        await log_ws_manager.connect(client_id, websocket)
+        while True:
+            await websocket.receive_text()
+    except WebSocketDisconnect:
+        pass
+    except asyncio.CancelledError:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Log WebSocket (client {client_id}) encountered an exception: {e}",
+            exc_info=True,
+        )
+    finally:
+        log_ws_manager.disconnect(client_id)

api_utils/routers/model_capabilities.py

@@ -0,0 +1,104 @@
+"""
+Model Capabilities API Endpoint
+
+SINGLE SOURCE OF TRUTH for model thinking capabilities.
+Frontend fetches this to determine UI controls dynamically.
+
+Configuration is loaded from config/model_capabilities.json.
+When new models are released, update the JSON file - no code changes needed.
+"""
+
+import json
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+router = APIRouter()
+
+# Config file path
+_CONFIG_PATH = (
+    Path(__file__).parent.parent.parent / "config" / "model_capabilities.json"
+)
+
+
+@lru_cache(maxsize=1)
+def _load_config() -> dict[str, Any]:
+    """
+    Load model capabilities configuration from JSON file.
+
+    Uses LRU cache to avoid repeated file reads.
+    Raises FileNotFoundError if config is missing.
+    """
+    if not _CONFIG_PATH.exists():
+        raise FileNotFoundError(f"Model capabilities config not found: {_CONFIG_PATH}")
+
+    with open(_CONFIG_PATH, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def reload_config() -> None:
+    """Clear the config cache, forcing a reload on next access."""
+    _load_config.cache_clear()
+
+
+def _get_model_capabilities(model_id: str) -> dict[str, Any]:
+    """
+    Determine thinking capabilities for a model.
+
+    Returns dict with:
+    - thinkingType: "level" | "budget" | "none"
+    - levels: List of thinking levels (for type="level")
+    - alwaysOn: Whether thinking is always on (for Gemini 2.5 Pro)
+    - budgetRange: [min, max] for budget slider
+    - supportsGoogleSearch: Whether the model supports Google Search
+    """
+    config = _load_config()
+    categories = config.get("categories", {})
+    matchers = config.get("matchers", [])
+
+    model_lower = model_id.lower()
+
+    # Try each matcher in order (order matters: more specific first)
+    for matcher in matchers:
+        pattern = matcher.get("pattern", "")
+        category_name = matcher.get("category", "")
+
+        if pattern and category_name:
+            try:
+                if re.search(pattern, model_lower, re.IGNORECASE):
+                    if category_name in categories:
+                        return categories[category_name].copy()
+            except re.error:
+                # Invalid regex pattern, skip
+                continue
+
+    # Default to "other" category
+    return categories.get(
+        "other", {"thinkingType": "none", "supportsGoogleSearch": True}
+    )
+
+
+@router.get("/api/model-capabilities")
+async def get_model_capabilities() -> JSONResponse:
+    """
+    Return thinking capabilities for all known model categories.
+
+    Frontend uses this to dynamically configure thinking controls.
+    """
+    config = _load_config()
+    return JSONResponse(content=config)
+
+
+@router.get("/api/model-capabilities/{model_id:path}")
+async def get_single_model_capabilities(model_id: str) -> JSONResponse:
+    """
+    Return thinking capabilities for a specific model.
+
+    Args:
+        model_id: Model identifier (e.g., "gemini-2.5-flash-preview")
+    """
+    return JSONResponse(content=_get_model_capabilities(model_id))

api_utils/routers/models.py

@@ -0,0 +1,70 @@
+import asyncio
+import logging
+import time
+from asyncio import Event
+from typing import Any, Dict, List, Set
+
+from fastapi import Depends
+from playwright.async_api import Page as AsyncPage
+
+from config import DEFAULT_FALLBACK_MODEL_ID
+
+from ..dependencies import (
+    ensure_request_lock,
+    get_excluded_model_ids,
+    get_logger,
+    get_model_list_fetch_event,
+    get_page_instance,
+    get_parsed_model_list,
+)
+
+
+async def list_models(
+    logger: logging.Logger = Depends(get_logger),
+    model_list_fetch_event: Event = Depends(get_model_list_fetch_event),
+    page_instance: AsyncPage = Depends(get_page_instance),
+    parsed_model_list: List[Dict[str, Any]] = Depends(get_parsed_model_list),
+    excluded_model_ids: Set[str] = Depends(get_excluded_model_ids),
+    _lock: None = Depends(ensure_request_lock),
+):
+    logger.debug("[API] Received /v1/models request.")
+
+    if (
+        not model_list_fetch_event.is_set()
+        and page_instance
+        and not page_instance.is_closed()
+    ):
+        logger.info(
+            "/v1/models: Model list event not set, attempting to refresh page..."
+        )
+        try:
+            await page_instance.reload(wait_until="domcontentloaded", timeout=20000)
+            await asyncio.wait_for(model_list_fetch_event.wait(), timeout=10.0)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.error(f"/v1/models: Error refreshing or waiting for model list: {e}")
+        finally:
+            if not model_list_fetch_event.is_set():
+                model_list_fetch_event.set()
+
+    if parsed_model_list:
+        final_model_list = [
+            m
+            for m in parsed_model_list
+            if isinstance(m, dict) and m.get("id") not in excluded_model_ids
+        ]
+        return {"object": "list", "data": final_model_list}
+    else:
+        logger.warning("Model list is empty, returning default fallback model.")
+        return {
+            "object": "list",
+            "data": [
+                {
+                    "id": DEFAULT_FALLBACK_MODEL_ID,
+                    "object": "model",
+                    "created": int(time.time()),
+                    "owned_by": "camoufox-proxy-fallback",
+                }
+            ],
+        }

api_utils/routers/ports.py

@@ -0,0 +1,353 @@
+"""
+Port Configuration and Status API Router
+
+Endpoints for port configuration, status querying, and process management.
+"""
+
+import json
+import os
+import platform
+import subprocess
+import time
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, field_validator
+
+router = APIRouter(prefix="/api/ports", tags=["ports"])
+
+# Config file path
+_CONFIG_DIR = Path(__file__).parent.parent.parent
+_PORTS_CONFIG_FILE = _CONFIG_DIR / "ports_config.json"
+
+
+class PortConfig(BaseModel):
+    """Port configuration model."""
+
+    fastapi_port: int = Field(default=2048, ge=1024, le=65535)
+    camoufox_debug_port: int = Field(default=9222, ge=1024, le=65535)
+    stream_proxy_port: int = Field(default=3120, ge=0, le=65535)
+    stream_proxy_enabled: bool = True
+
+    @field_validator("fastapi_port", "camoufox_debug_port")
+    @classmethod
+    def validate_required_port(cls, v: int) -> int:
+        if v < 1024:
+            raise ValueError("Port must be >= 1024")
+        return v
+
+
+class ProcessInfo(BaseModel):
+    """Information about a process."""
+
+    pid: int
+    name: str
+
+
+class PortStatus(BaseModel):
+    """Status of a port."""
+
+    port: int
+    port_type: str
+    in_use: bool
+    processes: list[ProcessInfo] = []
+
+
+class KillRequest(BaseModel):
+    """Request to kill a process."""
+
+    pid: int = Field(..., ge=1, description="PID of the process to terminate")
+    confirm: bool = Field(default=False, description="Confirm termination")
+
+
+def _load_port_config() -> PortConfig:
+    """Load port config from file or environment."""
+    # Environment variables take priority
+    config = PortConfig(
+        fastapi_port=int(os.environ.get("DEFAULT_FASTAPI_PORT", "2048")),
+        camoufox_debug_port=int(os.environ.get("DEFAULT_CAMOUFOX_PORT", "9222")),
+        stream_proxy_port=int(os.environ.get("STREAM_PORT", "3120")),
+        stream_proxy_enabled=os.environ.get("STREAM_PORT", "3120") != "0",
+    )
+
+    # Override with saved config if exists
+    if _PORTS_CONFIG_FILE.exists():
+        try:
+            data = json.loads(_PORTS_CONFIG_FILE.read_text(encoding="utf-8"))
+            config = PortConfig(**data)
+        except Exception:
+            pass
+
+    return config
+
+
+def _save_port_config(config: PortConfig) -> None:
+    """Save port config to file."""
+    _PORTS_CONFIG_FILE.write_text(
+        json.dumps(config.model_dump(), ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def _find_processes_on_port(port: int) -> list[ProcessInfo]:
+    """Find processes listening on a port."""
+    processes: list[ProcessInfo] = []
+    system = platform.system()
+
+    try:
+        if system in ("Linux", "Darwin"):
+            cmd = f"lsof -ti tcp:{port} -sTCP:LISTEN"
+            result = subprocess.run(
+                cmd, shell=True, capture_output=True, text=True, timeout=5
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                pids = [
+                    int(p) for p in result.stdout.strip().splitlines() if p.isdigit()
+                ]
+                for pid in pids:
+                    name = _get_process_name(pid)
+                    processes.append(ProcessInfo(pid=pid, name=name))
+
+        elif system == "Windows":
+            cmd = "netstat -ano -p TCP"
+            result = subprocess.run(
+                cmd,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=10,
+                creationflags=subprocess.CREATE_NO_WINDOW,  # type: ignore[attr-defined]
+            )
+            if result.returncode == 0:
+                for line in result.stdout.strip().splitlines():
+                    parts = line.split()
+                    if (
+                        len(parts) >= 5
+                        and parts[0].upper() == "TCP"
+                        and parts[3].upper() == "LISTENING"
+                    ):
+                        local_addr = parts[1]
+                        if local_addr.endswith(f":{port}"):
+                            pid_str = parts[4]
+                            if pid_str.isdigit():
+                                pid = int(pid_str)
+                                name = _get_process_name(pid)
+                                processes.append(ProcessInfo(pid=pid, name=name))
+
+    except Exception:
+        pass
+
+    # Deduplicate by PID
+    seen_pids: set[int] = set()
+    unique_processes: list[ProcessInfo] = []
+    for p in processes:
+        if p.pid not in seen_pids:
+            seen_pids.add(p.pid)
+            unique_processes.append(p)
+
+    return unique_processes
+
+
+def _get_process_name(pid: int) -> str:
+    """Get process name by PID."""
+    system = platform.system()
+
+    try:
+        if system == "Linux":
+            result = subprocess.run(
+                ["ps", "-p", str(pid), "-o", "comm="],
+                capture_output=True,
+                text=True,
+                timeout=3,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+
+        elif system == "Darwin":
+            result = subprocess.run(
+                ["ps", "-p", str(pid), "-o", "comm="],
+                capture_output=True,
+                text=True,
+                timeout=3,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+
+        elif system == "Windows":
+            result = subprocess.run(
+                ["tasklist", "/NH", "/FO", "CSV", "/FI", f"PID eq {pid}"],
+                capture_output=True,
+                text=True,
+                timeout=3,
+                creationflags=subprocess.CREATE_NO_WINDOW,  # type: ignore[attr-defined]
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                parts = result.stdout.strip().split('","')
+                if parts:
+                    return parts[0].strip('"')
+
+    except Exception:
+        pass
+
+    return "Unknown"
+
+
+def _kill_process(pid: int) -> tuple[bool, str]:
+    """Kill a process by PID. Returns (success, message)."""
+    system = platform.system()
+
+    try:
+        if system in ("Linux", "Darwin"):
+            # Try SIGTERM first
+            subprocess.run(["kill", "-TERM", str(pid)], capture_output=True, timeout=3)
+            time.sleep(0.5)
+
+            # Check if still alive
+            check = subprocess.run(
+                ["kill", "-0", str(pid)], capture_output=True, text=True
+            )
+            if check.returncode != 0:
+                return True, f"Process {pid} terminated (SIGTERM)"
+
+            # Force kill
+            subprocess.run(["kill", "-KILL", str(pid)], capture_output=True, timeout=3)
+            time.sleep(0.2)
+
+            # Verify
+            check = subprocess.run(
+                ["kill", "-0", str(pid)], capture_output=True, text=True
+            )
+            if check.returncode != 0:
+                return True, f"Process {pid} force terminated (SIGKILL)"
+            else:
+                return False, f"Unable to terminate process {pid}"
+
+        elif system == "Windows":
+            result = subprocess.run(
+                ["taskkill", "/PID", str(pid), "/T", "/F"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                creationflags=subprocess.CREATE_NO_WINDOW,  # type: ignore[attr-defined]
+            )
+            if result.returncode == 0:
+                return True, f"Process {pid} terminated"
+            else:
+                return False, f"Unable to terminate process {pid}: {result.stderr}"
+
+    except Exception as e:
+        return False, f"Error terminating process: {e}"
+
+    return False, "Unsupported OS"
+
+
+@router.get("/config")
+async def get_port_config() -> JSONResponse:
+    """Get port configuration."""
+    config = _load_port_config()
+    return JSONResponse(content=config.model_dump())
+
+
+@router.post("/config")
+async def update_port_config(config: PortConfig) -> JSONResponse:
+    """
+    Update port configuration.
+
+    Note: Changes will take effect on next server restart.
+    """
+    _save_port_config(config)
+    return JSONResponse(
+        content={
+            "success": True,
+            "config": config.model_dump(),
+            "message": "Configuration saved. Changes will take effect on next restart.",
+        }
+    )
+
+
+@router.get("/status")
+async def get_port_status() -> JSONResponse:
+    """Get port occupation status."""
+    config = _load_port_config()
+
+    statuses: list[PortStatus] = []
+
+    # Check FastAPI port
+    fastapi_processes = _find_processes_on_port(config.fastapi_port)
+    statuses.append(
+        PortStatus(
+            port=config.fastapi_port,
+            port_type="FastAPI",
+            in_use=len(fastapi_processes) > 0,
+            processes=fastapi_processes,
+        )
+    )
+
+    # Check Camoufox debug port
+    camoufox_processes = _find_processes_on_port(config.camoufox_debug_port)
+    statuses.append(
+        PortStatus(
+            port=config.camoufox_debug_port,
+            port_type="Camoufox Debug",
+            in_use=len(camoufox_processes) > 0,
+            processes=camoufox_processes,
+        )
+    )
+
+    # Check Stream proxy port (if enabled)
+    if config.stream_proxy_enabled and config.stream_proxy_port > 0:
+        stream_processes = _find_processes_on_port(config.stream_proxy_port)
+        statuses.append(
+            PortStatus(
+                port=config.stream_proxy_port,
+                port_type="Stream Proxy",
+                in_use=len(stream_processes) > 0,
+                processes=stream_processes,
+            )
+        )
+
+    return JSONResponse(content={"ports": [s.model_dump() for s in statuses]})
+
+
+@router.post("/kill")
+async def kill_process(request: KillRequest) -> JSONResponse:
+    """
+    Terminate process with specified PID.
+
+    Security validation:
+    - Requires confirm=true
+    - PID must belong to a process on a configured port
+    """
+    if not request.confirm:
+        raise HTTPException(
+            status_code=400,
+            detail="Please set confirm=true to confirm process termination",
+        )
+
+    # Security: Validate PID belongs to a tracked port
+    config = _load_port_config()
+    tracked_pids: set[int] = set()
+
+    # Collect PIDs from all configured ports
+    for port in [config.fastapi_port, config.camoufox_debug_port]:
+        for proc in _find_processes_on_port(port):
+            tracked_pids.add(proc.pid)
+
+    # Also check stream proxy port if enabled
+    if config.stream_proxy_enabled and config.stream_proxy_port > 0:
+        for proc in _find_processes_on_port(config.stream_proxy_port):
+            tracked_pids.add(proc.pid)
+
+    if request.pid not in tracked_pids:
+        raise HTTPException(
+            status_code=403,
+            detail=f"Security validation failed: PID {request.pid} does not belong to a configured port. Only processes running on FastAPI ({config.fastapi_port}), Camoufox ({config.camoufox_debug_port}) or Stream Proxy ({config.stream_proxy_port}) ports can be terminated.",
+        )
+
+    success, message = _kill_process(request.pid)
+
+    return JSONResponse(
+        content={"success": success, "message": message, "pid": request.pid},
+        status_code=200 if success else 500,
+    )

api_utils/routers/proxy.py

@@ -0,0 +1,163 @@
+"""
+Proxy Configuration API Router
+
+Endpoints for managing browser proxy settings and testing connectivity.
+"""
+
+import socket
+import time
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, field_validator
+
+router = APIRouter(prefix="/api/proxy", tags=["proxy"])
+
+# Config file path
+_CONFIG_DIR = Path(__file__).parent.parent.parent
+_PROXY_CONFIG_FILE = _CONFIG_DIR / "proxy_config.json"
+
+
+class ProxyConfig(BaseModel):
+    """Proxy configuration model."""
+
+    enabled: bool = False
+    address: str = "http://127.0.0.1:7890"
+
+    @field_validator("address")
+    @classmethod
+    def validate_address(cls, v: str) -> str:
+        """Validate proxy address format."""
+        v = v.strip()
+        if v and not (v.startswith("http://") or v.startswith("https://")):
+            raise ValueError("Proxy address must start with http:// or https://")
+        return v
+
+
+class ProxyTestRequest(BaseModel):
+    """Request model for proxy test."""
+
+    address: str = Field(..., description="Proxy address")
+    test_url: str = Field(
+        default="http://httpbin.org/get", description="Test target URL"
+    )
+
+
+class ProxyTestResult(BaseModel):
+    """Result of proxy connectivity test."""
+
+    success: bool
+    message: str
+    latency_ms: Optional[float] = None
+
+
+def _load_config() -> ProxyConfig:
+    """Load proxy config from file."""
+    import json
+
+    if _PROXY_CONFIG_FILE.exists():
+        try:
+            data = json.loads(_PROXY_CONFIG_FILE.read_text(encoding="utf-8"))
+            return ProxyConfig(**data)
+        except Exception:
+            pass
+    return ProxyConfig()
+
+
+def _save_config(config: ProxyConfig) -> None:
+    """Save proxy config to file."""
+    import json
+
+    _PROXY_CONFIG_FILE.write_text(
+        json.dumps(config.model_dump(), ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+@router.get("/config")
+async def get_proxy_config() -> JSONResponse:
+    """Get current proxy configuration."""
+    config = _load_config()
+    return JSONResponse(content=config.model_dump())
+
+
+@router.post("/config")
+async def update_proxy_config(config: ProxyConfig) -> JSONResponse:
+    """Update proxy configuration."""
+    _save_config(config)
+    return JSONResponse(content={"success": True, "config": config.model_dump()})
+
+
+@router.post("/test")
+async def test_proxy_connectivity(request: ProxyTestRequest) -> JSONResponse:
+    """Test proxy connectivity."""
+    import httpx
+
+    proxy_addr = request.address.strip()
+    test_url = request.test_url
+
+    if not proxy_addr:
+        return JSONResponse(
+            content=ProxyTestResult(
+                success=False, message="Proxy address cannot be empty"
+            ).model_dump(),
+            status_code=400,
+        )
+
+    try:
+        start_time = time.monotonic()
+        async with httpx.AsyncClient(
+            proxy=proxy_addr,
+            timeout=15.0,
+            follow_redirects=True,
+        ) as client:
+            response = await client.get(test_url)
+            latency = (time.monotonic() - start_time) * 1000
+
+            if 200 <= response.status_code < 300:
+                return JSONResponse(
+                    content=ProxyTestResult(
+                        success=True,
+                        message=f"Connection successful (HTTP {response.status_code})",
+                        latency_ms=round(latency, 2),
+                    ).model_dump()
+                )
+            else:
+                return JSONResponse(
+                    content=ProxyTestResult(
+                        success=False,
+                        message=f"HTTP Error: {response.status_code}",
+                        latency_ms=round(latency, 2),
+                    ).model_dump()
+                )
+
+    except httpx.ProxyError as e:
+        return JSONResponse(
+            content=ProxyTestResult(
+                success=False, message=f"Proxy error: {e}"
+            ).model_dump()
+        )
+    except httpx.ConnectTimeout:
+        return JSONResponse(
+            content=ProxyTestResult(
+                success=False, message="Connection timeout"
+            ).model_dump()
+        )
+    except httpx.ReadTimeout:
+        return JSONResponse(
+            content=ProxyTestResult(success=False, message="Read timeout").model_dump()
+        )
+    except socket.gaierror as e:
+        return JSONResponse(
+            content=ProxyTestResult(
+                success=False, message=f"DNS resolution failed: {e}"
+            ).model_dump()
+        )
+    except Exception as e:
+        return JSONResponse(
+            content=ProxyTestResult(
+                success=False, message=f"Unknown error: {e}"
+            ).model_dump()
+        )

api_utils/routers/queue.py

@@ -0,0 +1,99 @@
+import logging
+import time
+from asyncio import Lock, Queue
+
+from fastapi import Depends
+from fastapi.responses import JSONResponse
+
+from logging_utils import set_request_id
+
+from ..dependencies import get_logger, get_processing_lock, get_request_queue
+from ..error_utils import client_cancelled
+
+
+async def cancel_queued_request(
+    req_id: str, request_queue: Queue, logger: logging.Logger
+) -> bool:
+    set_request_id(req_id)
+    items_to_requeue = []
+    found = False
+    try:
+        while not request_queue.empty():
+            item = request_queue.get_nowait()
+            if item.get("req_id") == req_id:
+                logger.info("Found request in queue, marking as cancelled.")
+                item["cancelled"] = True
+                if (future := item.get("result_future")) and not future.done():
+                    future.set_exception(client_cancelled(req_id))
+                found = True
+            items_to_requeue.append(item)
+    finally:
+        for item in items_to_requeue:
+            await request_queue.put(item)
+    return found
+
+
+async def cancel_request(
+    req_id: str,
+    logger: logging.Logger = Depends(get_logger),
+    request_queue: Queue = Depends(get_request_queue),
+):
+    set_request_id(req_id)
+    logger.info("Received cancellation request.")
+    if await cancel_queued_request(req_id, request_queue, logger):
+        return JSONResponse(
+            content={
+                "success": True,
+                "message": f"Request {req_id} marked as cancelled.",
+            }
+        )
+    else:
+        return JSONResponse(
+            status_code=404,
+            content={
+                "success": False,
+                "message": f"Request {req_id} not found in queue.",
+            },
+        )
+
+
+async def get_queue_status(
+    request_queue: Queue = Depends(get_request_queue),
+    processing_lock: Lock = Depends(get_processing_lock),
+):
+    # Extract all items temporarily to inspect queue contents
+    queue_items = []
+    try:
+        while not request_queue.empty():
+            item = request_queue.get_nowait()
+            queue_items.append(item)
+    except Exception:
+        pass
+    finally:
+        # Put all items back in original order
+        for item in queue_items:
+            await request_queue.put(item)
+
+    queue_length = len(queue_items)
+
+    return JSONResponse(
+        content={
+            "queue_length": queue_length,
+            "is_processing_locked": processing_lock.locked(),
+            "items": sorted(
+                [
+                    {
+                        "req_id": item.get("req_id", "unknown"),
+                        "enqueue_time": item.get("enqueue_time", 0),
+                        "wait_time_seconds": round(
+                            time.time() - item.get("enqueue_time", 0), 2
+                        ),
+                        "is_streaming": item.get("request_data").stream,
+                        "cancelled": item.get("cancelled", False),
+                    }
+                    for item in queue_items
+                ],
+                key=lambda x: x.get("enqueue_time", 0),
+            ),
+        }
+    )

api_utils/routers/server.py

@@ -0,0 +1,140 @@
+"""
+Server Control API Router
+
+Provides endpoints for server status and control operations.
+"""
+
+import logging
+import os
+import time
+from datetime import datetime
+from typing import Optional
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from ..app import VERSION
+
+logger = logging.getLogger("CamoufoxLauncher")
+
+router = APIRouter(prefix="/api/server", tags=["server"])
+
+# Track server start time
+_SERVER_START_TIME: Optional[float] = None
+
+
+def _init_start_time() -> None:
+    """Initialize server start time (called once at startup)."""
+    global _SERVER_START_TIME
+    if _SERVER_START_TIME is None:
+        _SERVER_START_TIME = time.time()
+
+
+_init_start_time()
+
+
+class ServerStatus(BaseModel):
+    """Server status information."""
+
+    status: str
+    uptime_seconds: float
+    uptime_formatted: str
+    launch_mode: str
+    server_port: int
+    stream_port: int
+    version: str
+    python_version: str
+    started_at: str
+
+
+class RestartRequest(BaseModel):
+    """Restart request with mode."""
+
+    mode: str = "headless"  # headless, debug, virtual_display
+    confirm: bool = False
+
+
+def _format_uptime(seconds: float) -> str:
+    """Format uptime in human-readable format."""
+    days = int(seconds // 86400)
+    hours = int((seconds % 86400) // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = int(seconds % 60)
+
+    parts = []
+    if days > 0:
+        parts.append(f"{days}d")
+    if hours > 0:
+        parts.append(f"{hours}h")
+    if minutes > 0:
+        parts.append(f"{minutes}m")
+    parts.append(f"{secs}s")
+
+    return " ".join(parts)
+
+
+@router.get("/status")
+async def get_server_status() -> JSONResponse:
+    """Get server status information."""
+    import sys
+
+    uptime = time.time() - (_SERVER_START_TIME or time.time())
+    started_at = datetime.fromtimestamp(_SERVER_START_TIME or time.time())
+
+    status = ServerStatus(
+        status="running",
+        uptime_seconds=round(uptime, 2),
+        uptime_formatted=_format_uptime(uptime),
+        launch_mode=os.environ.get("LAUNCH_MODE", "unknown"),
+        server_port=int(
+            os.environ.get("SERVER_PORT_INFO", os.environ.get("PORT", 2048))
+        ),
+        stream_port=int(os.environ.get("STREAM_PORT", 3120)),
+        version=VERSION,
+        python_version=f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+        started_at=started_at.isoformat(),
+    )
+
+    return JSONResponse(content=status.model_dump())
+
+
+@router.post("/restart")
+async def restart_server(request: RestartRequest) -> JSONResponse:
+    """
+    Request server restart.
+
+    Note: This operation terminates the current process and requires an external process manager to restart.
+    """
+    if not request.confirm:
+        return JSONResponse(
+            content={
+                "success": False,
+                "message": "Restart operation requires confirmation. Please set confirm=true",
+            },
+            status_code=400,
+        )
+
+    valid_modes = ["headless", "debug", "virtual_display"]
+    if request.mode not in valid_modes:
+        return JSONResponse(
+            content={
+                "success": False,
+                "message": f"Invalid launch mode. Valid options: {valid_modes}",
+            },
+            status_code=400,
+        )
+
+    logger.info(f"[Server] Received restart request, target mode: {request.mode}")
+
+    # Set environment variable for next launch
+    os.environ["REQUESTED_RESTART_MODE"] = request.mode
+
+    # Return success - actual restart needs to be handled by process manager
+    return JSONResponse(
+        content={
+            "success": True,
+            "message": f"Server will restart in {request.mode} mode. Please refresh the page.",
+            "mode": request.mode,
+        }
+    )

api_utils/routers/static.py

@@ -0,0 +1,96 @@
+"""
+Static files serving routes
+Uses FastAPI/Starlette native static files service
+
+Optimization points:
+- Use StaticFiles for high-performance static file serving
+- Automatic handling of cache headers, byte-range requests, directory traversal protection
+- SPA routing uses catch-all to return only index.html
+"""
+
+import logging
+from pathlib import Path
+
+from fastapi import Depends, HTTPException
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from ..dependencies import get_logger
+
+_BASE_DIR = Path(__file__).parent.parent.parent
+
+# React build directory
+_REACT_DIST = _BASE_DIR / "static" / "frontend" / "dist"
+_REACT_ASSETS = _REACT_DIST / "assets"
+
+
+def get_static_files_app() -> StaticFiles | None:
+    """
+    Create a StaticFiles app for the assets directory.
+
+    Returns None if the directory doesn't exist (frontend not built).
+    """
+    if _REACT_ASSETS.exists():
+        return StaticFiles(directory=str(_REACT_ASSETS))
+    return None
+
+
+async def read_index(logger: logging.Logger = Depends(get_logger)) -> FileResponse:
+    """Serve React index.html for SPA routing."""
+    react_index = _REACT_DIST / "index.html"
+    if react_index.exists():
+        return FileResponse(react_index, media_type="text/html")
+
+    logger.error("React build not found - run 'npm run build' in static/frontend/")
+    raise HTTPException(
+        status_code=503,
+        detail="Frontend not built. Run 'npm run build' in static/frontend/",
+    )
+
+
+async def serve_react_assets(
+    filename: str, logger: logging.Logger = Depends(get_logger)
+) -> FileResponse:
+    """
+    Serve React built assets (JS, CSS, etc.).
+
+    Note: For production deployments, consider mounting StaticFiles directly
+    in the app configuration for better performance:
+
+        from fastapi.staticfiles import StaticFiles
+        app.mount("/assets", StaticFiles(directory="static/frontend/dist/assets"))
+
+    This fallback route is provided for flexibility and development convenience.
+    """
+    asset_path = _REACT_ASSETS / filename
+
+    if not asset_path.exists():
+        logger.debug(f"Asset not found: {asset_path}")
+        raise HTTPException(status_code=404, detail=f"Asset {filename} not found")
+
+    # Security: Prevent directory traversal
+    try:
+        asset_path.resolve().relative_to(_REACT_ASSETS.resolve())
+    except ValueError:
+        logger.warning(f"Directory traversal attempt blocked: {filename}")
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    # Determine media type based on suffix
+    suffix_to_media_type = {
+        ".js": "application/javascript",
+        ".css": "text/css",
+        ".map": "application/json",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".ico": "image/x-icon",
+        ".woff": "font/woff",
+        ".woff2": "font/woff2",
+        ".ttf": "font/ttf",
+        ".eot": "application/vnd.ms-fontobject",
+    }
+    media_type = suffix_to_media_type.get(asset_path.suffix.lower())
+
+    return FileResponse(asset_path, media_type=media_type)

api_utils/server_state.py

@@ -0,0 +1,126 @@
+"""
+Centralized server state module.
+
+This module contains all shared state variables that were previously in server.py.
+It has NO imports from project modules (only stdlib), making it safe to import
+at module level anywhere in the codebase without circular dependency issues.
+
+Usage:
+    from api_utils.server_state import state
+    # Access state attributes
+    page = state.page_instance
+    state.current_ai_studio_model_id = "new-model"
+"""
+
+import asyncio
+import logging
+import multiprocessing
+from asyncio import Event, Lock, Queue, Task
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Set
+
+if TYPE_CHECKING:
+    from playwright.async_api import (
+        Browser as AsyncBrowser,
+    )
+    from playwright.async_api import (
+        Page as AsyncPage,
+    )
+    from playwright.async_api import (
+        Playwright as AsyncPlaywright,
+    )
+
+    from api_utils.context_types import QueueItem
+    from models.logging import WebSocketConnectionManager
+
+
+class ServerState:
+    """
+    Centralized container for all server state.
+
+    This class holds all mutable state that needs to be shared across modules.
+    Using a class allows for better organization and easier testing (state can be reset).
+    """
+
+    def __init__(self) -> None:
+        """Initialize all state variables with default values."""
+        self.reset()
+
+    def reset(self) -> None:
+        """Reset all state to initial values. Useful for testing."""
+        # --- Stream Queue ---
+        self.STREAM_QUEUE: Optional[multiprocessing.Queue] = None
+        self.STREAM_PROCESS: Optional[multiprocessing.Process] = None
+
+        # --- Playwright/Browser State ---
+        self.playwright_manager: Optional["AsyncPlaywright"] = None
+        self.browser_instance: Optional["AsyncBrowser"] = None
+        self.page_instance: Optional["AsyncPage"] = None
+        self.is_playwright_ready: bool = False
+        self.is_browser_connected: bool = False
+        self.is_page_ready: bool = False
+        self.is_initializing: bool = False
+
+        # --- Proxy Configuration ---
+        self.PLAYWRIGHT_PROXY_SETTINGS: Optional[Dict[str, str]] = None
+
+        # --- Model State ---
+        self.global_model_list_raw_json: Optional[str] = None
+        self.parsed_model_list: List[Dict[str, Any]] = []
+        self.model_list_fetch_event: Event = asyncio.Event()
+        self.current_ai_studio_model_id: Optional[str] = None
+        self.current_auth_profile_path: Optional[str] = None
+        self.model_switching_lock: Lock = Lock()
+        self.excluded_model_ids: Set[str] = set()
+
+        # --- Request Processing State ---
+        self.request_queue: "Optional[Queue[QueueItem]]" = None
+        self.processing_lock: Optional[Lock] = None
+        self.worker_task: "Optional[Task[None]]" = None
+
+        # --- Parameter Cache ---
+        self.page_params_cache: Dict[str, Any] = {}
+        self.params_cache_lock: Lock = Lock()
+
+        # --- Debug Logging State ---
+        self.console_logs: List[Dict[str, Any]] = []
+        self.network_log: Dict[str, List[Dict[str, Any]]] = {
+            "requests": [],
+            "responses": [],
+        }
+
+        # --- Logging ---
+        self.logger: logging.Logger = logging.getLogger("AIStudioProxyServer")
+        self.log_ws_manager: Optional["WebSocketConnectionManager"] = None
+
+        # --- Control Flags ---
+        self.should_exit: bool = False
+        self.quota_watchdog: Optional[Callable] = None
+
+    def clear_debug_logs(self) -> None:
+        """Clear console and network logs (called after each request)."""
+        self.console_logs = []
+        self.network_log = {"requests": [], "responses": []}
+
+
+# Global singleton instance
+state = ServerState()
+
+
+# Convenience exports for backward compatibility
+# These allow direct attribute access like: from server_state import page_instance
+# But the recommended way is: from api_utils.server_state import state; state.page_instance
+
+
+def __getattr__(name: str) -> Any:
+    """
+    Module-level attribute access for backward compatibility.
+
+    Allows:
+        from server_state import page_instance
+    Instead of:
+        from api_utils.server_state import state
+        page_instance = state.page_instance
+    """
+    if hasattr(state, name):
+        return getattr(state, name)
+    raise AttributeError(f"module 'server_state' has no attribute '{name}'")

api_utils/sse.py

@@ -0,0 +1,41 @@
+import json
+import time
+from typing import Any, Dict, Optional
+
+
+def generate_sse_chunk(delta: str, req_id: str, model: str) -> str:
+    chunk_data: Dict[str, Any] = {
+        "id": f"chatcmpl-{req_id}",
+        "object": "chat.completion.chunk",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [{"index": 0, "delta": {"content": delta}, "finish_reason": None}],
+    }
+    return f"data: {json.dumps(chunk_data)}\n\n"
+
+
+def generate_sse_stop_chunk(
+    req_id: str,
+    model: str,
+    reason: str = "stop",
+    usage: Optional[Dict[str, int]] = None,
+) -> str:
+    stop_chunk_data: Dict[str, Any] = {
+        "id": f"chatcmpl-{req_id}",
+        "object": "chat.completion.chunk",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [{"index": 0, "delta": {}, "finish_reason": reason}],
+    }
+    if usage:
+        stop_chunk_data["usage"] = usage
+    return f"data: {json.dumps(stop_chunk_data)}\n\ndata: [DONE]\n\n"
+
+
+def generate_sse_error_chunk(
+    message: str, req_id: str, error_type: str = "server_error"
+) -> str:
+    error_chunk = {
+        "error": {"message": message, "type": error_type, "param": None, "code": req_id}
+    }
+    return f"data: {json.dumps(error_chunk)}\n\n"

api_utils/tools_registry.py

@@ -0,0 +1,120 @@
+import asyncio
+import json
+import os
+import time
+from typing import Any, Dict, List, Optional, Set
+
+
+def tool_get_current_time(params: Dict[str, Any]) -> Dict[str, Any]:
+    return {"current_time": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
+
+
+def tool_echo(params: Dict[str, Any]) -> Dict[str, Any]:
+    return {"echo": params}
+
+
+def tool_sum(params: Dict[str, Any]) -> Dict[str, Any]:
+    values = params.get("values")
+    if isinstance(values, list):
+        try:
+            total = sum(float(v) for v in values)
+        except Exception:
+            total = None
+    else:
+        total = None
+    return {"sum": total, "count": len(values) if isinstance(values, list) else 0}
+
+
+FUNCTION_REGISTRY = {
+    "get_current_time": tool_get_current_time,
+    "echo": tool_echo,
+    "sum": tool_sum,
+}
+
+# Runtime-allowed tool names from incoming requests (OpenAI tools array)
+_ALLOWED_RUNTIME_TOOLS: Set[str] = set()
+_runtime_mcp_endpoint: Optional[str] = None
+
+
+def register_runtime_tools(
+    tools: Optional[List[Dict[str, Any]]], mcp_endpoint: Optional[str] = None
+) -> None:
+    """Register tool names declared in the request as allowed.
+    The server may delegate unknown tools to MCP if configured.
+    """
+    # Reset per-request registry to avoid leakage across requests
+    global _runtime_mcp_endpoint
+    _ALLOWED_RUNTIME_TOOLS.clear()
+    _runtime_mcp_endpoint = None
+    if not tools:
+        return
+    try:
+        for t in tools:
+            name = None
+            fn = t.get("function") if "function" in t else t
+            if isinstance(fn, dict):
+                name = fn.get("name") or t.get("name")
+            else:
+                name = t.get("name")
+            if name:
+                _ALLOWED_RUNTIME_TOOLS.add(str(name))
+            # Detect per-tool endpoint extension
+            ext_ep = (
+                t.get("x-mcp-endpoint")
+                or t.get("x_mcp_endpoint")
+                or (
+                    isinstance(t.get("function"), dict)
+                    and t["function"].get("x-mcp-endpoint")
+                )
+                or None
+            )
+            if ext_ep and not mcp_endpoint:
+                mcp_endpoint = ext_ep
+        # Capture per-request MCP endpoint if provided (explicit or via tool extension)
+        if mcp_endpoint:
+            _runtime_mcp_endpoint = mcp_endpoint
+    except Exception:
+        # be forgiving on malformed tools
+        pass
+
+
+async def execute_tool_call(name: str, arguments_json: str) -> str:
+    """Execute registered tools and return stringified result. Unknown tools return descriptive errors.
+    Fully asynchronous: built-in functions execute directly; MCP path uses async httpx client.
+    """
+    try:
+        params = json.loads(arguments_json or "{}")
+    except Exception:
+        params = {}
+
+    func = FUNCTION_REGISTRY.get(name)
+    if not func:
+        # If tool is not built-in but declared, try MCP adapter if configured (env or per-request)
+        if name in _ALLOWED_RUNTIME_TOOLS:
+            try:
+                from api_utils.mcp_adapter import (
+                    execute_mcp_tool,
+                    execute_mcp_tool_with_endpoint,
+                )
+
+                if _runtime_mcp_endpoint:
+                    return await execute_mcp_tool_with_endpoint(
+                        _runtime_mcp_endpoint, name, params
+                    )
+                if os.environ.get("MCP_HTTP_ENDPOINT"):
+                    return await execute_mcp_tool(name, params)
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                return json.dumps(
+                    {"error": f"MCP execution failed: {e}"}, ensure_ascii=False
+                )
+        return json.dumps(
+            {"error": f"Unknown tool: {name}", "arguments": params}, ensure_ascii=False
+        )
+
+    try:
+        result = func(params)
+        return json.dumps(result, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": f"Execution failed: {e}"}, ensure_ascii=False)

api_utils/utils.py

@@ -0,0 +1,52 @@
+"""
+API utility function module
+Contains utility functions for SSE generation, stream processing, token statistics, and request validation
+(Refactored: logic moved to api_utils.utils_ext submodules)
+"""
+
+
+from .sse import generate_sse_stop_chunk
+from .utils_ext import (
+    _extension_for_mime,
+    calculate_usage_stats,
+    clear_stream_queue,
+    collect_and_validate_attachments,
+    estimate_tokens,
+    extract_data_url_to_local,
+    extract_json_from_text,
+    get_latest_user_text,
+    maybe_execute_tools,
+    prepare_combined_prompt,
+    save_blob_to_local,
+    use_helper_get_response,
+    use_stream_response,
+    validate_chat_request,
+)
+
+# For backward compatibility with existing code that might import these private functions
+_extract_json_from_text = extract_json_from_text
+_get_latest_user_text = get_latest_user_text
+
+
+def generate_sse_stop_chunk_with_usage(req_id: str, model: str, usage_stats: dict, reason: str = "stop") -> str:
+    """Generate SSE stop chunk with usage statistics"""
+    return generate_sse_stop_chunk(req_id, model, reason, usage_stats)
+
+
+__all__ = [
+    "generate_sse_stop_chunk_with_usage",
+    "extract_data_url_to_local",
+    "save_blob_to_local",
+    "collect_and_validate_attachments",
+    "prepare_combined_prompt",
+    "maybe_execute_tools",
+    "extract_json_from_text",
+    "get_latest_user_text",
+    "use_stream_response",
+    "clear_stream_queue",
+    "use_helper_get_response",
+    "validate_chat_request",
+    "estimate_tokens",
+    "calculate_usage_stats",
+    "_extension_for_mime",
+]

api_utils/utils_ext/__init__.py

@@ -0,0 +1,95 @@
+"""
+Extended utility submodules extracted from api_utils.utils.
+This package groups stream, helper, validation, files, and tokens utilities.
+"""
+
+from .files import (
+    _extension_for_mime,
+    collect_and_validate_attachments,
+    extract_data_url_to_local,
+    save_blob_to_local,
+)
+from .function_call_response_parser import (
+    FunctionCallParseResult,
+    FunctionCallResponseParser,
+    format_function_calls_to_openai,
+)
+from .function_calling import (
+    CallIdManager,
+    FunctionCallingConfig,
+    FunctionCallingMode,
+    ParsedFunctionCall,
+    PendingCall,
+    ResponseFormatter,
+    SchemaConversionError,
+    SchemaConverter,
+    build_assistant_message_with_tool_calls,
+    convert_openai_tools_to_gemini,
+    create_tool_calls_response,
+    get_finish_reason,
+)
+from .function_calling_cache import (
+    FunctionCallingCache,
+    FunctionCallingCacheEntry,
+)
+from .function_calling_orchestrator import (
+    FunctionCallingOrchestrator,
+    FunctionCallingState,
+    NativeFunctionCallingError,
+    get_effective_function_calling_mode,
+    get_function_calling_orchestrator,
+    reset_orchestrator,
+    should_skip_tool_injection,
+)
+from .helper import use_helper_get_response
+from .prompts import prepare_combined_prompt
+from .stream import clear_stream_queue, use_stream_response
+from .string_utils import extract_json_from_text, get_latest_user_text
+from .tokens import calculate_usage_stats, estimate_tokens
+from .tools_execution import maybe_execute_tools
+from .validation import validate_chat_request
+
+__all__ = [
+    "use_stream_response",
+    "clear_stream_queue",
+    "use_helper_get_response",
+    "validate_chat_request",
+    "_extension_for_mime",
+    "extract_data_url_to_local",
+    "save_blob_to_local",
+    "collect_and_validate_attachments",
+    "estimate_tokens",
+    "calculate_usage_stats",
+    "prepare_combined_prompt",
+    "maybe_execute_tools",
+    "extract_json_from_text",
+    "get_latest_user_text",
+    # Function Calling utilities
+    "FunctionCallingMode",
+    "FunctionCallingConfig",
+    "SchemaConverter",
+    "SchemaConversionError",
+    "CallIdManager",
+    "PendingCall",
+    "ParsedFunctionCall",
+    "ResponseFormatter",
+    "build_assistant_message_with_tool_calls",
+    "get_finish_reason",
+    "convert_openai_tools_to_gemini",
+    "create_tool_calls_response",
+    # Function Calling Cache
+    "FunctionCallingCache",
+    "FunctionCallingCacheEntry",
+    # Function Calling Orchestrator
+    "FunctionCallingOrchestrator",
+    "FunctionCallingState",
+    "NativeFunctionCallingError",
+    "get_function_calling_orchestrator",
+    "reset_orchestrator",
+    "should_skip_tool_injection",
+    "get_effective_function_calling_mode",
+    # Function Call Response Parser
+    "FunctionCallResponseParser",
+    "FunctionCallParseResult",
+    "format_function_calls_to_openai",
+]

api_utils/utils_ext/cooldown_manager.py

@@ -0,0 +1,99 @@
+import json
+import logging
+import os
+import threading
+from datetime import datetime
+
+COOLDOWN_FILE = os.path.join(
+    os.path.dirname(__file__), "..", "..", "config", "cooldown_status.json"
+)
+_lock = threading.Lock()
+
+
+def load_cooldown_profiles():
+    """
+    Loads the cooldown profiles from the persistent JSON file.
+
+    Returns:
+        dict: A dictionary of cooldown profiles.
+    """
+    with _lock:
+        if not os.path.exists(COOLDOWN_FILE):
+            return {}
+        try:
+            with open(COOLDOWN_FILE, "r") as f:
+                data = json.load(f)
+
+            profiles = {}
+            for profile, val in data.items():
+                if isinstance(val, dict):
+                    # Handle nested model-specific cooldowns
+                    model_cooldowns = {}
+                    for model_id, ts in val.items():
+                        try:
+                            model_cooldowns[model_id] = datetime.fromisoformat(ts)
+                        except (ValueError, TypeError):
+                            continue
+                    if model_cooldowns:
+                        # Clean up redundant "default" entries when specific models exist
+                        has_specific_models = any(
+                            model_id != "default" for model_id in model_cooldowns.keys()
+                        )
+                        if has_specific_models and "default" in model_cooldowns:
+                            logger = logging.getLogger("CooldownManager")
+                            logger.info(
+                                f"🧹 Cleaning up redundant 'default' entry for profile {os.path.basename(profile)}"
+                            )
+                            del model_cooldowns["default"]
+                        profiles[profile] = model_cooldowns
+                else:
+                    # Handle legacy/global cooldowns
+                    try:
+                        profiles[profile] = datetime.fromisoformat(val)
+                    except (ValueError, TypeError):
+                        continue
+            return profiles
+        except (json.JSONDecodeError, IOError):
+            return {}
+
+
+def save_cooldown_profiles(profiles):
+    """
+    Saves the cooldown profiles to the persistent JSON file.
+
+    Args:
+        profiles (dict): A dictionary of cooldown profiles to save.
+    """
+    with _lock:
+        try:
+            serializable_profiles = {}
+            for profile, data in profiles.items():
+                if isinstance(data, dict):
+                    # Handle nested model-specific cooldowns
+                    model_cooldowns = {}
+                    for model_id, ts in data.items():
+                        if isinstance(ts, datetime):
+                            model_cooldowns[model_id] = ts.isoformat()
+                        elif isinstance(ts, (int, float)):
+                            try:
+                                model_cooldowns[model_id] = datetime.fromtimestamp(
+                                    ts
+                                ).isoformat()
+                            except (ValueError, OSError):
+                                pass
+                    serializable_profiles[profile] = model_cooldowns
+
+                elif isinstance(data, datetime):
+                    serializable_profiles[profile] = data.isoformat()
+                elif isinstance(data, (int, float)):
+                    try:
+                        serializable_profiles[profile] = datetime.fromtimestamp(
+                            data
+                        ).isoformat()
+                    except (ValueError, OSError):
+                        pass
+
+            with open(COOLDOWN_FILE, "w") as f:
+                json.dump(serializable_profiles, f, indent=4)
+        except IOError:
+            pass

api_utils/utils_ext/files.py

@@ -0,0 +1,201 @@
+import base64
+import binascii
+import hashlib
+import logging
+import os
+import re
+from typing import Any, Dict, List, Optional, cast
+from urllib.parse import unquote, urlparse
+
+from logging_utils import set_request_id
+
+
+def _extension_for_mime(mime_type: str) -> str:
+    mime_type = (mime_type or "").lower()
+    mapping = {
+        "image/png": ".png",
+        "image/jpeg": ".jpg",
+        "image/jpg": ".jpg",
+        "image/gif": ".gif",
+        "image/webp": ".webp",
+        "image/svg+xml": ".svg",
+        "image/bmp": ".bmp",
+        "video/mp4": ".mp4",
+        "video/webm": ".webm",
+        "video/ogg": ".ogv",
+        "audio/mpeg": ".mp3",
+        "audio/mp3": ".mp3",
+        "audio/wav": ".wav",
+        "audio/ogg": ".ogg",
+        "audio/webm": ".weba",
+        "application/pdf": ".pdf",
+        "application/zip": ".zip",
+        "application/x-zip-compressed": ".zip",
+        "application/json": ".json",
+        "text/plain": ".txt",
+        "text/markdown": ".md",
+        "text/html": ".html",
+    }
+    return mapping.get(
+        mime_type, f".{mime_type.split('/')[-1]}" if "/" in mime_type else ".bin"
+    )
+
+
+def extract_data_url_to_local(
+    data_url: str, req_id: Optional[str] = None
+) -> Optional[str]:
+    from config import UPLOAD_FILES_DIR
+
+    logger = logging.getLogger("AIStudioProxyServer")
+
+    output_dir = (
+        UPLOAD_FILES_DIR if req_id is None else os.path.join(UPLOAD_FILES_DIR, req_id)
+    )
+
+    match = re.match(r"^data:(?P<mime>[^;]+);base64,(?P<data>.*)$", data_url)
+    if not match:
+        logger.error(
+            "Error: data:URL format is incorrect or does not contain base64 data."
+        )
+        return None
+
+    mime_type = match.group("mime")
+    encoded_data = match.group("data")
+
+    try:
+        decoded_bytes = base64.b64decode(encoded_data)
+    except binascii.Error as e:
+        logger.error(f"Error: Base64 decoding failed - {e}")
+        return None
+
+    md5_hash = hashlib.md5(decoded_bytes).hexdigest()
+    file_extension = _extension_for_mime(mime_type)
+    output_filepath = os.path.join(output_dir, f"{md5_hash}{file_extension}")
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    if os.path.exists(output_filepath):
+        logger.info(f"File already exists, skipping save: {output_filepath}")
+        return output_filepath
+
+    try:
+        with open(output_filepath, "wb") as f:
+            f.write(decoded_bytes)
+        logger.info(f"Saved data:URL to: {output_filepath}")
+        return output_filepath
+    except IOError as e:
+        logger.error(f"Error: Failed to save file - {e}")
+        return None
+
+
+def save_blob_to_local(
+    raw_bytes: bytes,
+    mime_type: Optional[str] = None,
+    fmt_ext: Optional[str] = None,
+    req_id: Optional[str] = None,
+) -> Optional[str]:
+    from config import UPLOAD_FILES_DIR
+
+    logger = logging.getLogger("AIStudioProxyServer")
+
+    output_dir = (
+        UPLOAD_FILES_DIR if req_id is None else os.path.join(UPLOAD_FILES_DIR, req_id)
+    )
+    md5_hash = hashlib.md5(raw_bytes).hexdigest()
+    ext = None
+    if fmt_ext:
+        fmt_ext = fmt_ext.strip(". ")
+        ext = f".{fmt_ext}" if fmt_ext else None
+    if not ext and mime_type:
+        ext = _extension_for_mime(mime_type)
+    if not ext:
+        ext = ".bin"
+    os.makedirs(output_dir, exist_ok=True)
+    output_filepath = os.path.join(output_dir, f"{md5_hash}{ext}")
+    if os.path.exists(output_filepath):
+        logger.info(f"File already exists, skipping save: {output_filepath}")
+        return output_filepath
+    try:
+        with open(output_filepath, "wb") as f:
+            f.write(raw_bytes)
+        logger.info(f"Saved binary to: {output_filepath}")
+        return output_filepath
+    except IOError as e:
+        logger.error(f"Error: Failed to save binary - {e}")
+        return None
+
+
+def collect_and_validate_attachments(
+    request: Any, req_id: str, initial_image_list: List[str]
+) -> List[str]:
+    """
+    Collect and validate attachments in the request (including top-level and message-level), merged into image_list.
+    """
+    logger = logging.getLogger("AIStudioProxyServer")
+
+    # 1. Validate initial list
+    valid_images: List[str] = []
+    for p in initial_image_list:
+        if p and os.path.isabs(p) and os.path.exists(p):
+            valid_images.append(p)
+
+    set_request_id(req_id)
+    if len(valid_images) != len(initial_image_list):
+        logger.warning(
+            f"Filtered out non-existent attachment paths: {set(initial_image_list) - set(valid_images)}"
+        )
+
+    image_list: List[str] = valid_images
+
+    # 2. Collect from request
+    def _process_attachments_list(items_list: List[Any], container_desc: str):
+        for it in items_list:
+            url_value: Optional[str] = None
+            if isinstance(it, str):
+                url_value = it
+            elif isinstance(it, dict):
+                typed_it: Dict[str, Any] = cast(Dict[str, Any], it)
+                url_raw: Any = typed_it.get("url") or typed_it.get("path")
+                if isinstance(url_raw, str):
+                    url_value = url_raw
+            if not url_value:
+                continue
+            url_value = url_value.strip()
+            if not url_value:
+                continue
+
+            if url_value.startswith("data:"):
+                fp = extract_data_url_to_local(url_value, req_id=req_id)
+                if fp:
+                    image_list.append(fp)
+            elif url_value.startswith("file:"):
+                parsed = urlparse(url_value)
+                lp = unquote(parsed.path)
+                if os.path.exists(lp):
+                    image_list.append(lp)
+                else:
+                    logger.warning(
+                        f"{container_desc} attachment file URL does not exist: {lp}"
+                    )
+            elif os.path.isabs(url_value) and os.path.exists(url_value):
+                image_list.append(url_value)
+
+    try:
+        # Top-level attachments
+        top_level_atts = getattr(request, "attachments", None)
+        if isinstance(top_level_atts, list) and len(top_level_atts) > 0:
+            _process_attachments_list(top_level_atts, "request.attachments")
+
+        # Message-level attachments/images/files/media
+        messages = getattr(request, "messages", None)
+        if isinstance(messages, list):
+            for i, msg in enumerate(messages):
+                for field in ["attachments", "images", "files", "media"]:
+                    items = getattr(msg, field, None)
+                    if isinstance(items, list) and len(items) > 0:
+                        _process_attachments_list(items, f"message[{i}].{field}")
+
+    except Exception as e:
+        logger.error(f"Error collecting attachments: {e}")
+
+    return image_list