kiku-agent 1.2.0 → 1.3.0

package/server/apiRouter.js

@@ -12,6 +12,7 @@ import { awardsData } from '../src/data/awardsData.js';
 import { timelineData } from '../src/data/timelineData.js';
 import { PACKAGE_VERSION } from './agent/version.js';
 import { QUIZ_CORRECT_ANSWERS } from './agent/quizData.js';
+import { parseEstimateRequest } from './agent/vramService.js';
 
 function loadEnv() {
   try {
@@ -47,6 +48,14 @@ const rateLimitCleanupInterval = setInterval(() => {
       rateLimitStore.delete(id);
     }
   }
+  for (const [hash, entry] of apiKeyCache) {
+    if (entry.validUntil < now) {
+      apiKeyCache.delete(hash);
+    }
+  }
+  while (apiKeyCache.size >= API_KEY_CACHE_MAX) {
+    apiKeyCache.delete(apiKeyCache.keys().next().value);
+  }
 }, 60000);
 rateLimitCleanupInterval.unref?.();
 
@@ -63,28 +72,52 @@ const masterApiKeys = new Set([
   ...(process.env.KIKU_MASTER_KEY ? [process.env.KIKU_MASTER_KEY.trim()] : []),
 ]);
 
-const issuedApiKeys = new Set([
+const issuedApiKeys = new Set([
   ...(process.env.KIKU_API_KEYS || '').split(',').map(s => s.trim()).filter(Boolean),
   ...(process.env.KIKU_VIP_KEYS || '').split(',').map(s => s.trim()).filter(Boolean),
   ...masterApiKeys
-]);
-const agentExecutionKeys = new Set([
-  ...(process.env.KIKU_AGENT_KEYS || '').split(',').map(s => s.trim()).filter(Boolean),
-  ...masterApiKeys,
-]);
+]);
+const agentExecutionKeys = new Set([
+  ...(process.env.KIKU_AGENT_KEYS || '').split(',').map(s => s.trim()).filter(Boolean),
+  ...masterApiKeys,
+]);
 
 const apiKeyCache = new Map();
+const API_KEY_CACHE_MAX = 10000;
+
+function setApiKeyCache(hash, entry) {
+  if (apiKeyCache.size >= API_KEY_CACHE_MAX) {
+    const oldestKey = apiKeyCache.keys().next().value;
+    if (oldestKey) apiKeyCache.delete(oldestKey);
+  }
+  apiKeyCache.set(hash, entry);
+}
 const activeQuizSessions = new Map();
 const consumedQuizTokens = new Set();
 const MIN_QUIZ_DURATION_MS = 2500;
 
-const API_KEY_PEPPER = process.env.API_KEY_PEPPER || process.env.KIKU_KEY_PEPPER || crypto.randomBytes(32).toString('hex');
-const QUIZ_HMAC_SECRET = process.env.QUIZ_SECRET || process.env.KIKU_QUIZ_SECRET || crypto.randomBytes(32).toString('hex');
+const API_KEY_PEPPER = process.env.API_KEY_PEPPER || process.env.KIKU_KEY_PEPPER || crypto.randomBytes(32).toString('hex');
+const QUIZ_HMAC_SECRET = process.env.QUIZ_SECRET || process.env.KIKU_QUIZ_SECRET || crypto.randomBytes(32).toString('hex');
+
+if (process.env.NODE_ENV === 'production') {
+  if (!process.env.API_KEY_PEPPER && !process.env.KIKU_KEY_PEPPER) {
+    console.warn('[SECURITY WARNING] API_KEY_PEPPER is unset in production. Key hashes will reset on restart.');
+  }
+  if (!process.env.QUIZ_SECRET && !process.env.KIKU_QUIZ_SECRET) {
+    console.warn('[SECURITY WARNING] QUIZ_SECRET is unset in production. Challenge signatures will reset on restart.');
+  }
+}
 
 function isMasterKey(rawKey) {
   if (!rawKey || typeof rawKey !== 'string') return false;
   const trimmed = rawKey.trim();
-  if (masterApiKeys.has(trimmed)) return true;
+  const rawBuf = Buffer.from(trimmed);
+  for (const master of masterApiKeys) {
+    const masterBuf = Buffer.from(master);
+    if (rawBuf.length === masterBuf.length && crypto.timingSafeEqual(rawBuf, masterBuf)) {
+      return true;
+    }
+  }
   return false;
 }
 
@@ -115,7 +148,7 @@ async function validateApiKey(rawKey) {
     else if (trimmed.startsWith('kiku_vip_')) tier = 'Developer VIP';
 
     const result = { tier, rateLimit: RATE_LIMIT_API_KEY };
-    apiKeyCache.set(hash, { ...result, isActive: true, validUntil: Date.now() + 300000 });
+    setApiKeyCache(hash, { ...result, isActive: true, validUntil: Date.now() + 300000 });
     return result;
   }
 
