Upload 4 files

entrypoint.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# ============================================================================
+#  NEXUS AI — Container entrypoint
+#  1) Detects the GPU and launches the vLLM OpenAI-compatible server
+#     in the background (skipped automatically when MOCK_MODE=1 or no GPU).
+#  2) Starts the FastAPI/uvicorn orchestrator on port 7860.
+# ============================================================================
+set -euo pipefail
+
+log() { echo "[entrypoint $(date +%H:%M:%S)] $*"; }
+
+log "=========================================================="
+log " NEXUS AI platform boot sequence"
+log " Model        : ${MODEL_NAME}"
+log " Max context  : ${MAX_MODEL_LEN}"
+log " GPU mem util : ${GPU_MEMORY_UTILIZATION}"
+log " Mock mode    : ${MOCK_MODE:-auto}"
+log "=========================================================="
+
+GPU_PRESENT=0
+if command -v nvidia-smi >/dev/null 2>&1 && nvidia-smi -L 2>/dev/null | grep -qi "GPU"; then
+    GPU_PRESENT=1
+fi
+
+if [[ "${MOCK_MODE:-auto}" == "1" || "${MOCK_MODE:-auto}" == "true" ]]; then
+    log "MOCK_MODE forced -> built-in simulation engine will answer."
+elif [[ "${GPU_PRESENT}" == "1" ]]; then
+    log "GPU detected -> launching vLLM OpenAI server on ${VLLM_HOST}:${VLLM_PORT}"
+    # shellcheck disable=SC2086
+    nohup vllm serve "${MODEL_NAME}" \
+        --host "${VLLM_HOST}" \
+        --port "${VLLM_PORT}" \
+        --dtype "${VLLM_DTYPE}" \
+        --max-model-len "${MAX_MODEL_LEN}" \
+        --gpu-memory-utilization "${GPU_MEMORY_UTILIZATION}" \
+        --enable-prefix-caching \
+        --disable-log-requests \
+        ${EXTRA_VLLM_ARGS:-} \
+        > /home/user/app/vllm_server.log 2>&1 &
+    VLLM_PID=$!
+    log "vLLM server started (pid=${VLLM_PID}). Logs: vllm_server.log"
+    log "FastAPI will answer with the simulation engine until vLLM is healthy."
+else
+    log "No GPU visible -> running with the built-in simulation engine."
+fi
+
+log "Starting FastAPI orchestrator on 0.0.0.0:${PORT}"
+exec uvicorn main:app \
+    --host 0.0.0.0 \
+    --port "${PORT}" \
+    --workers 1 \
+    --loop uvloop \
+    --http httptools \
+    --timeout-keep-alive 75 \
+    --log-level info

main.py

