kiku-agent 1.2.0 → 1.3.0

package/server/agent/envManager.js

@@ -0,0 +1,317 @@
+/**
+ * envManager — local .env lifecycle for kiku-agent.
+ *
+ * The npm package is consumed via a global install (`npm install -g kiku-agent`),
+ * so there is no project directory to host configuration. Environment files are
+ * resolved in this order:
+ *
+ *   1. package-root/.env      — development checkouts (and legacy hand-made files)
+ *   2. <KIKU_DATA_DIR>/.env   — user-owned location that survives npm upgrades
+ *
+ * Both files are loaded (package first, unset keys only). `/env` writes to the
+ * primary target: the package file when it exists, the user file otherwise.
+ *
+ * Only NECESSARY values are ever required; everything else is either
+ * auto-detected or left commented in the generated file.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { KIKU_DATA_DIR } from './appPaths.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const PACKAGE_ENV_PATH = path.resolve(__dirname, '..', '..', '.env');
+export const USER_ENV_PATH = path.join(KIKU_DATA_DIR, '.env');
+
+export function resolveEnvTargets({ packageEnvPath = PACKAGE_ENV_PATH, userEnvPath = USER_ENV_PATH } = {}) {
+  const packageExists = fs.existsSync(packageEnvPath);
+  return {
+    mode: packageExists ? 'repo' : 'user',
+    packageExists,
+    packageEnvPath,
+    userEnvPath,
+    primaryPath: packageExists ? packageEnvPath : userEnvPath,
+  };
+}
+
+export function parseEnvMap(text) {
+  const map = {};
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const m = line.match(/^\s*([\w.-]+)\s*=\s*(.*)\s*$/);
+    if (!m || line.trim().startsWith('#')) continue;
+    map[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return map;
+}
+
+export function readEnvFile(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return parseEnvMap(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function readMergedEnvMap({ packageEnvPath = PACKAGE_ENV_PATH, userEnvPath = USER_ENV_PATH } = {}) {
+  const map = {};
+  const sources = {};
+  const userMap = readEnvFile(userEnvPath) || {};
+  const packageMap = readEnvFile(packageEnvPath) || {};
+  for (const [key, value] of Object.entries(userMap)) {
+    map[key] = value;
+    sources[key] = userEnvPath;
+  }
+  for (const [key, value] of Object.entries(packageMap)) {
+    map[key] = value;
+    sources[key] = packageEnvPath;
+  }
+  return { map, sources, packageMap, userMap };
+}
+
+const SECRET_PATTERN = /(API_KEY|_KEYS|MASTER_KEY|SECRET|PEPPER|TOKEN|COOKIES|PASSWORD)/i;
+
+export function isSecretKey(key) {
+  return SECRET_PATTERN.test(String(key || ''));
+}
+
+export function maskValue(key, value) {
+  const str = String(value ?? '');
+  if (!str) return '(not set)';
+  if (!isSecretKey(key)) return str;
+  if (str.length <= 8) return '****';
+  return `${str.slice(0, 4)}…${str.slice(-3)} (${str.length} chars)`;
+}
+
+
+export const ENV_VAR_CATALOG = Object.freeze([
+ 
+  { key: 'LMSTUDIO_BASE_URL', group: 'necessary', defaultValue: 'http://127.0.0.1:1234/v1', description: 'LM Studio (OpenAI-compatible) endpoint' },
+  { key: 'VLLM_BASE_URL', group: 'optional', defaultValue: 'http://127.0.0.1:8000/v1', description: 'vLLM OpenAI-compatible endpoint (WSL/Linux)' },
+
+  
+  { key: 'KIKU_CONTEXT_LIMIT', group: 'recommended', auto: 'context', description: 'Context window for token telemetry (match LM Studio loaded_context_length)' },
+  { key: 'LMSTUDIO_MODELS_DIR', group: 'recommended', auto: 'modelsDir', description: 'Folder scanned for .gguf checkpoints (VRAM estimator)' },
+
+
+  { key: 'LLM_PROVIDER', group: 'optional', defaultValue: 'lmstudio', description: 'Default provider (lmstudio/vllm/openai/gemini/groq/deepseek/openrouter/custom)' },
+  { key: 'KIKU_VRAM_TOTAL_GB', group: 'optional', description: 'Pin the VRAM budget when GPU detection is unavailable' },
+  { key: 'KIKU_YT_COOKIES', group: 'optional', defaultValue: 'cookies.txt', description: 'Netscape cookies file for YouTube playback' },
+  { key: 'KIKU_YT_BROWSER', group: 'optional', description: 'Browser profile for cookie extraction (firefox/chrome/edge/brave)' },
+  { key: 'KIKU_YTDLP', group: 'optional', defaultValue: 'yt-dlp', description: 'yt-dlp binary path' },
+  { key: 'KIKU_YTDLP_CLIENT', group: 'optional', defaultValue: 'tv', description: 'YouTube player client (tv/ios/web)' },
+  { key: 'PORT_WEB_CHAT', group: 'optional', defaultValue: '3002', description: 'Web-chat server port' },
+  { key: 'KIKU_WEB_CHAT_HOST', group: 'optional', defaultValue: '127.0.0.1', description: 'Web-chat bind host (keep loopback unless behind a proxy)' },
+  { key: 'KIKU_THEME', group: 'optional', description: 'Terminal theme name' },
+  { key: 'KIKU_ENABLE_CN_WEB_TOOLS', group: 'optional', defaultValue: 'true', description: 'Enable Chinese web tools (search_chinese_web, search_bilibili)' },
+  { key: 'KIKU_MCP_ENABLE_WEB_TOOLS', group: 'optional', defaultValue: 'false', description: 'Expose web tools through the MCP server (KIKU_MCP_ENABLE_WEB_TOOLS=true)' },
+
+  
+  { key: 'OPENAI_API_KEY', group: 'cloud', description: 'OpenAI' },
+  { key: 'GEMINI_API_KEY', group: 'cloud', description: 'Google Gemini' },
+  { key: 'GROQ_API_KEY', group: 'cloud', description: 'Groq' },
+  { key: 'DEEPSEEK_API_KEY', group: 'cloud', description: 'DeepSeek' },
+  { key: 'OPENROUTER_API_KEY', group: 'cloud', description: 'OpenRouter' },
+
+ 
+  { key: 'API_KEY_PEPPER', group: 'server', description: 'HMAC pepper for API-key hashing' },
+  { key: 'QUIZ_SECRET', group: 'server', description: 'Quiz challenge token secret' },
+  { key: 'KIKU_PROVIDER_KEY_ENCRYPTION_KEY', group: 'server', description: 'Encrypts provider keys at rest' },
+  { key: 'KIKU_MASTER_KEYS', group: 'server', description: 'Admin keys for /keys/generate' },
+  { key: 'KIKU_API_KEYS', group: 'server', description: 'Pre-seeded developer keys' },
+  { key: 'KIKU_VIP_KEYS', group: 'server', description: 'Pre-seeded VIP keys' },
+  { key: 'KIKU_AGENT_KEYS', group: 'server', description: 'Agent-execution keys' },
+  { key: 'MCP_API_KEY', group: 'server', description: 'MCP HTTP auth' },
+]);
+
+const GROUP_LABELS = Object.freeze({
+  necessary: 'Necessary',
+  recommended: 'Recommended (auto-detected)',
+  optional: 'Optional',
+  cloud: 'Cloud provider keys',
+  server: 'Server deployment only',
+});
+
+export function describeGroup(group) {
+  return GROUP_LABELS[group] || group;
+}
+
+
+export async function detectAutoDefaults({ baseUrl, timeoutMs = 2500, signal, probe = true } = {}) {
+  const detected = {
+    lmStudioReachable: false,
+    loadedModel: null,
+    loadedModelType: null,
+    contextLength: null,
+    modelsDir: null,
+  };
+
+  if (probe !== false) {
+    const root = String(baseUrl || process.env.LMSTUDIO_BASE_URL || 'http://127.0.0.1:1234/v1')
+      .replace(/\/v1\/?$/, '')
+      .replace(/\/+$/, '');
+    try {
+      const timeoutSignal = AbortSignal.timeout(timeoutMs);
+      const fetchSignal = signal ? AbortSignal.any([timeoutSignal, signal]) : timeoutSignal;
+      const res = await fetch(`${root}/api/v0/models`, { signal: fetchSignal });
+      if (res.ok) {
+        const data = await res.json();
+        const models = Array.isArray(data?.data) ? data.data : [];
+        if (models.length > 0) detected.lmStudioReachable = true;
+        const loaded = models.find(m => m.state === 'loaded' && (m.type === 'llm' || m.type === 'vlm'))
+          || models.find(m => m.state === 'loaded');
+        if (loaded) {
+          detected.loadedModel = loaded.id || null;
+          detected.loadedModelType = loaded.type || null;
+          detected.contextLength = loaded.loaded_context_length ?? loaded.max_context_length ?? null;
+        }
+      }
+    } catch {
+
+    }
+  }
+
+  const candidates = [
+    process.env.LMSTUDIO_MODELS_DIR,
+    path.join(os.homedir(), '.lmstudio', 'models'),
+    process.platform === 'win32' && process.env.LOCALAPPDATA
+      ? path.join(process.env.LOCALAPPDATA, 'LM Studio', 'models')
+      : null,
+  ].filter(Boolean);
+  detected.modelsDir = candidates.find(p => {
+    try { return fs.existsSync(p); } catch { return false; }
+  }) || null;
+
+  return detected;
+}
+
+
+export function buildEnvTemplate({ values = {}, detected = null } = {}) {
+  const lines = [];
+  lines.push('# ==============================================================================');
+  lines.push('# Kiku Agent — local environment (.env)');
+  lines.push(`# Generated by \`/env init\` on ${new Date().toISOString().slice(0, 10)}.`);
+  lines.push('# Only necessary values are set; everything else stays commented until needed.');
+  lines.push('# ==============================================================================');
+  lines.push('');
+
+  const catalogByGroup = (group) => ENV_VAR_CATALOG.filter(entry => entry.group === group);
+
+  lines.push(`# --- ${describeGroup('necessary')} ----------------------------------------------------------`);
+  for (const entry of catalogByGroup('necessary')) {
+    lines.push(`# ${entry.description}`);
+    lines.push(`${entry.key}=${values[entry.key] ?? entry.defaultValue ?? ''}`);
+  }
+  lines.push('');
+
+  const recommended = catalogByGroup('recommended');
+  if (recommended.some(entry => values[entry.key])) {
+    lines.push(`# --- ${describeGroup('recommended')} ---------------------------------`);
+    for (const entry of recommended) {
+      lines.push(`# ${entry.description}`);
+      if (values[entry.key]) lines.push(`${entry.key}=${values[entry.key]}`);
+      else lines.push(`# ${entry.key}=`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`# --- ${describeGroup('optional')} — uncomment what you need --`);
+  for (const entry of catalogByGroup('optional')) {
+    if (values[entry.key]) lines.push(`${entry.key}=${values[entry.key]}`);
+    else lines.push(`# ${entry.key}=${entry.defaultValue ?? ''}   # ${entry.description}`);
+  }
+  lines.push('');
+
+  lines.push(`# --- ${describeGroup('cloud')} (only if you use cloud models) ---`);
+  for (const entry of catalogByGroup('cloud')) {
+    if (values[entry.key]) lines.push(`${entry.key}=${values[entry.key]}`);
+    else lines.push(`# ${entry.key}=   # ${entry.description}`);
+  }
+  lines.push('');
+
+  lines.push(`# --- ${describeGroup('server')} — never set by fans/CLI users ---`);
+  lines.push('# These credentials (Upstash rate limiting, Supabase storage, API signing');
+  lines.push('# secrets) belong to the hosted REST API / web-chat deployment and are');
+  lines.push('# already configured by the platform developer on that environment.');
+  lines.push('# /env init will never prompt for them and they are not needed locally.');
+  const serverKeys = catalogByGroup('server').map(entry => entry.key).join(', ');
+  lines.push(`# ${serverKeys}`);
+  lines.push('');
+
+  if (detected?.loadedModel) {
+    lines.push(`# Detected LM Studio model at generation time: ${detected.loadedModel}` +
+      (detected.contextLength ? ` (loaded context ${detected.contextLength} tokens)` : ''));
+  }
+
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n') + '\n';
+}
+
+export function writeEnvFile(filePath, content, { allowOverwrite = false } = {}) {
+  if (fs.existsSync(filePath) && !allowOverwrite) {
+    throw new Error(`${filePath} already exists (use /env set to change individual keys)`);
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+  return filePath;
+}
+
+export function generateEnvFile({ targetPath, values = {}, detected = null, allowOverwrite = true } = {}) {
+  const content = buildEnvTemplate({ values, detected });
+  writeEnvFile(targetPath, content, { allowOverwrite });
+  return { path: targetPath, keys: Object.keys(values) };
+}
+
+
+export function upsertEnvKey(filePath, key, value) {
+  const cleanKey = String(key || '').trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(cleanKey)) {
+    throw new Error(`Invalid environment variable name: ${key}`);
+  }
+  const cleanVal = String(value ?? '').replace(/[\r\n]+/g, '').trim();
+  const activeRe = new RegExp(`^${cleanKey}=`);
+  const commentedRe = new RegExp(`^#\\s*${cleanKey}=`);
+  const raw = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  const lines = raw ? raw.split(/\r?\n/) : [];
+
+  let replaced = false;
+  const next = [];
+  for (const line of lines) {
+    if (activeRe.test(line)) {
+      if (!replaced) {
+        next.push(`${cleanKey}=${cleanVal}`);
+        replaced = true;
+      }
+      continue;
+    }
+    if (commentedRe.test(line)) {
+      if (!replaced) {
+        next.push(`${cleanKey}=${cleanVal}`);
+        replaced = true;
+      }
+      continue;
+    }
+    next.push(line);
+  }
+  if (!replaced) next.push(`${cleanKey}=${cleanVal}`);
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, next.join('\n'), 'utf8');
+  return { path: filePath, key: cleanKey, value: cleanVal };
+}
+
+export function removeEnvKey(filePath, key) {
+  const cleanKey = String(key || '').trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(cleanKey)) {
+    throw new Error(`Invalid environment variable name: ${key}`);
+  }
+  const activeRe = new RegExp(`^${cleanKey}=`);
+  const commentedRe = new RegExp(`^#\\s*${cleanKey}=`);
+  if (!fs.existsSync(filePath)) return { path: filePath, removed: false };
+  const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+  const next = lines.filter(line => !activeRe.test(line) && !commentedRe.test(line));
+  fs.writeFileSync(filePath, next.join('\n'), 'utf8');
+  return { path: filePath, removed: next.length !== lines.length };
+}

package/server/agent/eventBus.js

@@ -33,7 +33,7 @@ class EventBus {
     const exactSet = this._listeners.get(event);
     if (exactSet) {
       for (const fn of exactSet) {
-        try { fn(data, event); } catch { /* swallow */ }
+        try { fn(data, event); } catch {  }
       }
     }
 