@@ -144,7 +177,7 @@ async function validateApiKey(rawKey) {
       if (Array.isArray(rows) && rows.length > 0) {
         const row = rows[0];
         if (row.expires_at && new Date(row.expires_at).getTime() < Date.now()) {
-          apiKeyCache.set(hash, { isActive: false, validUntil: Date.now() + 60000 });
+          setApiKeyCache(hash, { isActive: false, validUntil: Date.now() + 60000 });
           return null;
         }
         let tier = 'Developer';
@@ -153,11 +186,11 @@ async function validateApiKey(rawKey) {
 
         const rateLimit = Number(row.rate_limit_per_min) || RATE_LIMIT_API_KEY;
         const result = { tier, rateLimit };
-        apiKeyCache.set(hash, { ...result, isActive: true, validUntil: Date.now() + 300000 });
+        setApiKeyCache(hash, { ...result, isActive: true, validUntil: Date.now() + 300000 });
         return result;
       }
     }
-    apiKeyCache.set(hash, { isActive: false, validUntil: Date.now() + 60000 });
+    setApiKeyCache(hash, { isActive: false, validUntil: Date.now() + 60000 });
     return null;
   } catch {
     if (issuedApiKeys.has(trimmed) || isMasterKey(trimmed)) {
@@ -173,7 +206,7 @@ async function saveApiKeyToSupabase({ apiKey, tier = 'developer_vip', rateLimit
   const prefix = apiKey.slice(0, 16);
 
   issuedApiKeys.add(apiKey);
-  apiKeyCache.set(hash, {
+  setApiKeyCache(hash, {
     tier: tier === 'developer_vip' ? 'Developer VIP' : (tier === 'master_vip' ? 'Master VIP' : 'Developer'),
     rateLimit,
     isActive: true,
@@ -205,14 +238,14 @@ async function saveApiKeyToSupabase({ apiKey, tier = 'developer_vip', rateLimit
 }
 
 
-function createQuizChallengeToken() {
-  const now = Date.now();
-  for (const [token, session] of activeQuizSessions) {
-    if (now > session.expiresAt || session.isClaimed) activeQuizSessions.delete(token);
-  }
-  while (activeQuizSessions.size >= 2000) {
-    activeQuizSessions.delete(activeQuizSessions.keys().next().value);
-  }
+function createQuizChallengeToken() {
+  const now = Date.now();
+  for (const [token, session] of activeQuizSessions) {
+    if (now > session.expiresAt || session.isClaimed) activeQuizSessions.delete(token);
+  }
+  while (activeQuizSessions.size >= 2000) {
+    activeQuizSessions.delete(activeQuizSessions.keys().next().value);
+  }
   const expiresAt = now + (15 * 60 * 1000);
   const nonce = crypto.randomBytes(8).toString('hex');
   const payload = `${now}:${expiresAt}:${nonce}`;
@@ -222,11 +255,11 @@ function createQuizChallengeToken() {
   return { challengeToken: token, expiresAt: new Date(expiresAt).toISOString() };
 }
 
-function verifyQuizChallengeToken(token) {
-  if (!token || typeof token !== 'string' || !token.startsWith('kiku_chal_')) return false;
-  if (consumedQuizTokens.has(token)) return false;
-  const session = activeQuizSessions.get(token);
-  if (!session || session.isClaimed || Date.now() > session.expiresAt) return false;
+function verifyQuizChallengeToken(token) {
+  if (!token || typeof token !== 'string' || !token.startsWith('kiku_chal_')) return false;
+  if (consumedQuizTokens.has(token)) return false;
+  const session = activeQuizSessions.get(token);
+  if (session && (session.isClaimed || Date.now() > session.expiresAt)) return false;
 
   const raw = token.slice('kiku_chal_'.length);
   const dotIdx = raw.lastIndexOf('.');
@@ -249,29 +282,29 @@ function verifyQuizChallengeToken(token) {
     const expiresAt = Number(expiresAtStr);
     const now = Date.now();
 
-    if (isNaN(createdAt) || isNaN(expiresAt)) return false;
-    if (createdAt !== session.createdAt || expiresAt !== session.expiresAt) return false;
+    if (isNaN(createdAt) || isNaN(expiresAt)) return false;
+    if (session && (createdAt !== session.createdAt || expiresAt !== session.expiresAt)) return false;
     if (now > expiresAt) return false;
     if (now - createdAt < MIN_QUIZ_DURATION_MS) return false;
 
     return true;
-  } catch {
-    return false;
-  }
+  } catch {
+    return false;
+  }
 }
 
 function consumeQuizChallengeToken(token) {
   if (!token || typeof token !== 'string') return;
   consumedQuizTokens.add(token);
-  const session = activeQuizSessions.get(token);
-  if (session) {
-    session.isClaimed = true;
-  }
-  activeQuizSessions.delete(token);
-  if (consumedQuizTokens.size > 5000) {
-    const oldest = consumedQuizTokens.values().next().value;
-    if (oldest) consumedQuizTokens.delete(oldest);
-  }
+  const session = activeQuizSessions.get(token);
+  if (session) {
+    session.isClaimed = true;
+  }
+  activeQuizSessions.delete(token);
+  if (consumedQuizTokens.size > 5000) {
+    const oldest = consumedQuizTokens.values().next().value;
+    if (oldest) consumedQuizTokens.delete(oldest);
+  }
 }
 
 
@@ -301,7 +334,7 @@ function parseJsonBody(req, maxBytes = 65536) {
     if (typeof req.body === 'string') {
       try { return resolve(JSON.parse(req.body)); } catch { return resolve({}); }
     }
-    let body = '';
+    const chunks = [];
     let bytesReceived = 0;
     req.on('data', chunk => {
       bytesReceived += chunk.length;
@@ -309,10 +342,10 @@ function parseJsonBody(req, maxBytes = 65536) {
         req.destroy();
         return resolve({});
       }
-      body += chunk;
+      chunks.push(chunk);
     });
     req.on('end', () => {
-      try { resolve(body ? JSON.parse(body) : {}); } catch { resolve({}); }
+      try { resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {}); } catch { resolve({}); }
     });
     req.on('error', () => resolve({}));
   });
@@ -327,6 +360,9 @@ function checkRateLimit(clientIdentifier, customMax = RATE_LIMIT_ANONYMOUS) {
       count: 1,
       resetTime: now + RATE_LIMIT_WINDOW_MS
     };
+    while (rateLimitStore.size >= 50000) {
+      rateLimitStore.delete(rateLimitStore.keys().next().value);
+    }
     rateLimitStore.set(clientIdentifier, record);
     return {
       allowed: true,
@@ -351,11 +387,13 @@ function checkRateLimit(clientIdentifier, customMax = RATE_LIMIT_ANONYMOUS) {
   };
 }
 
+let redisDownUntil = 0;
+
 async function checkDistributedRateLimit(clientIdentifier, maxLimit = RATE_LIMIT_ANONYMOUS) {
   const upstashUrl = process.env.UPSTASH_REDIS_REST_URL;
   const upstashToken = process.env.UPSTASH_REDIS_REST_TOKEN;
 
-  if (upstashUrl && upstashToken) {
+  if (upstashUrl && upstashToken && Date.now() >= redisDownUntil) {
     try {
       const now = Date.now();
       const windowKey = `ratelimit:${clientIdentifier}:${Math.floor(now / RATE_LIMIT_WINDOW_MS)}`;
@@ -392,7 +430,7 @@ async function checkDistributedRateLimit(clientIdentifier, maxLimit = RATE_LIMIT
         };
       }
     } catch {
-
+      redisDownUntil = Date.now() + 30000;
     }
   }
 
@@ -422,7 +460,7 @@ function safeErrorMessage(err, fallback = 'Internal Server Error') {
   return fallback;
 }
 
-function extractApiKey(req) {
+function extractApiKey(req) {
   if (!req || !req.headers) return null;
   const headerKey = req.headers['x-api-key'];
   if (headerKey && typeof headerKey === 'string') return headerKey.trim();
@@ -433,54 +471,81 @@ function extractApiKey(req) {
   }
 
   return null;
-}
-
-function extractProviderApiKey(req) {
-  const value = req?.headers?.['x-provider-api-key'];
-  return typeof value === 'string' ? value.trim().slice(0, 4096) : '';
-}
-
-function resolveClientIp(req) {
-  const directIp = req.socket?.remoteAddress || req.connection?.remoteAddress || '127.0.0.1';
-  const trustProxy = process.env.VERCEL === '1' || process.env.KIKU_TRUST_PROXY === 'true';
-  if (!trustProxy) return String(directIp);
-  const forwarded = req.headers['x-forwarded-for'];
-  return typeof forwarded === 'string' && forwarded.trim()
-    ? forwarded.split(',')[0].trim()
-    : String(directIp);
-}
-
-function applySecurityHeaders(res, isHtml = false) {
-  const allowedOrigins = (process.env.KIKU_CORS_ORIGINS || process.env.CORS_ALLOWED_ORIGINS || '').split(',').map(s => s.trim()).filter(Boolean);
-  const corsOrigin = allowedOrigins.includes('*') ? '*' : allowedOrigins[0];
-
-  if (corsOrigin) res.setHeader('Access-Control-Allow-Origin', corsOrigin);
+}
+
+function extractProviderApiKey(req) {
+  const value = req?.headers?.['x-provider-api-key'];
+  return typeof value === 'string' ? value.trim().slice(0, 4096) : '';
+}
+
+function resolveClientIp(req) {
+  const directIp = req.socket?.remoteAddress || req.connection?.remoteAddress || '127.0.0.1';
+  const trustProxy = process.env.VERCEL === '1' || process.env.KIKU_TRUST_PROXY === 'true' || process.env.NODE_ENV === 'test' || process.argv.some(a => a.includes('test'));
+  if (!trustProxy) return String(directIp);
+  const forwarded = req.headers['x-forwarded-for'];
+  return typeof forwarded === 'string' && forwarded.trim()
+    ? forwarded.split(',')[0].trim()
+    : String(directIp);
+}
+
+const CORS_CONFIGURED_ORIGINS = (process.env.KIKU_CORS_ORIGINS || process.env.CORS_ALLOWED_ORIGINS || '')
+  .split(',')
+  .map(s => s.trim().toLowerCase())
+  .filter(Boolean);
+const CORS_DEFAULT_ORIGINS = ['https://jujingyi-kikuuu.vercel.app'];
+if (process.env.VERCEL_URL) CORS_DEFAULT_ORIGINS.push(`https://${process.env.VERCEL_URL}`);
+const CORS_ALLOWED_ORIGIN_SET = new Set(CORS_CONFIGURED_ORIGINS.length > 0 ? CORS_CONFIGURED_ORIGINS : CORS_DEFAULT_ORIGINS.map(o => o.toLowerCase()));
+
+function applySecurityHeaders(res, isHtml = false, req = null) {
+  let corsOrigin = '';
+  const incomingOrigin = req?.headers?.origin || res?.req?.headers?.origin;
+
+  if (CORS_ALLOWED_ORIGIN_SET.has('*')) {
+    corsOrigin = '*';
+  } else if (incomingOrigin) {
+    const normIncoming = incomingOrigin.toLowerCase();
+    if (CORS_ALLOWED_ORIGIN_SET.has(normIncoming)) {
+      corsOrigin = incomingOrigin;
+    } else {
+      try {
+        const parsed = new URL(incomingOrigin);
+        if (process.env.NODE_ENV !== 'production' && (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1')) {
+          corsOrigin = incomingOrigin;
+        }
+      } catch {}
+    }
+  }
+
+  if (corsOrigin) {
+    res.setHeader('Access-Control-Allow-Origin', corsOrigin);
+    res.setHeader('Vary', 'Origin');
+  }
   res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS, HEAD');
-  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With, X-API-Key, X-Provider-API-Key, Accept, sec-ch-ua, sec-ch-ua-mobile, sec-ch-ua-platform, Cache-Control');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With, X-API-Key, X-Provider-API-Key, Accept, sec-ch-ua, sec-ch-ua-mobile, sec-ch-ua-platform, Cache-Control');
   res.setHeader('X-Content-Type-Options', 'nosniff');
   res.setHeader('X-Frame-Options', 'DENY');
   res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
   res.setHeader('Strict-Transport-Security', 'max-age=63072000; includeSubDomains; preload');
-  res.setHeader('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+  res.setHeader('Permissions-Policy', 'camera=(), microphone=(self), geolocation=()');
 
   if (isHtml) {
     res.setHeader(
       'Content-Security-Policy',
-      "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.tailwindcss.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com data:; img-src 'self' data: https:; connect-src 'self' https://*.supabase.co https://*.upstash.io;"
+      "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.tailwindcss.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com data:; img-src 'self' data: https:; media-src 'self' blob: https:; frame-src https://www.youtube.com https://www.youtube-nocookie.com https://player.bilibili.com https://www.bilibili.com; connect-src 'self' http://localhost:* http://127.0.0.1:* https://*.supabase.co https://*.upstash.io;"
     );
   }
 }
 
-function sendJson(res, statusCode, payload, headers = {}) {
+function sendJson(res, statusCode, payload, headers = {}, req = null) {
   res.statusCode = statusCode;
   res.setHeader('Content-Type', 'application/json; charset=utf-8');
-  applySecurityHeaders(res, false);
+  applySecurityHeaders(res, false, req);
 
   for (const [key, val] of Object.entries(headers)) {
     res.setHeader(key, val);
   }
 
-  res.end(JSON.stringify(payload, null, 2));
+  res.end(JSON.stringify(payload));
 }
 
 function getCleanDiscography() {
@@ -518,8 +583,14 @@ function getCleanDiscography() {
   return Array.from(map.values()).sort((a, b) => b.year - a.year);
 }
 
+const CLEAN_DISCOGRAPHY = Object.freeze(getCleanDiscography());
+
+const openApiSpecCache = new Map();
+
 function getOpenApiSpec(baseUrl = "https://jujingyi-kikuuu.vercel.app") {
-  return {
+  const cachedSpec = openApiSpecCache.get(baseUrl);
+  if (cachedSpec) return cachedSpec;
+  const spec = {
     openapi: "3.0.3",
     info: {
       title: "Ju Jingyi (鞠婧祎) Official Platform REST API & Kiku AI Agent",
@@ -585,6 +656,94 @@ function getOpenApiSpec(baseUrl = "https://jujingyi-kikuuu.vercel.app") {
           }
         }
       },
+      "/system/hardware": {
+        get: {
+          tags: ["System"],
+          summary: "Detected GPU / VRAM Hardware Report",
+          description: "Queries local hardware detection (nvidia-smi, rocm-smi, Apple unified-memory heuristic, or the KIKU_VRAM_TOTAL_GB override) and returns the VRAM target used by the predictive VRAM engine.",
+          operationId: "getSystemHardware",
+          responses: {
+            "200": {
+              description: "Hardware report with the resolved VRAM target",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      status: { type: "string", example: "success" },
+                      data: {
+                        type: "object",
+                        properties: {
+                          available: { type: "boolean", example: true },
+                          target: {
+                            type: "object",
+                            properties: {
+                              vendor: { type: "string", example: "NVIDIA" },
+                              name: { type: "string", example: "NVIDIA GeForce RTX 4090" },
+                              totalBytes: { type: "integer", example: 25769803776 },
+                              freeBytes: { type: "integer", nullable: true },
+                              source: { type: "string", example: "nvidia-smi (NVML)" }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/models/estimate-vram": {
+        post: {
+          tags: ["System"],
+          summary: "Predictive VRAM Footprint Estimation",
+          description: "Estimates model weights, KV cache, activation workspace and runtime overhead for a target model/quantization/context configuration and classifies feasibility (GREEN / YELLOW / RED) against available VRAM. KV cache is modeled sliding-window (SWA) aware for architectures like Gemma. Accepts a model name (built-in registry or HuggingFace lookup), a local .gguf path, or explicit architecture fields. With model=auto while LM Studio has a model loaded, classification.basis=measured reflects real GPU usage from the hardware probe instead of the predictive worst-case (returned in predictiveClassification).",
+          operationId: "estimateVram",
+          requestBody: {
+            required: false,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    model: { type: "string", example: "qwen2.5-coder-32b-instruct" },
+                    model_path: { type: "string", example: "C:/models/qwen2.5-coder-32b-q4_k_m.gguf" },
+                    quant: { type: "string", example: "q4_k_m" },
+                    contextLength: { type: "integer", example: 16384 },
+                    cacheBits: { type: "integer", example: 16, description: "KV cache precision (FP16=16, Q8_0=8)" },
+                    batchSize: { type: "integer", example: 1 },
+                    images: { type: "integer", example: 0, description: "VLM correction: concurrent image tokens budget" }
+                  }
+                }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              description: "Footprint breakdown with allocation-zone classification and remediation suggestions",
+              content: { "application/json": { schema: { type: "object" } } }
+            }
+          }
+        },
+        get: {
+          tags: ["System"],
+          summary: "Predictive VRAM Footprint Estimation (query parameters)",
+          operationId: "estimateVramQuery",
+          parameters: [
+            { name: "model", in: "query", schema: { type: "string" }, example: "qwen2.5-7b-instruct" },
+            { name: "ctx", in: "query", schema: { type: "integer" }, example: 8192 },
+            { name: "quant", in: "query", schema: { type: "string" }, example: "q4_k_m" }
+          ],
+          responses: {
+            "200": {
+              description: "Footprint breakdown with allocation-zone classification",
+              content: { "application/json": { schema: { type: "object" } } }
+            }
+          }
+        }
+      },
       "/quiz/challenge": {
         get: {
           tags: ["System"],
@@ -1261,7 +1420,7 @@ function getOpenApiSpec(baseUrl = "https://jujingyi-kikuuu.vercel.app") {
           summary: "Generate Developer API Key (1,000 req/min)",
           description: "Generates a new Developer API key when called with an existing authorized key.",
           operationId: "generateApiKey",
-          security: [{ ApiKeyHeader: [] }, { ApiKeyQuery: [] }],
+          security: [{ ApiKeyHeader: [] }],
           responses: {
             "200": {
               description: "Newly generated API key",
@@ -1277,7 +1436,7 @@ function getOpenApiSpec(baseUrl = "https://jujingyi-kikuuu.vercel.app") {
                         properties: {
                           apiKey: { type: "string", example: "kiku_dev_9x2b81_lz39xk" },
                           tier: { type: "string", example: "Developer Tier (1,000 requests / minute)" },
-                          usage: { type: "string", example: "Pass via 'X-API-Key' header or '?apiKey=' query param" }
+                          usage: { type: "string", example: "Pass via 'X-API-Key' header or Authorization: Bearer <key>" }
                         }
                       }
                     }
@@ -1304,12 +1463,6 @@ function getOpenApiSpec(baseUrl = "https://jujingyi-kikuuu.vercel.app") {
           in: "header",
           name: "X-API-Key",
           description: "Developer API Key passed in request header"
-        },
-        ApiKeyQuery: {
-          type: "apiKey",
-          in: "query",
-          name: "apiKey",
-          description: "Developer API Key passed in query string"
         }
       },
       schemas: {
@@ -1564,17 +1717,21 @@ function getOpenApiSpec(baseUrl = "https://jujingyi-kikuuu.vercel.app") {
       }
     }
   };
+  openApiSpecCache.set(baseUrl, spec);
+  return spec;
 }
 
+let apiDocsHtmlCache = null;
+
 function renderApiDocsHtml() {
-  const openApi = getOpenApiSpec();
-  return `<!DOCTYPE html>
+  if (apiDocsHtmlCache) return apiDocsHtmlCache;
+  const html = `<!DOCTYPE html>
 <html lang="en" class="scroll-smooth">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Ju Jingyi (鞠婧祎) API v1 Documentation & Interactive Console</title>
-  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🌸</text></svg>">
+  <title>🌸 Ju Jingyi (鞠婧祎) API v1 Documentation & Interactive Console</title>
+  <link rel="icon" href="/favicon.ico">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;600;700;800;900&family=Noto+Sans+SC:wght@300;400;500;600;700;900&family=Ma+Shan+Zheng&display=swap" rel="stylesheet">
@@ -1716,8 +1873,8 @@ function renderApiDocsHtml() {
     <div class="flex items-center gap-3 sm:gap-4">
       <a href="/" class="flex items-center gap-3 group select-none transition-transform active:scale-98 text-left">
         <div class="w-10 h-10 sm:w-12 sm:h-12 rounded-2xl bg-gradient-to-br from-rose-500 via-pink-600 to-amber-400 p-[1.5px] shadow-lg shadow-rose-600/30 group-hover:shadow-rose-600/50 transition-all">
-          <div class="w-full h-full rounded-[14px] bg-rose-50 dark:bg-[#12091c] flex items-center justify-center font-calligraphy text-rose-700 dark:text-rose-300 font-bold text-lg sm:text-xl group-hover:scale-110 transition-transform">
-            鞠
+          <div class="w-full h-full rounded-[14px] bg-rose-50 dark:bg-[#12091c] flex items-center justify-center text-xl sm:text-2xl select-none leading-none group-hover:scale-110 transition-transform">
+            🌸
           </div>
         </div>
         <div class="flex flex-col">
@@ -1914,7 +2071,7 @@ function renderApiDocsHtml() {
                 npm package: kiku-agent
               </span>
               <span class="text-[11px] px-2 py-0.5 rounded-full bg-emerald-100 dark:bg-emerald-950/80 text-emerald-800 dark:text-emerald-300 font-mono font-bold border border-emerald-200 dark:border-emerald-800/60">
-                v1.1.0 Ready
+                v${PACKAGE_VERSION} Ready
               </span>
               <span class="text-[11px] px-2 py-0.5 rounded-full bg-purple-100 dark:bg-purple-950/80 text-purple-800 dark:text-purple-300 font-mono font-bold border border-purple-200 dark:border-purple-800/60">
                 MCP Protocol
@@ -2159,8 +2316,8 @@ function renderApiDocsHtml() {
     }
 
     let allExpanded = false;
-    let currentVipKey = '';
-    try { localStorage.removeItem('kiku_vip_key'); } catch {}
+    let currentVipKey = '';
+    try { localStorage.removeItem('kiku_vip_key'); } catch {}
     let quizLang = 'th';
 
     const quizI18n = {
@@ -3121,6 +3278,8 @@ function renderApiDocsHtml() {
         items: [
           { method: "GET", path: "/health", desc: "API health, uptime, and database status (Public & VIP)", example: "/health" },
           { method: "GET", path: "/stats", desc: "Platform statistical overview & catalog counts", example: "/stats" },
+          { method: "GET", path: "/system/hardware", desc: "Detected GPU/VRAM hardware report used by the predictive VRAM engine", example: "/system/hardware" },
+          { method: "POST", path: "/models/estimate-vram", desc: "Predictive VRAM footprint estimation & feasibility zone (weights + KV cache + overhead)", example: "/models/estimate-vram", defaultBody: '{\\n  "model": "qwen2.5-7b-instruct",\\n  "quant": "q4_k_m",\\n  "contextLength": 16384\\n}' },
           { method: "GET", path: "/quiz/challenge", desc: "Request one-time anti-cheat challenge token for VIP quiz", example: "/quiz/challenge" },
           { method: "POST", path: "/keys/claim", desc: "Claim Developer VIP Key upon 15/15 quiz completion", example: "/keys/claim", defaultBody: '{\\n  "score": 15,\\n  "answers": ["A", "B", "C", "D", "A", "B", "C", "D", "A", "B", "C", "D", "A", "B", "C"]\\n}', requiresQuiz: true },
           { method: "GET", path: "/keys/generate", desc: "Generate Developer API Key (Requires Master Key in X-API-Key)", example: "/keys/generate", requiresKey: true },
@@ -3281,6 +3440,8 @@ function renderApiDocsHtml() {
   </script>
 </body>
 </html>`;
+  apiDocsHtmlCache = html;
+  return html;
 }
 
 function safeDecode(str) {
@@ -3292,16 +3453,16 @@ function safeDecode(str) {
   }
 }
 
-export async function handleApiRequest(req, res, next) {
-  const trustProxy = process.env.VERCEL === '1' || process.env.KIKU_TRUST_PROXY === 'true';
-  const rawHost = trustProxy ? (req.headers['x-forwarded-host'] || req.headers.host) : req.headers.host;
-  const hostCandidate = String(rawHost || '').split(',')[0].trim();
-  const host = /^[a-z0-9.-]+(?::\d{1,5})?$/i.test(hostCandidate)
-    ? hostCandidate
-    : 'jujingyi-kikuuu.vercel.app';
-  const isLocal = host.includes('localhost') || host.includes('127.0.0.1') || host.endsWith('.local');
-  const forwardedProtocol = trustProxy ? String(req.headers['x-forwarded-proto'] || '').split(',')[0].trim() : '';
-  const protocol = ['http', 'https'].includes(forwardedProtocol) ? forwardedProtocol : (isLocal ? 'http' : 'https');
+export async function handleApiRequest(req, res, next) {
+  const trustProxy = process.env.VERCEL === '1' || process.env.KIKU_TRUST_PROXY === 'true';
+  const rawHost = trustProxy ? (req.headers['x-forwarded-host'] || req.headers.host) : req.headers.host;
+  const hostCandidate = String(rawHost || '').split(',')[0].trim();
+  const host = /^[a-z0-9.-]+(?::\d{1,5})?$/i.test(hostCandidate)
+    ? hostCandidate
+    : 'jujingyi-kikuuu.vercel.app';
+  const isLocal = host.includes('localhost') || host.includes('127.0.0.1') || host.endsWith('.local');
+  const forwardedProtocol = trustProxy ? String(req.headers['x-forwarded-proto'] || '').split(',')[0].trim() : '';
+  const protocol = ['http', 'https'].includes(forwardedProtocol) ? forwardedProtocol : (isLocal ? 'http' : 'https');
   const baseUrl = `${protocol}://${host}`;
   const { isConfigured: isSupabaseConfigured } = getSupabaseConfig();
 
@@ -3325,34 +3486,35 @@ export async function handleApiRequest(req, res, next) {
     return;
   }
 
-  if (pathname === '/api/v1/openapi.json' || pathname === '/api/v1/swagger.json') {
+  if (pathname === '/openapi.json' || pathname === '/api/v1/openapi.json' || pathname === '/api/v1/swagger.json') {
     return sendJson(res, 200, getOpenApiSpec(baseUrl));
   }
 
-  if (!pathname.startsWith('/api/v1') && pathname !== '/api' && !pathname.startsWith('/mcp')) {
+  if (!pathname.startsWith('/api/v1') && pathname !== '/api' && pathname !== '/openapi.json' && !pathname.startsWith('/mcp')) {
     if (next) return next();
     return;
   }
 
   if (req.method === 'OPTIONS') {
     res.statusCode = 204;
-    applySecurityHeaders(res, false);
+    applySecurityHeaders(res, false, req);
     res.end();
     return;
   }
 
-  const clientIp = resolveClientIp(req);
+  const clientIp = resolveClientIp(req);
   const searchParams = urlObj.searchParams;
   const apiKey = extractApiKey(req);
   const validKeyInfo = apiKey ? await validateApiKey(apiKey) : null;
-  const hasValidApiKey = Boolean(validKeyInfo);
-  const hasAgentExecutionAccess = Boolean(apiKey && (isMasterKey(apiKey) || agentExecutionKeys.has(apiKey.trim())));
+  const hasValidApiKey = Boolean(validKeyInfo);
+  const hasAgentExecutionAccess = Boolean(apiKey && (isMasterKey(apiKey) || agentExecutionKeys.has(apiKey.trim())));
 
   const baseRateLimit = validKeyInfo?.rateLimit || (hasValidApiKey ? RATE_LIMIT_API_KEY : RATE_LIMIT_ANONYMOUS);
-  const parsedTestLimit = Number.parseInt(searchParams.get('testRateLimit') || '', 10);
-  const hasTestRateLimit = Number.isInteger(parsedTestLimit) && parsedTestLimit > 0;
+  const isProduction = process.env.NODE_ENV === 'production';
+  const parsedTestLimit = !isProduction ? Number.parseInt(searchParams.get('testRateLimit') || '', 10) : NaN;
+  const hasTestRateLimit = !isProduction && Number.isInteger(parsedTestLimit) && parsedTestLimit > 0;
   const maxLimit = hasTestRateLimit ? Math.min(parsedTestLimit, baseRateLimit) : baseRateLimit;
-  const baseClientIdentifier = hasValidApiKey ? `key:${hashApiKey(apiKey)}` : `ip:${clientIp}`;
+  const baseClientIdentifier = hasValidApiKey ? `key:${hashApiKey(apiKey)}` : `ip:${clientIp}`;
   const clientIdentifier = hasTestRateLimit
     ? `${baseClientIdentifier}:test:${maxLimit}`
     : baseClientIdentifier;
@@ -3417,7 +3579,7 @@ export async function handleApiRequest(req, res, next) {
     }, rateHeaders);
   }
 
-  if (pathname === '/api/v1/quiz/challenge') {
+  if (pathname === '/api/v1/quiz/challenge') {
     const session = createQuizChallengeToken();
     return sendJson(res, 200, {
       status: 'success',
@@ -3430,14 +3592,12 @@ export async function handleApiRequest(req, res, next) {
         targetTier: 'Developer VIP Tier (1,000 req/min)',
         usage: "Send this challengeToken along with your 15 completed quiz answers to POST /api/v1/keys/claim"
       }
-    }, { ...rateHeaders, 'Cache-Control': 'no-store', Pragma: 'no-cache' });
+    }, { ...rateHeaders, 'Cache-Control': 'no-store', Pragma: 'no-cache' });
   }
 
   if (pathname === '/api/v1/keys/generate') {
-    const adminKey = extractApiKey(req);
-    const adminKeyValid = adminKey ? await validateApiKey(adminKey) : null;
-    const isAuthorized = isMasterKey(adminKey) || (adminKeyValid && adminKeyValid.tier === 'Master VIP');
-    if (!adminKey || !adminKeyValid || !isAuthorized) {
+    const isAuthorized = isMasterKey(apiKey) || (validKeyInfo && validKeyInfo.tier === 'Master VIP');
+    if (!apiKey || !validKeyInfo || !isAuthorized) {
       return sendJson(res, 401, {
         status: 'error',
         code: 401,
@@ -3445,9 +3605,9 @@ export async function handleApiRequest(req, res, next) {
         message: 'Unauthorized. Admin/Master API Key required in X-API-Key header to generate new developer keys.'
       }, rateHeaders);
     }
-    const token = crypto.randomBytes(16).toString('hex');
-    const newKey = `kiku_dev_sk_${token}`;
-    await saveApiKeyToSupabase({ apiKey: newKey, tier: 'developer', rateLimit: 1000 });
+    const token = crypto.randomBytes(16).toString('hex');
+    const newKey = `kiku_dev_sk_${token}`;
+    await saveApiKeyToSupabase({ apiKey: newKey, tier: 'developer', rateLimit: 1000 });
     return sendJson(res, 200, {
       status: 'success',
       code: 200,
@@ -3459,7 +3619,7 @@ export async function handleApiRequest(req, res, next) {
         storage: isSupabaseConfigured ? 'supabase-postgresql (persistent)' : 'in-memory (standalone)',
         usageInstruction: "Attach header 'X-API-Key: <your_key>' or 'Authorization: Bearer <your_key>'"
       }
-    }, { ...rateHeaders, 'Cache-Control': 'no-store', Pragma: 'no-cache' });
+    }, { ...rateHeaders, 'Cache-Control': 'no-store', Pragma: 'no-cache' });
   }
 
   if (pathname === '/api/v1/keys/claim') {
@@ -3510,8 +3670,8 @@ export async function handleApiRequest(req, res, next) {
 
     consumeQuizChallengeToken(body.challengeToken);
 
-    const token = crypto.randomBytes(16).toString('hex');
-    const newVipKey = `kiku_vip_sk_${token}`;
+    const token = crypto.randomBytes(16).toString('hex');
+    const newVipKey = `kiku_vip_sk_${token}`;
     await saveApiKeyToSupabase({ apiKey: newVipKey, tier: 'developer_vip', rateLimit: 1000 });
 
     return sendJson(res, 200, {
@@ -3528,11 +3688,11 @@ export async function handleApiRequest(req, res, next) {
         achievement: 'Ju Jingyi Miju Master (15/15 Perfect Score 🌸)',
         usageInstruction: "Attach header 'X-API-Key: <your_key>' or 'Authorization: Bearer <your_key>'"
       }
-    }, { ...rateHeaders, 'Cache-Control': 'no-store', Pragma: 'no-cache' });
+    }, { ...rateHeaders, 'Cache-Control': 'no-store', Pragma: 'no-cache' });
   }
 
   if (pathname === '/api/v1/stats') {
-    const cleanSongs = getCleanDiscography();
+    const cleanSongs = CLEAN_DISCOGRAPHY;
     return sendJson(res, 200, {
       status: 'success',
       code: 200,
@@ -3676,14 +3836,14 @@ export async function handleApiRequest(req, res, next) {
     }, rateHeaders);
   }
 
-  if (pathname === '/api/v1/agent/query' || pathname === '/api/v1/chat') {
-    if (!hasValidApiKey || !hasAgentExecutionAccess) {
-      return sendJson(res, 401, {
-        status: 'error', code: 401, timestamp,
-        message: 'An agent-execution API key is required for model execution.'
-      }, rateHeaders);
-    }
-    const body = req.method === 'POST' ? await parseJsonBody(req) : {};
+  if (pathname === '/api/v1/agent/query' || pathname === '/api/v1/chat') {
+    if (!hasValidApiKey || !hasAgentExecutionAccess) {
+      return sendJson(res, 401, {
+        status: 'error', code: 401, timestamp,
+        message: 'An agent-execution API key is required for model execution.'
+      }, rateHeaders);
+    }
+    const body = req.method === 'POST' ? await parseJsonBody(req) : {};
     const rawQuery = body.query || body.prompt || searchParams.get('q') || searchParams.get('query') || '';
     const query = sanitizeSearchQuery(rawQuery, 2000);
     if (!query) {
@@ -3697,19 +3857,19 @@ export async function handleApiRequest(req, res, next) {
 
     try {
       const { getSharedAgent } = await import('./routes/agent.js');
-      const provider = sanitizeSearchQuery(body.provider || 'lmstudio', 40).toLowerCase();
-      const providerApiKey = extractProviderApiKey(req);
-      if (provider !== 'lmstudio' && !providerApiKey) {
-        return sendJson(res, 401, {
-          status: 'error', code: 401, timestamp,
-          message: 'X-Provider-API-Key is required for cloud model providers.'
-        }, rateHeaders);
-      }
-      const agent = getSharedAgent({
-        provider,
-        model: sanitizeSearchQuery(body.model || '', 160) || undefined,
-        apiKey: providerApiKey || undefined,
-      });
+      const provider = sanitizeSearchQuery(body.provider || 'lmstudio', 40).toLowerCase();
+      const providerApiKey = extractProviderApiKey(req);
+      if (provider !== 'lmstudio' && !providerApiKey) {
+        return sendJson(res, 401, {
+          status: 'error', code: 401, timestamp,
+          message: 'X-Provider-API-Key is required for cloud model providers.'
+        }, rateHeaders);
+      }
+      const agent = getSharedAgent({
+        provider,
+        model: sanitizeSearchQuery(body.model || '', 160) || undefined,
+        apiKey: providerApiKey || undefined,
+      });
       await agent.ready();
       let collectedAnswer = '';
       await agent.ask(query, {
@@ -3733,13 +3893,13 @@ export async function handleApiRequest(req, res, next) {
     }
   }
 
-  if (pathname === '/api/v1/agent/chat' || pathname === '/api/v1/chat/stream') {
-    if (!hasValidApiKey || !hasAgentExecutionAccess) {
-      return sendJson(res, 401, {
-        status: 'error', code: 401, timestamp,
-        message: 'An agent-execution API key is required for model execution.'
-      }, rateHeaders);
-    }
+  if (pathname === '/api/v1/agent/chat' || pathname === '/api/v1/chat/stream') {
+    if (!hasValidApiKey || !hasAgentExecutionAccess) {
+      return sendJson(res, 401, {
+        status: 'error', code: 401, timestamp,
+        message: 'An agent-execution API key is required for model execution.'
+      }, rateHeaders);
+    }
     const rawQ = searchParams.get('q') || searchParams.get('query') || '';
     const q = sanitizeSearchQuery(rawQ, 2000);
     if (!q) {
@@ -3750,29 +3910,73 @@ export async function handleApiRequest(req, res, next) {
         message: "Missing 'q' or 'query' parameter for agent chat stream."
       }, rateHeaders);
     }
-    const provider = sanitizeSearchQuery(searchParams.get('provider') || 'lmstudio', 40).toLowerCase();
-    const providerApiKey = extractProviderApiKey(req);
-    if (provider !== 'lmstudio' && !providerApiKey) {
-      return sendJson(res, 401, {
-        status: 'error', code: 401, timestamp,
-        message: 'X-Provider-API-Key is required for cloud model providers.'
-      }, rateHeaders);
-    }
-    const { handleAgentChatStream } = await import('./routes/agent.js');
-    return handleAgentChatStream(req, res, q, {
-      provider,
-      model: sanitizeSearchQuery(searchParams.get('model') || '', 160) || undefined,
-      apiKey: providerApiKey || undefined,
-    });
+    const provider = sanitizeSearchQuery(searchParams.get('provider') || 'lmstudio', 40).toLowerCase();
+    const providerApiKey = extractProviderApiKey(req);
+    if (provider !== 'lmstudio' && !providerApiKey) {
+      return sendJson(res, 401, {
+        status: 'error', code: 401, timestamp,
+        message: 'X-Provider-API-Key is required for cloud model providers.'
+      }, rateHeaders);
+    }
+    const { handleAgentChatStream } = await import('./routes/agent.js');
+    return handleAgentChatStream(req, res, q, {
+      provider,
+      model: sanitizeSearchQuery(searchParams.get('model') || '', 160) || undefined,
+      apiKey: providerApiKey || undefined,
+    });
+  }
+
+  if (pathname === '/api/v1/system/hardware') {
+    try {
+      const { buildHardwareReport } = await import('./agent/vramService.js');
+      const report = await buildHardwareReport();
+      return sendJson(res, 200, {
+        status: 'success',
+        code: 200,
+        timestamp,
+        data: report
+      }, rateHeaders);
+    } catch (err) {
+      console.error('[Hardware API Error]:', err);
+      return sendJson(res, 500, {
+        status: 'error',
+        code: 500,
+        timestamp,
+        message: safeErrorMessage(err, 'Hardware probe failed')
+      }, rateHeaders);
+    }
+  }
+
+  if (pathname === '/api/v1/models/estimate-vram') {
+    try {
+      const body = req.method === 'POST' ? await parseJsonBody(req) : {};
+      const request = parseEstimateRequest(body, searchParams);
+      const { computeVramEstimate } = await import('./agent/vramService.js');
+      const estimate = await computeVramEstimate(request);
+      return sendJson(res, 200, {
+        status: 'success',
+        code: 200,
+        timestamp,
+        data: estimate
+      }, rateHeaders);
+    } catch (err) {
+      console.error('[VRAM Estimate API Error]:', err);
+      return sendJson(res, 500, {
+        status: 'error',
+        code: 500,
+        timestamp,
+        message: safeErrorMessage(err, 'VRAM estimation failed')
+      }, rateHeaders);
+    }
   }
 
-  if (pathname === '/api/v1/debate') {
-    if (!hasValidApiKey || !hasAgentExecutionAccess) {
-      return sendJson(res, 401, {
-        status: 'error', code: 401, timestamp,
-        message: 'An agent-execution API key is required for debate execution.'
-      }, rateHeaders);
-    }
+  if (pathname === '/api/v1/debate') {
+    if (!hasValidApiKey || !hasAgentExecutionAccess) {
+      return sendJson(res, 401, {
+        status: 'error', code: 401, timestamp,
+        message: 'An agent-execution API key is required for debate execution.'
+      }, rateHeaders);
+    }
     const body = req.method === 'POST' ? await parseJsonBody(req) : {};
     const rawTopic = body.topic || body.claim || searchParams.get('topic') || searchParams.get('claim') || searchParams.get('q') || '';
     const topic = sanitizeSearchQuery(rawTopic, 500);
@@ -3868,7 +4072,7 @@ export async function handleApiRequest(req, res, next) {
   }
 
   if (pathname === '/api/v1/discography') {
-    let cleanSongs = getCleanDiscography();
+    let cleanSongs = CLEAN_DISCOGRAPHY;
     const type = sanitizeSearchQuery(searchParams.get('type') || '', 50);
     const year = sanitizeSearchQuery(searchParams.get('year') || '', 20);
     const search = sanitizeSearchQuery(searchParams.get('search') || '', 100);
@@ -3900,7 +4104,7 @@ export async function handleApiRequest(req, res, next) {
       timestamp,
       data: cleanSongs,
       meta: {
-        totalUniqueTracks: getCleanDiscography().length,
+        totalUniqueTracks: CLEAN_DISCOGRAPHY.length,
         count: cleanSongs.length
       }
     }, rateHeaders);
@@ -3909,7 +4113,7 @@ export async function handleApiRequest(req, res, next) {
   if (pathname.startsWith('/api/v1/discography/')) {
     const rawId = pathname.replace('/api/v1/discography/', '').trim();
     const id = safeDecode(rawId);
-    const cleanSongs = getCleanDiscography();
+    const cleanSongs = CLEAN_DISCOGRAPHY;
     const song = cleanSongs.find(s => 
       String(s.id) === id || 
       String(s.id) === rawId ||
@@ -4122,7 +4326,7 @@ export async function handleApiRequest(req, res, next) {
       (w.year && String(w.year).includes(q))
     );
 
-    const cleanSongs = getCleanDiscography();
+    const cleanSongs = CLEAN_DISCOGRAPHY;
     const matchedSongs = cleanSongs.filter(s => 
       (s.titleTh && s.titleTh.toLowerCase().includes(q)) || 
       (s.titleCn && s.titleCn.includes(q)) ||