@@ -0,0 +1,1854 @@
+#!/usr/bin/env python3
+# ============================================================================
+#  NEXUS AI — Elite AI Chat Platform · FastAPI Orchestrator
+# ----------------------------------------------------------------------------
+#  • Three-tier AI engine ........ Flash / Max (deep reasoning) / Agents swarm
+#  • Local inference ............. vLLM OpenAI-compatible server (A100 tuned)
+#  • Persistence ................. Turso (libSQL) with automatic local fallback
+#  • Security .................... master-token + IP + GPS audit + JWT sessions
+#  • Observability ............... live CPU/RAM/GPU/token telemetry (WebSocket)
+#  • Self-healing ................ AI log analyzer + on-the-fly patch applier
+#  • Sandbox ..................... jailed web terminal + file manager + uploads
+# ============================================================================
+from __future__ import annotations
+
+import asyncio
+import collections
+import hashlib
+import hmac
+import json
+import logging
+import math
+import os
+import re
+import secrets
+import shutil
+import sqlite3
+import sys
+import threading
+import time
+import traceback
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, AsyncGenerator, Deque, Dict, List, Optional, Tuple
+
+import jwt
+import psutil
+import requests
+from fastapi import (
+    Body,
+    Depends,
+    FastAPI,
+    File,
+    HTTPException,
+    Query,
+    Request,
+    UploadFile,
+    WebSocket,
+    WebSocketDisconnect,
+)
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+# ---------------------------------------------------------------------------
+# Optional dependencies (never crash the boot if one is missing)
+# ---------------------------------------------------------------------------
+try:
+    import GPUtil  # type: ignore
+except Exception:  # pragma: no cover
+    GPUtil = None
+
+try:
+    import libsql_client  # type: ignore
+except Exception:  # pragma: no cover
+    libsql_client = None
+
+try:
+    from bs4 import BeautifulSoup  # type: ignore
+except Exception:  # pragma: no cover
+    BeautifulSoup = None
+
+try:
+    from pypdf import PdfReader  # type: ignore
+except Exception:  # pragma: no cover
+    PdfReader = None
+
+try:
+    import pytesseract  # type: ignore
+    from PIL import Image  # type: ignore
+except Exception:  # pragma: no cover
+    pytesseract = None
+    Image = None
+
+# ============================================================================
+# 1. CONFIGURATION
+# ============================================================================
+APP_ROOT = Path(__file__).resolve().parent
+STATIC_DIR = APP_ROOT / "static"
+SANDBOX_DIR = Path(os.environ.get("SANDBOX_DIR", str(APP_ROOT / "sandbox_workspace"))).resolve()
+UPLOAD_DIR = SANDBOX_DIR / "uploads"
+LOCAL_DB_PATH = os.environ.get("LOCAL_DB_PATH", str(APP_ROOT / "nexus_local.db"))
+
+for _d in (SANDBOX_DIR, UPLOAD_DIR):
+    _d.mkdir(parents=True, exist_ok=True)
+
+
+class CFG:
+    """Central runtime configuration (all overridable via environment)."""
+
+    APP_NAME: str = os.environ.get("APP_NAME", "NEXUS AI")
+    VERSION: str = "3.1.0"
+    PORT: int = int(os.environ.get("PORT", "7860"))
+
+    # --- Security -----------------------------------------------------------
+    ADMIN_API_KEY: str = os.environ.get("ADMIN_API_KEY", "").strip()
+    JWT_SECRET: str = os.environ.get("JWT_SECRET", "").strip()
+    JWT_ALG: str = "HS256"
+    JWT_TTL_HOURS: int = int(os.environ.get("JWT_TTL_HOURS", "168"))  # 7 days
+    SESSION_COOKIE: str = "nexus_session"
+
+    # --- Geo shield ----------------------------------------------------------
+    SAFE_LAT: Optional[float] = (
+        float(os.environ["SAFE_LAT"]) if os.environ.get("SAFE_LAT") else None
+    )
+    SAFE_LON: Optional[float] = (
+        float(os.environ["SAFE_LON"]) if os.environ.get("SAFE_LON") else None
+    )
+    SAFE_RADIUS_KM: float = float(os.environ.get("SAFE_RADIUS_KM", "50"))
+    STRICT_GEO: bool = os.environ.get("STRICT_GEO", "0") in ("1", "true", "yes")
+
+    # --- Database ------------------------------------------------------------
+    TURSO_URL: str = os.environ.get("TURSO_DATABASE_URL", "").strip()
+    TURSO_TOKEN: str = os.environ.get("TURSO_AUTH_TOKEN", "").strip()
+
+    # --- Inference -----------------------------------------------------------
+    VLLM_URL: str = (
+        f"http://{os.environ.get('VLLM_HOST', '127.0.0.1')}:"
+        f"{os.environ.get('VLLM_PORT', '8000')}/v1"
+    )
+    MODEL_NAME: str = os.environ.get(
+        "MODEL_NAME", "deepseek-ai/DeepSeek-Coder-V2-Lite-Instruct"
+    )
+    HF_TOKEN: str = os.environ.get("HF_TOKEN", "").strip()
+    MOCK_MODE: bool = os.environ.get("MOCK_MODE", "auto").lower() in ("1", "true", "yes")
+
+    # --- Generation defaults -------------------------------------------------
+    DEFAULT_MAX_TOKENS: int = int(os.environ.get("DEFAULT_MAX_TOKENS", "4096"))
+    DEFAULT_CONTEXT_WINDOW: int = int(os.environ.get("MAX_MODEL_LEN", "32768"))
+    LLM_TIMEOUT_S: int = int(os.environ.get("LLM_TIMEOUT_S", "600"))
+
+    # --- Sandbox terminal ----------------------------------------------------
+    TERMINAL_TIMEOUT_S: int = int(os.environ.get("TERMINAL_TIMEOUT_S", "180"))
+    TERMINAL_MAX_OUTPUT: int = int(os.environ.get("TERMINAL_MAX_OUTPUT", str(256 * 1024)))
+
+    # --- Web research ---------------------------------------------------------
+    SEARCH_TIMEOUT_S: int = int(os.environ.get("SEARCH_TIMEOUT_S", "15"))
+    FETCH_MAX_BYTES: int = int(os.environ.get("FETCH_MAX_BYTES", str(120 * 1024)))
+
+    LOG_BUFFER_SIZE: int = 2000
+
+
+if not CFG.ADMIN_API_KEY:
+    CFG.ADMIN_API_KEY = secrets.token_urlsafe(24)
+    _AUTO_KEY = True
+else:
+    _AUTO_KEY = False
+
+if not CFG.JWT_SECRET:
+    CFG.JWT_SECRET = hashlib.sha256(f"nexus::{CFG.ADMIN_API_KEY}".encode()).hexdigest()
+
+# ============================================================================
+# 2. LOGGING — console + rolling in-memory buffer + async DB mirroring
+# ============================================================================
+LOG_BUFFER: Deque[Dict[str, Any]] = collections.deque(maxlen=CFG.LOG_BUFFER_SIZE)
+
+
+class RingBufferHandler(logging.Handler):
+    """Keeps the last N records in RAM and mirrors them into Turso (best effort)."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            entry = {
+                "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+                "level": record.levelname,
+                "logger": record.name,
+                "message": self.format(record),
+            }
+            LOG_BUFFER.append(entry)
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(self._persist(entry))
+            except RuntimeError:
+                pass  # no running loop yet (early boot)
+        except Exception:
+            pass
+
+    @staticmethod
+    async def _persist(entry: Dict[str, Any]) -> None:
+        try:
+            if DB.ready:
+                await DB.execute(
+                    "INSERT INTO system_logs(level, logger, message) VALUES(?,?,?)",
+                    (entry["level"], entry["logger"], entry["message"][:4000]),
+                )
+        except Exception:
+            pass
+
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(levelname)-7s | %(name)s | %(message)s",
+    stream=sys.stdout,
+)
+_ring = RingBufferHandler()
+_ring.setFormatter(logging.Formatter("%(message)s"))
+logging.getLogger().addHandler(_ring)
+log = logging.getLogger("nexus")
+
+# ============================================================================
+# 3. DATABASE — Turso (libSQL) with automatic local-file fallback
+# ============================================================================
+SCHEMA_STATEMENTS: Tuple[str, ...] = (
+    """CREATE TABLE IF NOT EXISTS users (
+           id TEXT PRIMARY KEY,
+           username TEXT UNIQUE,
+           created_at TEXT DEFAULT (datetime('now'))
+       )""",
+    """CREATE TABLE IF NOT EXISTS chats (
+           id TEXT PRIMARY KEY,
+           user_id TEXT,
+           title TEXT NOT NULL DEFAULT 'New chat',
+           mode TEXT NOT NULL DEFAULT 'flash',
+           created_at TEXT DEFAULT (datetime('now')),
+           updated_at TEXT DEFAULT (datetime('now'))
+       )""",
+    """CREATE TABLE IF NOT EXISTS messages (
+           id TEXT PRIMARY KEY,
+           chat_id TEXT NOT NULL,
+           role TEXT NOT NULL,
+           content TEXT NOT NULL,
+           mode TEXT DEFAULT 'flash',
+           tokens INTEGER DEFAULT 0,
+           created_at TEXT DEFAULT (datetime('now'))
+       )""",
+    """CREATE INDEX IF NOT EXISTS idx_messages_chat ON messages(chat_id)""",
+    """CREATE TABLE IF NOT EXISTS memories (
+           id TEXT PRIMARY KEY,
+           key TEXT UNIQUE NOT NULL,
+           value TEXT NOT NULL,
+           updated_at TEXT DEFAULT (datetime('now'))
+       )""",
+    """CREATE TABLE IF NOT EXISTS system_logs (
+           id INTEGER PRIMARY KEY AUTOINCREMENT,
+           level TEXT,
+           logger TEXT,
+           message TEXT,
+           created_at TEXT DEFAULT (datetime('now'))
+       )""",
+    """CREATE TABLE IF NOT EXISTS sandbox_projects (
+           id TEXT PRIMARY KEY,
+           name TEXT UNIQUE NOT NULL,
+           files_json TEXT NOT NULL DEFAULT '{}',
+           updated_at TEXT DEFAULT (datetime('now'))
+       )""",
+    """CREATE TABLE IF NOT EXISTS auth_audit (
+           id INTEGER PRIMARY KEY AUTOINCREMENT,
+           ip TEXT,
+           latitude REAL,
+           longitude REAL,
+           success INTEGER DEFAULT 0,
+           reason TEXT,
+           user_agent TEXT,
+           created_at TEXT DEFAULT (datetime('now'))
+       )""",
+)
+
+
+class _SQLiteShim:
+    """Tiny stdlib fallback exposing the subset of the libsql API we use."""
+
+    def __init__(self, path: str) -> None:
+        self.conn = sqlite3.connect(path, check_same_thread=False)
+        self._lock = threading.Lock()
+
+    def execute(self, sql: str, params: Any = None):
+        with self._lock:
+            cur = self.conn.execute(sql, tuple(params or ()))
+            self.conn.commit()
+
+            class RS:
+                columns = [d[0] for d in (cur.description or [])]
+                rows = cur.fetchall()
+                rows_affected = cur.rowcount
+
+            return RS()
+
+    def close(self) -> None:
+        self.conn.close()
+
+
+class _Database:
+    """Async façade around the (synchronous) libsql/sqlite clients."""
+
+    def __init__(self) -> None:
+        self.client: Any = None
+        self.backend: str = "none"
+        self.ready: bool = False
+
+    async def connect(self) -> None:
+        if CFG.TURSO_URL and libsql_client is not None:
+            try:
+                self.client = libsql_client.create_client(
+                    CFG.TURSO_URL, auth_token=CFG.TURSO_TOKEN or None
+                )
+                await asyncio.to_thread(self.client.execute, "SELECT 1")
+                self.backend = "turso"
+                log.info("Connected to Turso database: %s", CFG.TURSO_URL)
+            except Exception as exc:  # pragma: no cover
+                log.error("Turso connection failed (%s) — falling back to local DB", exc)
+                self.client = None
+
+        if self.client is None:
+            if libsql_client is not None:
+                self.client = libsql_client.create_client(f"file:{LOCAL_DB_PATH}")
+            else:
+                self.client = _SQLiteShim(LOCAL_DB_PATH)
+            self.backend = "local"
+            log.warning("Using LOCAL embedded database at %s", LOCAL_DB_PATH)
+
+        for stmt in SCHEMA_STATEMENTS:
+            await asyncio.to_thread(self.client.execute, stmt)
+        self.ready = True
+        log.info("Database schema verified (%s backend)", self.backend)
+
+    # -- helpers -------------------------------------------------------------
+    async def execute(self, sql: str, params: Any = None):
+        if not self.ready:
+            raise RuntimeError("database not ready")
+        return await asyncio.to_thread(self.client.execute, sql, tuple(params or ()))
+
+    async def query(self, sql: str, params: Any = None) -> List[Dict[str, Any]]:
+        rs = await self.execute(sql, params)
+        cols = list(rs.columns)
+        return [dict(zip(cols, row)) for row in rs.rows]
+
+    async def query_one(self, sql: str, params: Any = None) -> Optional[Dict[str, Any]]:
+        rows = await self.query(sql, params)
+        return rows[0] if rows else None
+
+    def close(self) -> None:
+        try:
+            self.client.close()
+        except Exception:
+            pass
+
+
+DB = _Database()
+
+# ============================================================================
+# 4. SMALL UTILITIES
+# ============================================================================
+def new_id() -> str:
+    return uuid.uuid4().hex
+
+
+def utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def approx_tokens(text: str) -> int:
+    """Fast heuristic token estimate (≈4 chars/token, min 1 for non-empty)."""
+    if not text:
+        return 0
+    return max(1, math.ceil(len(text) / 4))
+
+
+def clamp(value: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, value))
+
+
+def haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    r = 6371.0
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp = math.radians(lat2 - lat1)
+    dl = math.radians(lon2 - lon1)
+    a = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * r * math.asin(math.sqrt(a))
+
+
+def client_ip(request: Request) -> str:
+    fwd = request.headers.get("x-forwarded-for", "")
+    if fwd:
+        return fwd.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+# ============================================================================
+# 5. SECURITY — JWT sessions, geo shield, dependency guards
+# ============================================================================
+def issue_token(ip: str) -> str:
+    now = datetime.now(timezone.utc)
+    payload = {
+        "sub": "nexus-admin",
+        "ip": ip,
+        "iat": int(now.timestamp()),
+        "exp": int((now + timedelta(hours=CFG.JWT_TTL_HOURS)).timestamp()),
+        "jti": new_id(),
+    }
+    return jwt.encode(payload, CFG.JWT_SECRET, algorithm=CFG.JWT_ALG)
+
+
+def decode_token(token: str) -> Optional[Dict[str, Any]]:
+    try:
+        return jwt.decode(token, CFG.JWT_SECRET, algorithms=[CFG.JWT_ALG])
+    except Exception:
+        return None
+
+
+def token_from_request(request: Request) -> Optional[str]:
+    auth = request.headers.get("authorization", "")
+    if auth.lower().startswith("bearer "):
+        return auth.split(" ", 1)[1].strip()
+    cookie = request.cookies.get(CFG.SESSION_COOKIE)
+    if cookie:
+        return cookie
+    return request.query_params.get("token")
+
+
+async def require_session(request: Request) -> Dict[str, Any]:
+    token = token_from_request(request)
+    session = decode_token(token) if token else None
+    if not session:
+        raise HTTPException(status_code=401, detail="authentication required")
+    return session
+
+
+def ws_session(ws: WebSocket) -> Optional[Dict[str, Any]]:
+    token = ws.query_params.get("token") or ws.cookies.get(CFG.SESSION_COOKIE)
+    return decode_token(token) if token else None
+
+
+def geo_verdict(lat: Optional[float], lon: Optional[float]) -> Tuple[bool, str]:
+    """Returns (accepted, reason). Registers everything for audit either way."""
+    if CFG.SAFE_LAT is None or CFG.SAFE_LON is None:
+        return True, "geo-fence not configured — audited"
+    if lat is None or lon is None:
+        return (not CFG.STRICT_GEO), "no coordinates supplied"
+    dist = haversine_km(CFG.SAFE_LAT, CFG.SAFE_LON, lat, lon)
+    if dist <= CFG.SAFE_RADIUS_KM:
+        return True, f"inside safe zone ({dist:.1f} km)"
+    if CFG.STRICT_GEO:
+        return False, f"outside safe zone ({dist:.1f} km > {CFG.SAFE_RADIUS_KM} km)"
+    return True, f"outside safe zone ({dist:.1f} km) — audited"
+
+
+class AuthVerifyIn(BaseModel):
+    token: str = Field(..., min_length=1, max_length=512)
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+
+
+# ============================================================================
+# 6. SAFETY ENGINE — three strictness profiles
+# ============================================================================
+class SafetyEngine:
+    """Pattern-based protective filter pipeline.
+
+    Profiles
+    --------
+    very_severe : hyper-sensitive — blocks injection, malware, violence, NSFW,
+                  jailbreak attempts and redacts PII on input AND output.
+    balanced    : default protection — blocks malware/violence/injection,
+                  warns + redacts PII.
+    none        : every filter disabled (unrestricted developer operations).
+    """
+
+    PATTERNS: Dict[str, str] = {
+        "prompt_injection": (
+            r"(?i)\b(ignore\s+(all|any|previous|prior)\s+(instructions|prompts|rules)"
+            r"|disregard\s+(your|all)\s+(instructions|training)"
+            r"|reveal\s+(your|the)\s+(system\s+prompt|instructions)"
+            r"|\bDAN\b|\bjailbreak\b|bypass\s+(the\s+)?(safety|filters?))"
+        ),
+        "malware": (
+            r"(?i)\b(ransomware|keylogger|botnet|rat\s+trojan|exploit\s+kit"
+            r"|reverse\s+shell\s+payload|dropper\s+script|rootkit|cryptominer\s+payload)\b"
+        ),
+        "violence": (
+            r"(?i)\b(build|make|assemble)\s+(a\s+)?(bomb|explosive|pipe\s+bomb|molotov)"
+            r"|\b(assassination\s+plan|school\s+shooting\s+plan)\b"
+        ),
+        "nsfw": r"(?i)\b(pornograph|explicit\s+sexual\s+content|\bxxx\b)\b",
+        "pii_email": r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}",
+        "pii_ssn": r"\b\d{3}-\d{2}-\d{4}\b",
+        "pii_card": r"\b(?:\d[ -]*?){13,16}\b",
+    }
+
+    BLOCK_RULES: Dict[str, Tuple[str, ...]] = {
+        "very_severe": (
+            "prompt_injection", "malware", "violence", "nsfw",
+            "pii_email", "pii_ssn", "pii_card",
+        ),
+        "balanced": ("prompt_injection", "malware", "violence"),
+        "none": (),
+    }
+    REDACT_RULES: Dict[str, Tuple[str, ...]] = {
+        "very_severe": ("pii_email", "pii_ssn", "pii_card"),
+        "balanced": ("pii_email", "pii_ssn", "pii_card"),
+        "none": (),
+    }
+
+    def __init__(self) -> None:
+        self._compiled = {k: re.compile(v) for k, v in self.PATTERNS.items()}
+
+    def scan(
+        self, text: str, profile: str
+    ) -> Tuple[bool, List[str], str]:
+        profile = (profile or "balanced").lower()
+        if profile not in self.BLOCK_RULES:
+            profile = "balanced"
+        violations: List[str] = []
+        sanitized = text
+        for name in self.BLOCK_RULES[profile]:
+            if self._compiled[name].search(text):
+                violations.append(name)
+        for name in self.REDACT_RULES[profile]:
+            sanitized = self._compiled[name].sub(f"[REDACTED-{name.upper()}]", sanitized)
+        blocked = bool(violations) and profile != "none"
+        return (not blocked), violations, sanitized
+
+
+SAFETY = SafetyEngine()
+
+# ============================================================================
+# 7. WEB RESEARCH — DuckDuckGo HTML search + lightweight page fetching
+# ============================================================================
+TRUSTED_DOMAINS = (
+    "github.com", "stackoverflow.com", "stackexchange.com", "arxiv.org",
+    "docs.python.org", "developer.mozilla.org", "huggingface.co",
+    "pytorch.org", "wikipedia.org",
+)
+
+
+def ddg_search(query: str, max_results: int = 5, trusted_only: bool = False) -> List[Dict[str, str]]:
+    """Scrape DuckDuckGo's HTML endpoint. Returns [{title, url, snippet}]."""
+    results: List[Dict[str, str]] = []
+    try:
+        resp = requests.get(
+            "https://html.duckduckgo.com/html/",
+            params={"q": query},
+            headers={"User-Agent": "Mozilla/5.0 (X11; Linux x86_64) NEXUS-Research/3.0"},
+            timeout=CFG.SEARCH_TIMEOUT_S,
+        )
+        resp.raise_for_status()
+        if BeautifulSoup is None:
+            return results
+        soup = BeautifulSoup(resp.text, "lxml")
+        for res in soup.select(".result"):
+            a = res.select_one(".result__a")
+            sn = res.select_one(".result__snippet")
+            if not a or not a.get("href"):
+                continue
+            url = a["href"]
+            m = re.search(r"uddg=([^&]+)", url)
+            if m:
+                from urllib.parse import unquote
+                url = unquote(m.group(1))
+            if trusted_only and not any(d in url for d in TRUSTED_DOMAINS):
+                continue
+            results.append(
+                {
+                    "title": a.get_text(strip=True)[:200],
+                    "url": url,
+                    "snippet": (sn.get_text(strip=True)[:400] if sn else ""),
+                }
+            )
+            if len(results) >= max_results:
+                break
+    except Exception as exc:
+        log.warning("web search failed: %s", exc)
+    return results
+
+
+def fetch_page_text(url: str, max_chars: int = 6000) -> str:
+    """Fetch a page and return cleaned visible text (bounded)."""
+    try:
+        resp = requests.get(
+            url,
+            headers={"User-Agent": "Mozilla/5.0 (X11; Linux x86_64) NEXUS-Research/3.0"},
+            timeout=CFG.SEARCH_TIMEOUT_S,
+            stream=True,
+        )
+        resp.raise_for_status()
+        raw = resp.raw.read(CFG.FETCH_MAX_BYTES, decode_content=True)
+        if BeautifulSoup is None:
+            return raw.decode("utf-8", "ignore")[:max_chars]
+        soup = BeautifulSoup(raw, "lxml")
+        for tag in soup(["script", "style", "noscript", "header", "footer", "nav"]):
+            tag.decompose()
+        text = re.sub(r"\s+", " ", soup.get_text(" ", strip=True))
+        return text[:max_chars]
+    except Exception as exc:
+        log.warning("fetch failed for %s: %s", url, exc)
+        return ""
+
+# ============================================================================
+# 8. TOKEN METER — cumulative generation-rate accounting
+# ============================================================================
+class TokenMeter:
+    def __init__(self) -> None:
+        self.events: Deque[Tuple[float, int]] = collections.deque(maxlen=10000)
+        self.total: int = 0
+
+    def record(self, n: int) -> None:
+        if n <= 0:
+            return
+        self.events.append((time.time(), n))
+        self.total += n
+
+    def rate(self, window_s: float = 30.0) -> float:
+        cutoff = time.time() - window_s
+        return sum(n for ts, n in self.events if ts >= cutoff) / window_s
+
+
+METER = TokenMeter()
+
+# ============================================================================
+# 9. LLM CLIENT — vLLM OpenAI-compatible backend + resilient simulation engine
+# ============================================================================
+class LLMClient:
+    def __init__(self) -> None:
+        self._health_cache: Tuple[float, bool] = (0.0, False)
+
+    # -- health ---------------------------------------------------------------
+    def _health_sync(self) -> bool:
+        try:
+            r = requests.get(f"{CFG.VLLM_URL}/models", timeout=2.5)
+            return r.status_code == 200
+        except Exception:
+            return False
+
+    async def healthy(self) -> bool:
+        if CFG.MOCK_MODE:
+            return False
+        ts, cached = self._health_cache
+        if time.time() - ts < 15:
+            return cached
+        ok = await asyncio.to_thread(self._health_sync)
+        self._health_cache = (time.time(), ok)
+        return ok
+
+    # -- payload ---------------------------------------------------------------
+    @staticmethod
+    def _payload(messages: List[Dict[str, str]], s: Dict[str, Any], stream: bool) -> Dict[str, Any]:
+        return {
+            "model": s.get("model") or CFG.MODEL_NAME,
+            "messages": messages,
+            "temperature": clamp(float(s.get("temperature", 0.7)), 0.0, 2.0),
+            "top_p": clamp(float(s.get("top_p", 0.95)), 0.0, 1.0),
+            "top_k": int(s.get("top_k", 40)),
+            "min_p": clamp(float(s.get("min_p", 0.0)), 0.0, 1.0),
+            "max_tokens": int(clamp(int(s.get("max_tokens", CFG.DEFAULT_MAX_TOKENS)), 16, 131072)),
+            "frequency_penalty": clamp(float(s.get("frequency_penalty", 0.0)), -2.0, 2.0),
+            "presence_penalty": clamp(float(s.get("presence_penalty", 0.0)), -2.0, 2.0),
+            "repetition_penalty": clamp(float(s.get("repetition_penalty", 1.0)), 0.0, 2.0),
+            "stream": stream,
+        }
+
+    @staticmethod
+    def _headers() -> Dict[str, str]:
+        key = CFG.HF_TOKEN or "EMPTY"
+        return {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+
+    # -- non-streaming completion ----------------------------------------------
+    def _complete_sync(self, messages: List[Dict[str, str]], s: Dict[str, Any]) -> str:
+        r = requests.post(
+            f"{CFG.VLLM_URL}/chat/completions",
+            headers=self._headers(),
+            json=self._payload(messages, s, stream=False),
+            timeout=CFG.LLM_TIMEOUT_S,
+        )
+        r.raise_for_status()
+        data = r.json()
+        usage = data.get("usage") or {}
+        METER.record(int(usage.get("completion_tokens", 0)))
+        return (data["choices"][0]["message"].get("content") or "").strip()
+
+    async def acomplete(self, messages: List[Dict[str, str]], s: Dict[str, Any]) -> str:
+        if not await self.healthy():
+            return self._mock_response(messages)
+        try:
+            return await asyncio.to_thread(self._complete_sync, messages, s)
+        except Exception as exc:
+            log.error("LLM completion failed: %s", exc)
+            return self._mock_response(messages)
+
+    # -- streaming completion ----------------------------------------------------
+    def _stream_sync(self, messages: List[Dict[str, str]], s: Dict[str, Any], q: "queue.Queue"):
+        import queue as _q  # local alias
+        try:
+            with requests.post(
+                f"{CFG.VLLM_URL}/chat/completions",
+                headers=self._headers(),
+                json=self._payload(messages, s, stream=True),
+                timeout=CFG.LLM_TIMEOUT_S,
+                stream=True,
+            ) as r:
+                r.raise_for_status()
+                for line in r.iter_lines(decode_unicode=True):
+                    if not line or not line.startswith("data:"):
+                        continue
+                    data = line[5:].strip()
+                    if data == "[DONE]":
+                        break
+                    try:
+                        chunk = json.loads(data)
+                        delta = (chunk["choices"][0].get("delta") or {}).get("content")
+                        if delta:
+                            q.put(delta)
+                    except Exception:
+                        continue
+        except Exception as exc:
+            q.put(exc)
+        finally:
+            q.put(None)
+
+    async def astream(
+        self, messages: List[Dict[str, str]], s: Dict[str, Any]
+    ) -> AsyncGenerator[str, None]:
+        if not await self.healthy():
+            async for piece in self._mock_stream(messages):
+                yield piece
+            return
+
+        import queue
+        q: "queue.Queue" = queue.Queue()
+        loop = asyncio.get_running_loop()
+        threading.Thread(target=self._stream_sync, args=(messages, s, q), daemon=True).start()
+        while True:
+            item = await asyncio.to_thread(q.get)
+            if item is None:
+                break
+            if isinstance(item, Exception):
+                log.error("LLM stream failed: %s", item)
+                async for piece in self._mock_stream(messages):
+                    yield piece
+                return
+            METER.record(approx_tokens(item))
+            yield item
+
+    # -- simulation engine (no-GPU fallback, always available) -------------------
+    @staticmethod
+    def _last_user(messages: List[Dict[str, str]]) -> str:
+        for m in reversed(messages):
+            if m.get("role") == "user":
+                return m.get("content", "")
+        return ""
+
+    def _mock_response(self, messages: List[Dict[str, str]]) -> str:
+        user = self._last_user(messages).strip()
+        excerpt = user[:300] + ("…" if len(user) > 300 else "")
+        return (
+            "⚙️ **Simulation engine** — the vLLM server is not reachable yet "
+            "(model still loading, or no GPU attached).\n\n"
+            f"**You asked:**\n> {excerpt or '(empty prompt)'}\n\n"
+            "**What I can tell you right now:**\n"
+            "- The NEXUS orchestrator is healthy and all APIs are live.\n"
+            "- Once the local model finishes loading, Flash/Max/Agents will stream "
+            "real tokens from it automatically.\n"
+            "- Set `MOCK_MODE=0` (default) to keep waiting for vLLM, or check "
+            "`vllm_server.log` in the sandbox for boot progress.\n\n"
+            "```python\n# quick probe you can run in the NEXUS console\n"
+            "curl -s http://127.0.0.1:8000/v1/models | head\n```"
+        )
+
+    async def _mock_stream(self, messages: List[Dict[str, str]]) -> AsyncGenerator[str, None]:
+        text = self._mock_response(messages)
+        for i in range(0, len(text), 6):
+            piece = text[i : i + 6]
+            METER.record(approx_tokens(piece))
+            yield piece
+            await asyncio.sleep(0.012)
+
+
+LLM = LLMClient()
+
+# ============================================================================
+# 10. PROMPT ASSEMBLY
+# ============================================================================
+BASE_SYSTEM = (
+    "You are NEXUS, an elite principal-level AI pair-programmer and systems architect "
+    "running locally on dedicated GPU infrastructure. You answer with precision, "
+    "write production-grade code with no placeholders, and explain trade-offs briefly. "
+    "Format answers in Markdown with fenced code blocks that include the language."
+)
+
+AGENT_ROLES: Dict[str, str] = {
+    "project_manager": (
+        "You are the PROJECT MANAGER agent. Decompose the request into a concrete, "
+        "ordered task list. Reply ONLY with a JSON array like "
+        '[{"agent":"coder","task":"..."}]. Valid agents: researcher, coder, debugger, '
+        "security, database, ui_ux. Max 5 tasks, no prose."
+    ),
+    "researcher": (
+        "You are the RESEARCHER agent. Gather the key facts, APIs, and prior art "
+        "relevant to the task. Output concise bullet points with source names."
+    ),
+    "coder": (
+        "You are the CODER agent. Write complete, production-ready code. Every file "
+        "in its own fenced block whose first line is a `# path: <filename>` comment."
+    ),
+    "debugger": (
+        "You are the DEBUGGER agent. Review the produced artifacts for runtime errors, "
+        "edge cases, race conditions and logic bugs. List each issue with its fix."
+    ),
+    "security": (
+        "You are the SECURITY agent. Audit the artifacts for injection, auth, secrets "
+        "handling, and unsafe defaults. Give a verdict plus concrete hardening steps."
+    ),
+    "database": (
+        "You are the DATABASE agent. Design schemas, write optimized SQL/libSQL "
+        "queries and indexes for the task."
+    ),
+    "ui_ux": (
+        "You are the UI/UX agent. Produce refined, responsive, accessible interface "
+        "code following the dark glassmorphic design system (#0B0F19, cyan accents)."
+    ),
+}
+
+
+async def build_messages(payload: Dict[str, Any], s: Dict[str, Any]) -> List[Dict[str, str]]:
+    parts: List[str] = [BASE_SYSTEM]
+
+    if s.get("persistent_instructions_enabled") and s.get("persistent_instructions"):
+        parts.append(f"Persistent instructions:\n{s['persistent_instructions']}")
+    if s.get("system_prompt_enabled") and s.get("system_prompt"):
+        parts.append(str(s["system_prompt"]))
+    if s.get("developer_prompt_enabled") and s.get("developer_prompt"):
+        parts.append(f"[Developer directive] {s['developer_prompt']}")
+    if s.get("user_profile"):
+        parts.append(f"[User profile] {s['user_profile']}")
+    if s.get("strict_instructions"):
+        parts.append("Follow every user instruction strictly and literally.")
+    lang = (s.get("language") or "auto").lower()
+    if lang != "auto":
+        parts.append(f"Always answer in {lang}.")
+
+    if s.get("use_memory"):
+        try:
+            rows = await DB.query("SELECT key, value FROM memories ORDER BY updated_at DESC LIMIT 10")
+            if rows:
+                mem = "\n".join(f"- {r['key']}: {r['value']}" for r in rows)
+                parts.append(f"[Long-term memory]\n{mem}")
+        except Exception:
+            pass
+
+    if s.get("citations") and s.get("web_search"):
+        parts.append("Cite sources inline as [1], [2]… matching the provided source list.")
+
+    messages: List[Dict[str, str]] = [{"role": "system", "content": "\n\n".join(parts)}]
+
+    # --- context window management (approximate) ------------------------------
+    budget = int(s.get("context_window", CFG.DEFAULT_CONTEXT_WINDOW)) - int(
+        s.get("max_tokens", CFG.DEFAULT_MAX_TOKENS)
+    )
+    budget_chars = max(4000, budget * 4)
+    history = list(payload.get("messages", []))
+    kept: List[Dict[str, str]] = []
+    total = 0
+    for m in reversed(history):
+        c = len(m.get("content", ""))
+        if total + c > budget_chars and kept:
+            break
+        kept.append(m)
+        total += c
+    kept.reverse()
+    for m in kept:
+        role = m.get("role") if m.get("role") in ("user", "assistant", "system") else "user"
+        messages.append({"role": role, "content": str(m.get("content", ""))[:60000]})
+    return messages
+
+# ============================================================================
+# 11. WEBSOCKET SEND HELPER
+# ============================================================================
+async def ws_send(ws: WebSocket, event: Dict[str, Any]) -> bool:
+    try:
+        await ws.send_text(json.dumps(event, ensure_ascii=False))
+        return True
+    except Exception:
+        return False
+
+
+# ============================================================================
+# 12. ENGINE — FLASH (direct low-latency streaming)
+# ============================================================================
+async def engine_flash(ws: WebSocket, payload: Dict[str, Any], s: Dict[str, Any]) -> str:
+    messages = await build_messages(payload, s)
+    acc = ""
+    async for piece in LLM.astream(messages, s):
+        acc += piece
+        if not await ws_send(ws, {"type": "token", "content": piece}):
+            break
+    return acc
+
+
+# ============================================================================
+# 13. ENGINE — MAX (visible deep-reasoning pipeline)
+# ============================================================================
+async def engine_max(ws: WebSocket, payload: Dict[str, Any], s: Dict[str, Any]) -> Tuple[str, List[Dict[str, str]]]:
+    user_q = ""
+    for m in reversed(payload.get("messages", [])):
+        if m.get("role") == "user":
+            user_q = m.get("content", "")
+            break
+
+    thinking_budget = int(s.get("thinking_budget", 1200))
+    think_s = dict(s)
+    think_s["max_tokens"] = thinking_budget
+    think_s["temperature"] = min(float(s.get("temperature", 0.7)), 0.5)
+    sources: List[Dict[str, str]] = []
+
+    # -- Step 1 · Planning ------------------------------------------------------
+    await ws_send(ws, {"type": "thinking", "step": "planning", "status": "working",
+                       "content": "Decomposing the problem into a reasoning plan…"})
+    plan = await LLM.acomplete(
+        [
+            {"role": "system", "content": "You are a meticulous planning engine. "
+             "Produce a numbered step-by-step plan to solve the user's request. "
+             "Be concrete and technical."},
+            {"role": "user", "content": user_q},
+        ],
+        think_s,
+    )
+    await ws_send(ws, {"type": "thinking", "step": "planning", "status": "done", "content": plan})
+
+    # -- Step 2 · Web research (optional) ---------------------------------------
+    research_digest = ""
+    if s.get("web_search"):
+        await ws_send(ws, {"type": "thinking", "step": "searching", "status": "working",
+                           "content": f"Searching the web for: {user_q[:120]}"})
+        depth = int(clamp(int(s.get("search_depth", 5)), 1, 10))
+        trusted_only = bool(s.get("trusted_sources")) and not s.get("deep_research")
+        sources = await asyncio.to_thread(ddg_search, user_q, depth, trusted_only)
+
+        digests: List[str] = []
+        if s.get("deep_research"):
+            for item in sources[:4]:
+                text = await asyncio.to_thread(fetch_page_text, item["url"], 4000)
+                if text:
+                    item["fetched"] = True
+                    digests.append(f"### {item['title']}\n{text[:2500]}")
+                else:
+                    digests.append(f"### {item['title']}\n{item['snippet']}")
+        else:
+            digests = [f"- {r['title']} — {r['snippet']} ({r['url']})" for r in sources]
+        research_digest = "\n\n".join(digests)
+        await ws_send(ws, {"type": "thinking", "step": "searching", "status": "done",
+                           "content": f"Collected {len(sources)} source(s)."
+                           + (f"\n\n{research_digest[:2000]}" if research_digest else "")})
+        await ws_send(ws, {"type": "citations", "items": sources})
+
+    # -- Step 3 · Deep reasoning --------------------------------------------------
+    await ws_send(ws, {"type": "thinking", "step": "reasoning", "status": "working",
+                       "content": "Reasoning through the plan with gathered evidence…"})
+    reasoning_input = (
+        f"PLAN:\n{plan}\n\n"
+        + (f"WEB EVIDENCE:\n{research_digest[:8000]}\n\n" if research_digest else "")
+        + f"USER REQUEST:\n{user_q}"
+    )
+    draft = await LLM.acomplete(
+        [
+            {"role": "system", "content": "You are a deep reasoning engine. Work through "
+             "the plan step by step and produce a thorough draft answer. Show your work."},
+            {"role": "user", "content": reasoning_input},
+        ],
+        think_s,
+    )
+    await ws_send(ws, {"type": "thinking", "step": "reasoning", "status": "done", "content": draft})
+
+    # -- Step 4 · Self-correction / reflection --------------------------------------
+    if s.get("reflection", True):
+        await ws_send(ws, {"type": "thinking", "step": "reflection", "status": "working",
+                           "content": "Critiquing the draft for errors and gaps…"})
+        critique = await LLM.acomplete(
+            [
+                {"role": "system", "content": "You are a ruthless self-critic. Review the "
+                 "draft answer: find factual errors, missing edge cases, and weak spots. "
+                 "Then list precise corrections."},
+                {"role": "user", "content": f"REQUEST:\n{user_q}\n\nDRAFT:\n{draft}"},
+            ],
+            think_s,
+        )
+        await ws_send(ws, {"type": "thinking", "step": "reflection", "status": "done", "content": critique})
+    else:
+        critique = ""
+
+    # -- Step 5 · Final streamed answer ----------------------------------------------
+    final_msgs = await build_messages(payload, s)
+    final_msgs.append(
+        {"role": "system", "content":
+            "You have already produced a plan, research digest, draft and self-critique "
+            "(provided below). Now write the FINAL polished answer for the user. "
+            "Incorporate the corrections; do not mention this meta-process.\n\n"
+            f"PLAN:\n{plan[:3000]}\n\nDRAFT:\n{draft[:6000]}\n\nCRITIQUE:\n{critique[:3000]}"}
+    )
+    acc = ""
+    async for piece in LLM.astream(final_msgs, s):
+        acc += piece
+        if not await ws_send(ws, {"type": "token", "content": piece}):
+            break
+    return acc, sources
+
+
+# ============================================================================
+# 14. ENGINE — AGENTS (autonomous specialist swarm)
+# ============================================================================
+DEFAULT_PLAN = [
+    {"agent": "researcher", "task": "Clarify requirements and gather key technical facts."},
+    {"agent": "coder", "task": "Implement the complete solution as production-ready files."},
+    {"agent": "debugger", "task": "Review the implementation for bugs and edge cases."},
+    {"agent": "security", "task": "Audit the implementation for vulnerabilities."},
+]
+
+
+def _parse_plan(text: str) -> List[Dict[str, str]]:
+    try:
+        m = re.search(r"\[.*\]", text, re.S)
+        if m:
+            data = json.loads(m.group(0))
+            plan = [
+                {"agent": str(t.get("agent", "coder")), "task": str(t.get("task", ""))[:500]}
+                for t in data if isinstance(t, dict) and t.get("task")
+            ]
+            if plan:
+                return plan[:5]
+    except Exception:
+        pass
+    return list(DEFAULT_PLAN)
+
+
+async def engine_agents(ws: WebSocket, payload: Dict[str, Any], s: Dict[str, Any]) -> str:
+    user_q = ""
+    for m in reversed(payload.get("messages", [])):
+        if m.get("role") == "user":
+            user_q = m.get("content", "")
+            break
+
+    agent_s = dict(s)
+    agent_s["max_tokens"] = min(int(s.get("max_tokens", CFG.DEFAULT_MAX_TOKENS)), 3000)
+    agent_s["temperature"] = min(float(s.get("temperature", 0.7)), 0.4)
+
+    # -- PM routing ---------------------------------------------------------------
+    await ws_send(ws, {"type": "agent", "agent": "project_manager", "status": "working",
+                       "content": "Analyzing the mission and assembling the swarm…"})
+    if s.get("multi_agent", True):
+        plan_text = await LLM.acomplete(
+            [
+                {"role": "system", "content": AGENT_ROLES["project_manager"]},
+                {"role": "user", "content": user_q},
+            ],
+            agent_s,
+        )
+        plan = _parse_plan(plan_text)
+    else:
+        plan = [{"agent": "coder", "task": user_q[:400]}]
+    pretty = "\n".join(f"{i+1}. **{t['agent']}** → {t['task']}" for i, t in enumerate(plan))
+    await ws_send(ws, {"type": "agent", "agent": "project_manager", "status": "done",
+                       "content": f"Mission plan ({len(plan)} task(s)):\n{pretty}"})
+
+    # -- Execution routing loop -----------------------------------------------------
+    artifacts: List[Dict[str, str]] = []
+    for idx, task in enumerate(plan, 1):
+        role = task["agent"] if task["agent"] in AGENT_ROLES else "coder"
+        await ws_send(ws, {"type": "agent", "agent": role, "status": "working",
+                           "content": f"[{idx}/{len(plan)}] {task['task']}"})
+        prior = ""
+        if artifacts:
+            prior = "\n\n".join(
+                f"[Output of {a['agent']}]\n{a['output'][:1500]}" for a in artifacts[-3:]
+            )
+        out = await LLM.acomplete(
+            [
+                {"role": "system", "content": AGENT_ROLES[role]},
+                {"role": "user", "content":
+                    f"MISSION:\n{user_q}\n\nYOUR TASK:\n{task['task']}\n\n"
+                    + (f"PRIOR AGENT OUTPUTS:\n{prior}" if prior else "")},
+            ],
+            agent_s,
+        )
+        artifacts.append({"agent": role, "task": task["task"], "output": out})
+        await ws_send(ws, {"type": "agent", "agent": role, "status": "done", "content": out})
+
+    # -- Final compilation ------------------------------------------------------------
+    await ws_send(ws, {"type": "status", "content": "Compiling the swarm's final deliverable…"})
+    compiled_context = "\n\n".join(
+        f"===== AGENT: {a['agent']} (task: {a['task']}) =====\n{a['output']}" for a in artifacts
+    )
+    final_msgs = [
+        {"role": "system", "content":
+            "You are the lead integrator of an AI agent swarm. Compile all agent outputs "
+            "into ONE coherent final deliverable: a short executive summary followed by the "
+            "complete artifacts (code files in fenced blocks with `# path:` headers). "
+            "Do not lose any code."},
+        {"role": "user", "content": f"MISSION:\n{user_q}\n\n{compiled_context[:20000]}"},
+    ]
+    acc = ""
+    async for piece in LLM.astream(final_msgs, s):
+        acc += piece
+        if not await ws_send(ws, {"type": "token", "content": piece}):
+            break
+
+    # -- Persist the project snapshot ---------------------------------------------------
+    try:
+        files = dict(re.findall(r"```[\w+-]*\n#\s*path:\s*(\S+)\n(.*?)```", acc, re.S))
+        await DB.execute(
+            "INSERT INTO sandbox_projects(id, name, files_json, updated_at) VALUES(?,?,?,datetime('now')) "
+            "ON CONFLICT(name) DO UPDATE SET files_json=excluded.files_json, updated_at=datetime('now')",
+            (new_id(), f"mission-{int(time.time())}", json.dumps(files, ensure_ascii=False)),
+        )
+    except Exception as exc:
+        log.warning("sandbox project persist failed: %s", exc)
+    return acc
+
+# ============================================================================
+# 15. FASTAPI APPLICATION
+# ============================================================================
+app = FastAPI(title=CFG.APP_NAME, version=CFG.VERSION, docs_url=None, redoc_url=None)
+app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+METRICS_CLIENTS: set = set()
+APP_START_TS = time.time()
+
+
+# ---------------------------------------------------------------------------
+# Middleware: hard-block any direct .html access without a valid session
+# ---------------------------------------------------------------------------
+@app.middleware("http")
+async def html_guard(request: Request, call_next):
+    path = request.url.path
+    if path.startswith("/static/") and path.endswith(".html") and not path.endswith("lockscreen.html"):
+        token = token_from_request(request)
+        if not token or not decode_token(token):
+            return FileResponse(str(STATIC_DIR / "lockscreen.html"), status_code=200)
+    return await call_next(request)
+
+
+# ---------------------------------------------------------------------------
+# Page serving (every page requires a valid session cookie/token)
+# ---------------------------------------------------------------------------
+def _page_or_lock(filename: str, request: Request):
+    token = token_from_request(request)
+    if token and decode_token(token):
+        return FileResponse(str(STATIC_DIR / filename))
+    return FileResponse(str(STATIC_DIR / "lockscreen.html"))
+
+
+@app.get("/", response_class=HTMLResponse)
+async def page_index(request: Request):
+    return _page_or_lock("index.html", request)
+
+
+@app.get("/usage", response_class=HTMLResponse)
+async def page_usage(request: Request):
+    return _page_or_lock("usage.html", request)
+
+
+@app.get("/logs", response_class=HTMLResponse)
+async def page_logs(request: Request):
+    return _page_or_lock("logs.html", request)
+
+
+@app.get("/console", response_class=HTMLResponse)
+async def page_console(request: Request):
+    return _page_or_lock("console.html", request)
+
+
+# ---------------------------------------------------------------------------
+# Auth API
+# ---------------------------------------------------------------------------
+@app.post("/api/auth/verify")
+async def auth_verify(body: AuthVerifyIn, request: Request):
+    ip = client_ip(request)
+    ua = request.headers.get("user-agent", "")[:300]
+    ok_token = hmac.compare_digest(body.token.strip(), CFG.ADMIN_API_KEY)
+    geo_ok, geo_reason = geo_verdict(body.latitude, body.longitude)
+    success = ok_token and geo_ok
+    reason = "ok" if success else ("bad master token" if not ok_token else geo_reason)
+
+    try:
+        await DB.execute(
+            "INSERT INTO auth_audit(ip, latitude, longitude, success, reason, user_agent) "
+            "VALUES(?,?,?,?,?,?)",
+            (ip, body.latitude, body.longitude, 1 if success else 0, reason, ua),
+        )
+    except Exception as exc:
+        log.warning("auth audit insert failed: %s", exc)
+
+    if not success:
+        log.warning("AUTH FAIL ip=%s reason=%s", ip, reason)
+        raise HTTPException(status_code=403, detail=f"access denied: {reason}")
+
+    token = issue_token(ip)
+    log.info("AUTH OK ip=%s geo=%s", ip, geo_reason)
+    resp = JSONResponse(
+        {
+            "ok": True,
+            "token": token,
+            "expires_in_hours": CFG.JWT_TTL_HOURS,
+            "geo": geo_reason,
+            "ip": ip,
+        }
+    )
+    resp.set_cookie(
+        CFG.SESSION_COOKIE, token,
+        max_age=CFG.JWT_TTL_HOURS * 3600, httponly=False, samesite="lax",
+    )
+    return resp
+
+
+@app.get("/api/auth/session")
+async def auth_session(session: Dict[str, Any] = Depends(require_session)):
+    return {
+        "ok": True,
+        "sub": session.get("sub"),
+        "ip": session.get("ip"),
+        "exp": session.get("exp"),
+        "model": CFG.MODEL_NAME,
+        "mock_mode": CFG.MOCK_MODE,
+        "db": DB.backend,
+        "vllm": await LLM.healthy(),
+        "version": CFG.VERSION,
+    }
+
+
+@app.post("/api/auth/logout")
+async def auth_logout():
+    resp = JSONResponse({"ok": True})
+    resp.delete_cookie(CFG.SESSION_COOKIE)
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# Health / info
+# ---------------------------------------------------------------------------
+@app.get("/api/health")
+async def health():
+    return {
+        "status": "ok",
+        "app": CFG.APP_NAME,
+        "version": CFG.VERSION,
+        "uptime_s": round(time.time() - APP_START_TS, 1),
+        "db": DB.backend,
+        "vllm": await LLM.healthy(),
+        "mock_mode": CFG.MOCK_MODE,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Chat persistence API
+# ---------------------------------------------------------------------------
+class ChatCreateIn(BaseModel):
+    title: str = Field("New chat", max_length=200)
+    mode: str = Field("flash", max_length=20)
+
+
+@app.get("/api/chats")
+async def list_chats(session: Dict[str, Any] = Depends(require_session)):
+    return await DB.query(
+        "SELECT id, title, mode, created_at, updated_at FROM chats "
+        "ORDER BY updated_at DESC LIMIT 100"
+    )
+
+
+@app.post("/api/chats")
+async def create_chat(body: ChatCreateIn, session: Dict[str, Any] = Depends(require_session)):
+    cid = new_id()
+    await DB.execute(
+        "INSERT INTO chats(id, user_id, title, mode) VALUES(?,?,?,?)",
+        (cid, session.get("sub", "admin"), body.title.strip() or "New chat", body.mode),
+    )
+    return {"id": cid, "title": body.title, "mode": body.mode}
+
+
+@app.get("/api/chats/{chat_id}/messages")
+async def chat_messages(chat_id: str, session: Dict[str, Any] = Depends(require_session)):
+    return await DB.query(
+        "SELECT id, role, content, mode, tokens, created_at FROM messages "
+        "WHERE chat_id=? ORDER BY created_at ASC, rowid ASC LIMIT 500",
+        (chat_id,),
+    )
+
+
+@app.delete("/api/chats/{chat_id}")
+async def delete_chat(chat_id: str, session: Dict[str, Any] = Depends(require_session)):
+    await DB.execute("DELETE FROM messages WHERE chat_id=?", (chat_id,))
+    await DB.execute("DELETE FROM chats WHERE id=?", (chat_id,))
+    return {"ok": True}
+
+
+@app.patch("/api/chats/{chat_id}")
+async def rename_chat(chat_id: str, body: ChatCreateIn, session: Dict[str, Any] = Depends(require_session)):
+    await DB.execute(
+        "UPDATE chats SET title=?, updated_at=datetime('now') WHERE id=?",
+        (body.title.strip() or "New chat", chat_id),
+    )
+    return {"ok": True}
+
+
+# ---------------------------------------------------------------------------
+# Memory API (Turso-backed long-term memory)
+# ---------------------------------------------------------------------------
+class MemoryIn(BaseModel):
+    key: str = Field(..., min_length=1, max_length=120)
+    value: str = Field(..., min_length=1, max_length=4000)
+
+
+@app.get("/api/memory")
+async def list_memory(session: Dict[str, Any] = Depends(require_session)):
+    return await DB.query("SELECT id, key, value, updated_at FROM memories ORDER BY updated_at DESC LIMIT 100")
+
+
+@app.post("/api/memory")
+async def upsert_memory(body: MemoryIn, session: Dict[str, Any] = Depends(require_session)):
+    await DB.execute(
+        "INSERT INTO memories(id, key, value, updated_at) VALUES(?,?,?,datetime('now')) "
+        "ON CONFLICT(key) DO UPDATE SET value=excluded.value, updated_at=datetime('now')",
+        (new_id(), body.key.strip(), body.value.strip()),
+    )
+    return {"ok": True}
+
+
+@app.delete("/api/memory/{key}")
+async def delete_memory(key: str, session: Dict[str, Any] = Depends(require_session)):
+    await DB.execute("DELETE FROM memories WHERE key=?", (key,))
+    return {"ok": True}
+
+
+# ---------------------------------------------------------------------------
+# Logs API + AI diagnostics + self-healing patch
+# ---------------------------------------------------------------------------
+@app.get("/api/logs")
+async def get_logs(
+    limit: int = Query(300, ge=1, le=2000),
+    level: str = Query("", max_length=10),
+    session: Dict[str, Any] = Depends(require_session),
+):
+    entries = list(LOG_BUFFER)
+    if level:
+        lv = level.upper()
+        entries = [e for e in entries if e["level"] == lv]
+    return entries[-limit:]
+
+
+class LogAnalyzeIn(BaseModel):
+    focus: str = Field("", max_length=1000)
+
+
+@app.post("/api/logs/analyze")
+async def analyze_logs(body: LogAnalyzeIn, session: Dict[str, Any] = Depends(require_session)):
+    entries = [e for e in LOG_BUFFER if e["level"] in ("ERROR", "WARNING", "CRITICAL")][-80:]
+    if not entries:
+        entries = list(LOG_BUFFER)[-40:]
+    blob = "\n".join(f"[{e['ts']}] {e['level']} {e['logger']}: {e['message']}" for e in entries)
+    analysis = await LLM.acomplete(
+        [
+            {"role": "system", "content":
+                "You are the NEXUS self-healing diagnostics agent. Analyze the system logs "
+                "below. Identify root causes, then propose concrete fixes (Python, Docker, "
+                "or configuration). If a fix requires rewriting a file, output it in a fenced "
+                "code block whose first line is `# path: <absolute path>`. Be surgical."
+                + (f"\nUser focus: {body.focus}" if body.focus else "")},
+            {"role": "user", "content": blob[:20000]},
+        ],
+        {"max_tokens": 1500, "temperature": 0.3, "model": CFG.MODEL_NAME},
+    )
+    return {"analyzed_entries": len(entries), "analysis": analysis}
+
+
+class PatchIn(BaseModel):
+    path: str = Field(..., min_length=1, max_length=500)
+    content: str = Field(..., max_length=400000)
+    confirm: bool = False
+
+
+ALLOWED_PATCH_ROOTS = (APP_ROOT, SANDBOX_DIR)
+
+
+def _resolve_jailed(path: str, roots=ALLOWED_PATCH_ROOTS) -> Path:
+    p = Path(path).resolve()
+    if not any(str(p).startswith(str(r)) for r in roots):
+        raise HTTPException(status_code=403, detail="path outside allowed roots")
+    return p
+
+
+@app.post("/api/logs/apply-patch")
+async def apply_patch(body: PatchIn, session: Dict[str, Any] = Depends(require_session)):
+    if not body.confirm:
+        raise HTTPException(status_code=400, detail="set confirm=true to apply the patch")
+    target = _resolve_jailed(body.path)
+    if not target.exists():
+        raise HTTPException(status_code=404, detail="target file does not exist")
+    backup = target.with_suffix(target.suffix + f".bak.{int(time.time())}")
+    shutil.copy2(target, backup)
+    target.write_text(body.content, encoding="utf-8")
+    log.warning("SELF-HEAL patch applied to %s (backup: %s)", target, backup)
+    return {"ok": True, "patched": str(target), "backup": str(backup)}
+
+
+@app.get("/api/logs/read-file")
+async def read_file_for_patch(path: str, session: Dict[str, Any] = Depends(require_session)):
+    target = _resolve_jailed(path)
+    if not target.is_file():
+        raise HTTPException(status_code=404, detail="not a file")
+    return {"path": str(target), "content": target.read_text(encoding="utf-8", errors="replace")[:400000]}
+
+
+# ---------------------------------------------------------------------------
+# Sandbox file manager + uploads (vision / OCR / PDF / code parsing)
+# ---------------------------------------------------------------------------
+TEXT_EXTS = {".py", ".js", ".ts", ".html", ".css", ".json", ".md", ".txt", ".sql",
+             ".csv", ".log", ".sh", ".yml", ".yaml", ".toml", ".env", ".cfg", ".xml"}
+IMG_EXTS = {".png", ".jpg", ".jpeg", ".webp", ".bmp", ".gif"}
+
+
+@app.get("/api/sandbox/tree")
+async def sandbox_tree(session: Dict[str, Any] = Depends(require_session)):
+    tree: List[Dict[str, Any]] = []
+    for p in sorted(SANDBOX_DIR.rglob("*")):
+        if p.is_file() and len(tree) < 500:
+            tree.append({
+                "path": str(p.relative_to(SANDBOX_DIR)),
+                "size": p.stat().st_size,
+                "modified": datetime.fromtimestamp(p.stat().st_mtime, timezone.utc).isoformat(timespec="seconds"),
+            })
+    return tree
+
+
+class SandboxFileIn(BaseModel):
+    path: str = Field(..., min_length=1, max_length=300)
+    content: str = Field("", max_length=400000)
+
+
+@app.get("/api/sandbox/file")
+async def sandbox_read(path: str, session: Dict[str, Any] = Depends(require_session)):
+    target = _resolve_jailed(str(SANDBOX_DIR / path), roots=(SANDBOX_DIR,))
+    if not target.is_file():
+        raise HTTPException(status_code=404, detail="not a file")
+    return {"path": path, "content": target.read_text(encoding="utf-8", errors="replace")[:400000]}
+
+
+@app.post("/api/sandbox/file")
+async def sandbox_write(body: SandboxFileIn, session: Dict[str, Any] = Depends(require_session)):
+    target = _resolve_jailed(str(SANDBOX_DIR / body.path), roots=(SANDBOX_DIR,))
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(body.content, encoding="utf-8")
+    log.info("sandbox file written: %s (%d bytes)", target, len(body.content))
+    return {"ok": True, "path": str(target.relative_to(SANDBOX_DIR))}
+
+
+@app.post("/api/upload")
+async def upload_file(file: UploadFile = File(...), session: Dict[str, Any] = Depends(require_session)):
+    safe_name = re.sub(r"[^A-Za-z0-9._-]+", "_", file.filename or "upload.bin")[:120]
+    dest = UPLOAD_DIR / f"{int(time.time())}_{safe_name}"
+    data = await file.read()
+    if len(data) > 40 * 1024 * 1024:
+        raise HTTPException(status_code=413, detail="file too large (40 MB max)")
+    dest.write_bytes(data)
+    ext = dest.suffix.lower()
+    kind, preview = "binary", ""
+
+    try:
+        if ext in TEXT_EXTS:
+            kind = "text"
+            preview = data.decode("utf-8", "replace")[:30000]
+        elif ext == ".pdf" and PdfReader is not None:
+            kind = "pdf"
+            reader = PdfReader(str(dest))
+            preview = "\n".join((pg.extract_text() or "") for pg in reader.pages[:20])[:30000]
+        elif ext in IMG_EXTS:
+            kind = "image"
+            if pytesseract is not None and Image is not None:
+                try:
+                    preview = pytesseract.image_to_string(Image.open(dest))[:10000]
+                    kind = "image+ocr"
+                except Exception:
+                    preview = ""
+    except Exception as exc:
+        log.warning("upload parse failed (%s): %s", safe_name, exc)
+
+    log.info("upload: %s kind=%s size=%d", safe_name, kind, len(data))
+    return {
+        "ok": True, "filename": safe_name, "kind": kind,
+        "size": len(data), "stored": str(dest.relative_to(SANDBOX_DIR)),
+        "preview": preview,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Metrics snapshot + broadcaster
+# ---------------------------------------------------------------------------
+def _gpu_stats() -> List[Dict[str, Any]]:
+    if GPUtil is None:
+        return []
+    try:
+        return [
+            {
+                "name": g.name, "load": round(g.load * 100, 1),
+                "mem_used_mb": round(g.memoryUsed, 1), "mem_total_mb": round(g.memoryTotal, 1),
+                "mem_percent": round(g.memoryUtil * 100, 1),
+                "temperature": round(g.temperature, 1),
+            }
+            for g in GPUtil.getGPUs()
+        ]
+    except Exception:
+        return []
+
+
+async def metrics_snapshot() -> Dict[str, Any]:
+    vm = psutil.virtual_memory()
+    proc = psutil.Process()
+    return {
+        "ts": utcnow(),
+        "cpu_percent": psutil.cpu_percent(interval=None),
+        "cpu_count": psutil.cpu_count(logical=True),
+        "ram": {"total_gb": round(vm.total / 1e9, 1), "used_gb": round(vm.used / 1e9, 1),
+                "percent": vm.percent},
+        "gpu": _gpu_stats(),
+        "threads": proc.num_threads(),
+        "proc_mem_mb": round(proc.memory_info().rss / 1e6, 1),
+        "tokens_per_sec": round(METER.rate(), 1),
+        "total_tokens": METER.total,
+        "uptime_s": round(time.time() - APP_START_TS, 0),
+        "vllm": await LLM.healthy(),
+        "db": DB.backend,
+        "mock_mode": CFG.MOCK_MODE,
+        "model": CFG.MODEL_NAME,
+    }
+
+
+@app.get("/api/metrics")
+async def metrics_http(session: Dict[str, Any] = Depends(require_session)):
+    return await metrics_snapshot()
+
+
+async def metrics_broadcaster() -> None:
+    psutil.cpu_percent(interval=None)  # prime the counter
+    while True:
+        try:
+            if METRICS_CLIENTS:
+                snap = await metrics_snapshot()
+                msg = json.dumps(snap)
+                dead = []
+                for ws in list(METRICS_CLIENTS):
+                    try:
+                        await ws.send_text(msg)
+                    except Exception:
+                        dead.append(ws)
+                for ws in dead:
+                    METRICS_CLIENTS.discard(ws)
+        except Exception as exc:
+            log.warning("metrics broadcast error: %s", exc)
+        await asyncio.sleep(2)
+
+
+@app.websocket("/ws/metrics")
+async def ws_metrics(ws: WebSocket):
+    if not ws_session(ws):
+        await ws.close(code=4401)
+        return
+    await ws.accept()
+    METRICS_CLIENTS.add(ws)
+    try:
+        await ws.send_text(json.dumps(await metrics_snapshot()))
+        while True:
+            await ws.receive_text()  # keepalive pings from the client
+    except WebSocketDisconnect:
+        pass
+    except Exception:
+        pass
+    finally:
+        METRICS_CLIENTS.discard(ws)
+
+# ---------------------------------------------------------------------------
+# Chat WebSocket — one connection per generation, JSON event protocol
+# ---------------------------------------------------------------------------
+async def _persist_chat_turn(chat_id: str, mode: str, user_text: str,
+                             assistant_text: str, title_hint: str) -> None:
+    try:
+        exists = await DB.query_one("SELECT id, title FROM chats WHERE id=?", (chat_id,))
+        if not exists:
+            await DB.execute(
+                "INSERT INTO chats(id, user_id, title, mode) VALUES(?,?,?,?)",
+                (chat_id, "nexus-admin", (title_hint[:80] or "New chat"), mode),
+            )
+        elif exists.get("title") == "New chat" and title_hint:
+            await DB.execute("UPDATE chats SET title=? WHERE id=?", (title_hint[:80], chat_id))
+        await DB.execute(
+            "INSERT INTO messages(id, chat_id, role, content, mode, tokens) VALUES(?,?,?,?,?,?)",
+            (new_id(), chat_id, "user", user_text, mode, approx_tokens(user_text)),
+        )
+        await DB.execute(
+            "INSERT INTO messages(id, chat_id, role, content, mode, tokens) VALUES(?,?,?,?,?,?)",
+            (new_id(), chat_id, "assistant", assistant_text, mode, approx_tokens(assistant_text)),
+        )
+        await DB.execute("UPDATE chats SET updated_at=datetime('now'), mode=? WHERE id=?",
+                         (mode, chat_id))
+    except Exception as exc:
+        log.warning("chat persist failed: %s", exc)
+
+
+@app.websocket("/ws/chat")
+async def ws_chat(ws: WebSocket):
+    session = ws_session(ws)
+    if not session:
+        await ws.close(code=4401)
+        return
+    await ws.accept()
+    log.info("chat ws connected (%s)", session.get("sub"))
+
+    try:
+        raw = await ws.receive_text()
+        payload = json.loads(raw)
+        mode = str(payload.get("mode", "flash")).lower()
+        s: Dict[str, Any] = payload.get("settings") or {}
+        profile = str(s.get("safety_profile", "balanced"))
+
+        # ---- Safety gate on the incoming user turn --------------------------
+        user_text = ""
+        for m in reversed(payload.get("messages", [])):
+            if m.get("role") == "user":
+                user_text = str(m.get("content", ""))
+                break
+        ok_in, violations, sanitized = SAFETY.scan(user_text, profile)
+        if not ok_in:
+            await ws_send(ws, {"type": "error",
+                               "content": f"🛡️ Blocked by the **{profile}** safety profile: "
+                                          f"{', '.join(violations)}"})
+            await ws_send(ws, {"type": "done", "chat_id": None, "usage": {}})
+            await ws.close()
+            return
+        if sanitized != user_text:
+            for m in payload.get("messages", []):
+                if m.get("role") == "user" and m.get("content") == user_text:
+                    m["content"] = sanitized
+            await ws_send(ws, {"type": "status", "content": "PII redacted by safety profile."})
+
+        await ws_send(ws, {"type": "status", "content": f"Engine `{mode}` engaged…"})
+
+        # ---- Route to the selected engine ------------------------------------
+        sources: List[Dict[str, str]] = []
+        if mode == "max":
+            answer, sources = await engine_max(ws, payload, s)
+        elif mode == "agents":
+            answer = await engine_agents(ws, payload, s)
+        else:
+            mode = "flash"
+            answer = await engine_flash(ws, payload, s)
+
+        # ---- Safety gate on the outgoing answer --------------------------------
+        ok_out, out_violations, clean_answer = SAFETY.scan(answer, profile)
+        if not ok_out:
+            await ws_send(ws, {"type": "replace",
+                               "content": f"🛡️ The generated answer was withheld by the "
+                                          f"**{profile}** safety profile ({', '.join(out_violations)})."})
+            answer = ""
+        elif clean_answer != answer:
+            answer = clean_answer
+            await ws_send(ws, {"type": "replace", "content": answer})
+
+        # ---- Persist + finish ------------------------------------------------------
+        chat_id = str(payload.get("chat_id") or new_id())
+        await _persist_chat_turn(chat_id, mode, user_text, answer, user_text[:80])
+        await ws_send(ws, {
+            "type": "done",
+            "chat_id": chat_id,
+            "mode": mode,
+            "citations": sources,
+            "usage": {
+                "completion_tokens_est": approx_tokens(answer),
+                "session_total_tokens": METER.total,
+                "tokens_per_sec": round(METER.rate(), 1),
+            },
+        })
+    except WebSocketDisconnect:
+        log.info("chat ws disconnected mid-generation")
+    except json.JSONDecodeError:
+        await ws_send(ws, {"type": "error", "content": "Malformed payload (expected JSON)."})
+    except Exception as exc:
+        log.error("chat ws error: %s\n%s", exc, traceback.format_exc())
+        await ws_send(ws, {"type": "error", "content": f"Internal error: {exc}"})
+    finally:
+        try:
+            await ws.close()
+        except Exception:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Terminal WebSocket — jailed bash emulator
+# ---------------------------------------------------------------------------
+TERMINAL_BLOCKLIST = re.compile(
+    r"(rm\s+-[rf]{1,2}\s+/(?:\s|$)|\bmkfs\b|\bdd\s+if=|\bshutdown\b|\breboot\b"
+    r"|\bhalt\b|\bpoweroff\b|:\(\)\s*\{|\bfork\b\s*\|\s*\bfork\b"
+    r"|>\s*/dev/sd|chmod\s+-R\s+777\s+/)",
+    re.IGNORECASE,
+)
+
+SECRET_ENV_KEYS = ("TURSO_AUTH_TOKEN", "ADMIN_API_KEY", "JWT_SECRET", "HF_TOKEN")
+
+
+def _terminal_env() -> Dict[str, str]:
+    env = dict(os.environ)
+    for k in list(env):
+        if any(sec in k for sec in SECRET_ENV_KEYS):
+            env.pop(k, None)
+    env["PS1"] = ""
+    env["TERM"] = "xterm-256color"
+    return env
+
+
+def _clamp_cwd(path: Path) -> Path:
+    try:
+        resolved = path.resolve()
+        resolved.relative_to(SANDBOX_DIR)
+        return resolved
+    except Exception:
+        return SANDBOX_DIR
+
+
+@app.websocket("/ws/terminal")
+async def ws_terminal(ws: WebSocket):
+    if not ws_session(ws):
+        await ws.close(code=4401)
+        return
+    await ws.accept()
+    cwd = SANDBOX_DIR
+    env = _terminal_env()
+    await ws_send(ws, {"type": "banner",
+                       "content": f"NEXUS secure shell — jailed to {SANDBOX_DIR}\n"
+                                  f"Type commands. `cd` is supported. Ctrl-D or `exit` closes.\r\n"})
+    try:
+        while True:
+            data = json.loads(await ws.receive_text())
+            cmd = str(data.get("cmd", "")).rstrip()
+            if not cmd:
+                continue
+            if cmd.strip() in ("exit", "logout"):
+                await ws_send(ws, {"type": "exit", "code": 0})
+                break
+            if TERMINAL_BLOCKLIST.search(cmd):
+                await ws_send(ws, {"type": "output",
+                                   "data": f"\r\n\x1b[31m[shield] command blocked for safety: {cmd}\x1b[0m\r\n"})
+                await ws_send(ws, {"type": "exit", "code": 126, "cwd": str(cwd)})
+                continue
+
+            # ---- built-in cd (persistent per connection) -----------------------
+            m = re.match(r"^\s*cd(?:\s+(.*))?$", cmd)
+            if m:
+                target = (m.group(1) or "").strip().strip('"').strip("'")
+                new_cwd = _clamp_cwd((cwd / target) if target else SANDBOX_DIR)
+                if new_cwd.is_dir():
+                    cwd = new_cwd
+                    await ws_send(ws, {"type": "exit", "code": 0, "cwd": str(cwd)})
+                else:
+                    await ws_send(ws, {"type": "output",
+                                       "data": f"\r\ncd: no such directory: {target}\r\n"})
+                    await ws_send(ws, {"type": "exit", "code": 1, "cwd": str(cwd)})
+                continue
+
+            # ---- execute ----------------------------------------------------------
+            log.info("terminal exec: %s (cwd=%s)", cmd[:200], cwd)
+            try:
+                proc = await asyncio.create_subprocess_shell(
+                    cmd,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.STDOUT,
+                    cwd=str(cwd),
+                    env=env,
+                    limit=CFG.TERMINAL_MAX_OUTPUT,
+                )
+            except Exception as exc:
+                await ws_send(ws, {"type": "output", "data": f"\r\nspawn failed: {exc}\r\n"})
+                await ws_send(ws, {"type": "exit", "code": 127, "cwd": str(cwd)})
+                continue
+
+            produced = 0
+            timed_out = False
+            start = time.time()
+            assert proc.stdout is not None
+            while True:
+                if time.time() - start > CFG.TERMINAL_TIMEOUT_S:
+                    timed_out = True
+                    try:
+                        proc.kill()
+                    except Exception:
+                        pass
+                    break
+                try:
+                    chunk = await asyncio.wait_for(proc.stdout.read(4096), timeout=1.0)
+                except asyncio.TimeoutError:
+                    if proc.returncode is not None:
+                        break
+                    continue
+                if not chunk:
+                    break
+                produced += len(chunk)
+                if produced > CFG.TERMINAL_MAX_OUTPUT:
+                    await ws_send(ws, {"type": "output",
+                                       "data": "\r\n\x1b[33m[truncated: output limit reached]\x1b[0m\r\n"})
+                    try:
+                        proc.kill()
+                    except Exception:
+                        pass
+                    break
+                await ws_send(ws, {"type": "output",
+                                   "data": chunk.decode("utf-8", "replace")})
+            try:
+                code = await asyncio.wait_for(proc.wait(), timeout=5)
+            except Exception:
+                code = proc.returncode if proc.returncode is not None else -9
+            if timed_out:
+                await ws_send(ws, {"type": "output",
+                                   "data": f"\r\n\x1b[33m[killed: timeout {CFG.TERMINAL_TIMEOUT_S}s]\x1b[0m\r\n"})
+                code = 124
+            await ws_send(ws, {"type": "exit", "code": code, "cwd": str(cwd)})
+    except WebSocketDisconnect:
+        pass
+    except Exception as exc:
+        log.error("terminal ws error: %s", exc)
+    finally:
+        try:
+            await ws.close()
+        except Exception:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Startup / shutdown
+# ---------------------------------------------------------------------------
+@app.on_event("startup")
+async def on_startup() -> None:
+    log.info("=" * 70)
+    log.info(" %s v%s booting…", CFG.APP_NAME, CFG.VERSION)
+    log.info(" model=%s mock=%s vllm=%s", CFG.MODEL_NAME, CFG.MOCK_MODE, CFG.VLLM_URL)
+    if _AUTO_KEY:
+        log.warning("!" * 70)
+        log.warning("ADMIN_API_KEY was NOT set — generated an ephemeral master key:")
+        log.warning("  >>>  %s  <<<", CFG.ADMIN_API_KEY)
+        log.warning("Set the ADMIN_API_KEY secret for a stable credential.")
+        log.warning("!" * 70)
+    await DB.connect()
+    asyncio.create_task(metrics_broadcaster())
+    log.info("startup complete — serving on port %d", CFG.PORT)
+
+
+@app.on_event("shutdown")
+async def on_shutdown() -> None:
+    log.info("shutting down…")
+    DB.close()
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("main:app", host="0.0.0.0", port=CFG.PORT, log_level="info")

package-lock.json

@@ -0,0 +1,6 @@
+{
+  "name": "app",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}

requirements.txt

@@ -0,0 +1,36 @@
+# ============================================================================
+#  NEXUS AI — Python dependencies
+# ============================================================================
+
+# ---- Web framework / ASGI server ------------------------------------------
+fastapi>=0.110.0,<1.0.0
+uvicorn[standard]>=0.29.0
+websockets>=12.0
+python-multipart>=0.0.9          # file uploads (vision / code parsing)
+
+# ---- Local LLM inference (OpenAI-compatible server, A100 optimized) -------
+vllm>=0.6.3,<0.8.0 ; platform_system == "Linux"
+
+# ---- Turso / libSQL database (falls back to local file when unset) --------
+libsql-client>=0.3.1
+
+# ---- Security --------------------------------------------------------------
+pyjwt>=2.8.0
+cryptography>=42.0.0
+
+# ---- System monitoring -----------------------------------------------------
+psutil>=5.9.8
+GPUtil>=1.4.0
+
+# ---- Web research (Max engine) --------------------------------------------
+requests>=2.31.0
+beautifulsoup4>=4.12.3
+lxml>=5.1.0
+
+# ---- File understanding (uploads) -----------------------------------------
+pypdf>=4.2.0
+pytesseract>=0.3.10
+Pillow>=10.2.0
+
+# ---- Validation ------------------------------------------------------------
+pydantic>=2.6.0