@@ -42,14 +42,14 @@ class EventBus {
     const wildcardSet = this._listeners.get(wildcardEvent);
     if (wildcardSet) {
       for (const fn of wildcardSet) {
-        try { fn(data, event); } catch { /* swallow */ }
+        try { fn(data, event); } catch {  }
       }
     }
 
     const globalSet = this._listeners.get('*');
     if (globalSet) {
       for (const fn of globalSet) {
-        try { fn(data, event); } catch { /* swallow */ }
+        try { fn(data, event); } catch {  }
       }
     }
   }

package/server/agent/feedbackLearning.js

@@ -1,11 +1,8 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 
-// Minimum feedback samples on a feature before it becomes a learned directive.
 export const FEEDBACK_MIN_SAMPLES = 5;
-// Like-rate at/above this promotes a "prefer" directive.
 export const FEEDBACK_LIKE_THRESHOLD = 0.7;
-// Like-rate at/below this promotes an "avoid" directive.
 export const FEEDBACK_DISLIKE_THRESHOLD = 0.35;
 export const FEEDBACK_MAX_DIRECTIVES = 6;
 const MAX_EVENTS = 500;
@@ -46,10 +43,6 @@ export function extractAnswerFeatures(answer = '', toolsUsed = []) {
   };
 }
 
-// Each definition maps one observable answer trait to an optional "prefer"
-// directive (high like-rate) and/or an "avoid" directive (low like-rate).
-// Traits whose dislike-side is ambiguous (e.g. disliking a short answer does
-// not imply verbosity is wanted) only define the like side.
 const FEATURE_DEFS = [
   {
     key: 'len:short',
@@ -183,7 +176,6 @@ export class FeedbackLearning {
         out.push({ id: `avoid:${def.key}`, kind: 'avoid', text: def.dislike, support: samples, likeRate: Number(likeRate.toFixed(2)), updatedAt: new Date().toISOString() });
       }
     }
-    // Prefer stronger evidence first; cap so the prompt stays lean.
     out.sort((a, b) => b.support - a.support || (b.kind === 'avoid' ? 1 : 0) - (a.kind === 'avoid' ? 1 : 0));
     this.state.directives = out.slice(0, FEEDBACK_MAX_DIRECTIVES);
   }

package/server/agent/gpuMetrics.js

@@ -29,11 +29,97 @@ function runProcessCapture(cmd, args, timeoutMs = 2500) {
   });
 }
 
-export async function getGpuMetrics() {
+function detectGpuVendor(name) {
+  return name.includes('NVIDIA')
+    ? 'NVIDIA'
+    : name.includes('AMD') || name.includes('Radeon')
+    ? 'AMD'
+    : name.includes('Intel')
+    ? 'Intel'
+    : 'Generic';
+}
+
+let cachedSharedMemory = null;
+const SHARED_MEMORY_TTL_MS = 10_000;
+
+export async function getSharedMemoryMetrics(processFilter = '') {
+  if (process.platform !== 'win32') {
+    return { available: false, sharedMemoryUsedMb: 0, hasSpillover: false };
+  }
+  if (cachedSharedMemory && (Date.now() - cachedSharedMemory.timestamp < SHARED_MEMORY_TTL_MS)) {
+    return cachedSharedMemory.data;
+  }
+  try {
+    const script = processFilter
+      ? `$p = @(Get-Process '*${processFilter}*' -ErrorAction SilentlyContinue).Id; if ($p -and $p.Count -gt 0) { $paths = $p | ForEach-Object { "\\GPU Process Memory(pid_" + $_ + "_*)\\Shared Usage" }; $s = (Get-Counter $paths -ErrorAction SilentlyContinue).CounterSamples; if ($s) { ($s | Measure-Object -Property CookedValue -Sum).Sum } else { 0 } } else { (Get-Counter '\\GPU Process Memory(*)\\Shared Usage' -ErrorAction SilentlyContinue).CounterSamples | Measure-Object -Property CookedValue -Sum | Select-Object -ExpandProperty Sum }`
+      : `(Get-Counter '\\GPU Process Memory(*)\\Shared Usage' -ErrorAction SilentlyContinue).CounterSamples | Measure-Object -Property CookedValue -Sum | Select-Object -ExpandProperty Sum`;
+    const res = await runProcessCapture('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], 2500);
+    if (res.ok && res.stdout) {
+      const bytes = parseFloat(res.stdout.trim()) || 0;
+      const mb = Number((bytes / (1024 * 1024)).toFixed(1));
+      const result = {
+        available: true,
+        sharedMemoryBytes: bytes,
+        sharedMemoryUsedMb: mb,
+        hasSpillover: mb > 5.0,
+      };
+      cachedSharedMemory = { data: result, timestamp: Date.now() };
+      return result;
+    }
+  } catch {}
+  return { available: false, sharedMemoryUsedMb: 0, hasSpillover: false };
+}
+
+let cachedGpuMetrics = null;
+let lastGpuMetricsFetch = 0;
+const GPU_METRICS_TTL_MS = 5_000;
+
+let gpuMetricsInFlight = null;
+let windowsFallbackCache = null;
+let windowsFallbackInFlight = null;
+const WINDOWS_FALLBACK_TTL_MS = 300_000;
+
+export async function getGpuMetrics(options = {}) {
+  const hasCache = cachedGpuMetrics !== null;
+  const isFresh = hasCache && (Date.now() - lastGpuMetricsFetch < GPU_METRICS_TTL_MS);
+
+  if (isFresh && !options.noCache) {
+    return cachedGpuMetrics;
+  }
+
+  if (hasCache && !options.noCache) {
+    if (!gpuMetricsInFlight) {
+      gpuMetricsInFlight = computeGpuMetrics(options)
+        .catch(() => cachedGpuMetrics)
+        .finally(() => { gpuMetricsInFlight = null; });
+    }
+    return cachedGpuMetrics;
+  }
+
+  if (gpuMetricsInFlight) return gpuMetricsInFlight;
+  gpuMetricsInFlight = computeGpuMetrics(options);
+  try {
+    return await gpuMetricsInFlight;
+  } finally {
+    gpuMetricsInFlight = null;
+  }
+}
 
-  const nv = await runProcessCapture('nvidia-smi', [
-    '--query-gpu=name,memory.total,memory.used,memory.free,utilization.gpu,temperature.gpu,driver_version',
-    '--format=csv,noheader,nounits'
+async function computeGpuMetrics(options = {}) {
+  const result = await computeGpuMetricsUncached(options);
+  cachedGpuMetrics = result;
+  lastGpuMetricsFetch = Date.now();
+  return result;
+}
+
+async function computeGpuMetricsUncached(options = {}) {
+  const includeShared = options.includeShared !== false;
+  const [nv, shared] = await Promise.all([
+    runProcessCapture('nvidia-smi', [
+      '--query-gpu=name,memory.total,memory.used,memory.free,utilization.gpu,temperature.gpu,driver_version',
+      '--format=csv,noheader,nounits'
+    ]),
+    includeShared ? getSharedMemoryMetrics('lm') : Promise.resolve(cachedSharedMemory?.data || { available: false, sharedMemoryUsedMb: 0, hasSpillover: false })
   ]);
 
   if (nv.ok && nv.stdout) {
@@ -54,6 +140,8 @@ export async function getGpuMetrics() {
         totalMb,
         usedMb,
         freeMb,
+        source: 'nvidia-smi (NVML)',
+        approximate: false,
         totalGb: (totalMb / 1024).toFixed(1),
         usedGb: (usedMb / 1024).toFixed(1),
         freeGb: (freeMb / 1024).toFixed(1),
@@ -61,6 +149,8 @@ export async function getGpuMetrics() {
         utilizationGpu: utilPercent,
         temperatureC: tempC,
         driverVersion: driver || 'N/A',
+        sharedMemoryUsedMb: shared.sharedMemoryUsedMb || 0,
+        hasSpillover: Boolean(shared.hasSpillover),
       };
     });
 
@@ -71,62 +161,26 @@ export async function getGpuMetrics() {
         count: gpus.length,
         primary: gpus[0],
         gpus,
+        sharedMemory: shared,
       };
     }
   }
 
- 
-  if (process.platform === 'win32') {
-    const ps = await runProcessCapture('powershell', [
-      '-NoProfile',
-      '-NonInteractive',
-      '-Command',
-      'Get-CimInstance Win32_VideoController | Select-Object Name, AdapterRAM | ConvertTo-Json'
-    ]);
-
-    if (ps.ok && ps.stdout) {
-      try {
-        let data = JSON.parse(ps.stdout);
-        if (!Array.isArray(data)) data = [data];
-        const gpus = data.filter(item => item?.Name).map((item, idx) => {
-          const ramBytes = item.AdapterRAM || 0;
-          const totalMb = Math.round(ramBytes / (1024 * 1024));
-          const name = String(item.Name);
-          const vendor = name.includes('NVIDIA')
-            ? 'NVIDIA'
-            : name.includes('AMD') || name.includes('Radeon')
-            ? 'AMD'
-            : name.includes('Intel')
-            ? 'Intel'
-            : 'Generic';
 
-          return {
-            index: idx,
-            name,
-            vendor,
-            totalMb,
-            usedMb: null,
-            freeMb: null,
-            totalGb: (totalMb / 1024).toFixed(1),
-            usedGb: null,
-            freeGb: null,
-            usedPercent: null,
-            utilizationGpu: null,
-            temperatureC: null,
-            driverVersion: 'N/A',
-          };
-        });
-
-        if (gpus.length > 0) {
-          return {
-            available: true,
-            vendor: gpus[0].vendor,
-            count: gpus.length,
-            primary: gpus[0],
-            gpus,
-          };
-        }
-      } catch {}
+  if (process.platform === 'win32') {
+    if (windowsFallbackCache && Date.now() < windowsFallbackCache.expires) {
+      return windowsFallbackCache.data;
+    }
+    if (!windowsFallbackInFlight) windowsFallbackInFlight = probeWindowsGpuFallback();
+    let fallback = null;
+    try {
+      fallback = await windowsFallbackInFlight;
+    } finally {
+      windowsFallbackInFlight = null;
+    }
+    if (fallback) {
+      windowsFallbackCache = { expires: Date.now() + WINDOWS_FALLBACK_TTL_MS, data: fallback };
+      return fallback;
     }
   }
 
@@ -175,6 +229,85 @@ export async function getGpuMetrics() {
   };
 }
 
+async function probeWindowsGpuFallback() {
+  const REGISTRY_SNIPPET = "$b='HKLM:\\SYSTEM\\CurrentControlSet\\Control\\Class\\{4d36e968-e325-11ce-bfc1-08002be10318}'; Get-ChildItem $b -ErrorAction SilentlyContinue | ForEach-Object { $p = Get-ItemProperty -Path $_.PSPath -ErrorAction SilentlyContinue; if ($p.DriverDesc -and $p.'HardwareInformation.qwMemorySize') { $raw = $p.'HardwareInformation.qwMemorySize'; $n = [UInt64]0; if ($raw -is [byte[]]) { $n = [BitConverter]::ToUInt64([byte[]]$raw, 0) } elseif ($raw -is [long] -or $raw -is [int]) { $n = [UInt64]$raw }; if ($n -gt 0) { [PSCustomObject]@{ Name = $p.DriverDesc; Bytes = $n } } } } | ConvertTo-Json";
+
+  let gpus = [];
+
+  const ps = await runProcessCapture('powershell', [
+    '-NoProfile',
+    '-NonInteractive',
+    '-Command',
+    REGISTRY_SNIPPET,
+  ]);
+  if (ps.stdout) {
+    try {
+      let data = JSON.parse(ps.stdout);
+      if (!Array.isArray(data)) data = [data];
+      gpus = data.filter(item => item?.Name && Number(item.Bytes) > 0).map((item, idx) => {
+        const name = String(item.Name);
+        return {
+          index: idx,
+          name,
+          vendor: detectGpuVendor(name),
+          totalMb: Math.round(Number(item.Bytes) / (1024 * 1024)),
+          usedMb: null,
+          freeMb: null,
+          source: 'windows-registry',
+          approximate: false,
+        };
+      });
+    } catch {}
+  }
+
+  if (gpus.length === 0) {
+    const wmi = await runProcessCapture('powershell', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      'Get-CimInstance Win32_VideoController | Select-Object Name, AdapterRAM | ConvertTo-Json'
+    ]);
+    if (wmi.stdout) {
+      try {
+        let data = JSON.parse(wmi.stdout);
+        if (!Array.isArray(data)) data = [data];
+        gpus = data.filter(item => item?.Name).map((item, idx) => ({
+          index: idx,
+          name: String(item.Name),
+          vendor: detectGpuVendor(String(item.Name)),
+          totalMb: Math.round((item.AdapterRAM || 0) / (1024 * 1024)),
+          usedMb: null,
+          freeMb: null,
+          source: 'wmi-adapterram',
+          approximate: true,
+        }));
+      } catch {}
+    }
+  }
+
+  if (gpus.length === 0) return null;
+
+  gpus.sort((a, b) => (b.totalMb || 0) - (a.totalMb || 0));
+  gpus.forEach((g, idx) => { g.index = idx; });
+  const primary = gpus[0];
+  return {
+    available: true,
+    vendor: primary.vendor,
+    count: gpus.length,
+    primary: {
+      ...primary,
+      totalGb: (primary.totalMb / 1024).toFixed(1),
+      usedGb: null,
+      freeGb: null,
+      usedPercent: null,
+      utilizationGpu: null,
+      temperatureC: null,
+      driverVersion: 'N/A',
+    },
+    gpus,
+  };
+}
+
 export function formatProgressBar(percent = 0, width = 16) {
   const safePct = Math.max(0, Math.min(100, Number(percent) || 0));
   const filled = Math.round((safePct / 100) * width);