magpie-gemini-web 0.4.1 → 0.5.0

package/lib/studio-native.mjs

@@ -0,0 +1,1137 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import net from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { spawn, execFile, execFileSync } from 'node:child_process';
+import release from './studio-release.json' with { type: 'json' };
+
+export const STUDIO_VERSION = `v${release.version}`;
+export const PINNED_ARCHIVES = release.binaries;
+// The port a new setup tries first: AIStudio2API's own default.
+export const DEFAULT_STUDIO_PORT = 2048;
+// backend.log is set aside as backend.log.1 when a start finds it past this size.
+const LOG_ROTATE_BYTES = 10 * 1024 * 1024;
+
+const adminSessions = new Map();
+const inFlightStarts = new Map();
+const inFlightReady = new Map();
+
+export function studioDataDir(env = process.env) {
+  return env.AI_STUDIO_DATA_DIR || path.join(os.homedir(), '.local', 'share', 'magpie-ai-studio');
+}
+
+export function computeFileHash(filePath) {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+// studioCommand is a command line for this plugin's own management CLI, to quote in messages.
+// Magpie installs the plugin where its user doesn't look, so `npm run studio:*` from a checkout
+// is no help to them; the CLI's full path also keeps its pinned version the plugin's own.
+export function studioCommand(action) {
+  const script = fileURLToPath(new URL('../scripts/studio.mjs', import.meta.url));
+  return `node "${script}" ${action}`;
+}
+
+// pickStudioPort is the port for a new setup: preferred when nothing uses it, else one the system
+// has free. A user who already runs AIStudio2API keeps it on its default port, which a new setup
+// would otherwise find taken on every start.
+export async function pickStudioPort(preferred = DEFAULT_STUDIO_PORT) {
+  if (!(await portAnswers(preferred)) && await canListen(preferred)) return preferred;
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+// portAnswers says whether something accepts connections on the port. Listening alone doesn't
+// tell: on macOS a listener on 0.0.0.0 lets another bind 127.0.0.1 to the same port.
+function portAnswers(port) {
+  return new Promise(resolve => {
+    const socket = net.connect({ host: '127.0.0.1', port });
+    const done = answered => {
+      socket.destroy();
+      resolve(answered);
+    };
+    socket.setTimeout(1000, () => done(true));
+    socket.once('connect', () => done(true));
+    socket.once('error', err => done(err.code !== 'ECONNREFUSED'));
+  });
+}
+
+function canListen(port) {
+  return new Promise(resolve => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+  });
+}
+
+// newConfigPort is the port to write when dataDir has no config.json yet (options.preferredPort
+// tried first), else undefined.
+async function newConfigPort(dataDir, options = {}) {
+  if (fs.existsSync(path.join(dataDir, 'config.json'))) return undefined;
+  return pickStudioPort(options.preferredPort ?? DEFAULT_STUDIO_PORT);
+}
+
+export function binaryPath(dataDir, platform = process.platform) {
+  return path.join(dataDir, 'package', platform === 'win32' ? 'aistudio2api.exe' : 'aistudio2api');
+}
+
+export function validateProxy(proxy) {
+  if (proxy === undefined || proxy === null || proxy === '') return '';
+  if (typeof proxy !== 'string') {
+    throw new Error('Proxy URL must be a string');
+  }
+  const trimmed = proxy.trim();
+  if (!trimmed) return '';
+  if (/[\r\n]/.test(trimmed)) throw new Error('Proxy URL must not contain newlines');
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error('Invalid proxy URL');
+  }
+  if (!['http:', 'https:', 'socks5:', 'socks5h:'].includes(parsed.protocol)) {
+    throw new Error('Proxy URL must use http, https, or socks5 protocol');
+  }
+  return trimmed;
+}
+
+// effectiveProxy is the proxy the service and its downloads go through: the one given, else
+// AI_STUDIO_PROXY, else the one saved in config.json.
+function effectiveProxy(explicit, saved) {
+  if (explicit !== undefined) return validateProxy(explicit);
+  if (process.env.AI_STUDIO_PROXY !== undefined) return validateProxy(process.env.AI_STUDIO_PROXY);
+  return validateProxy(saved);
+}
+
+export function validateConfig(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('Configuration must be an object');
+  }
+  if (config.version !== 1) {
+    throw new Error(`Unsupported configuration version: ${config.version}`);
+  }
+  const port = config.port;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port number in configuration: ${port}`);
+  }
+  if (typeof config.apiKey !== 'string' || !config.apiKey || /[\r\n]/.test(config.apiKey)) {
+    throw new Error('Invalid apiKey in configuration: must be non-empty string without newlines');
+  }
+  if (typeof config.adminUsername !== 'string' || !config.adminUsername || /[\r\n]/.test(config.adminUsername)) {
+    throw new Error('Invalid adminUsername in configuration: must be non-empty string without newlines');
+  }
+  if (typeof config.adminPassword !== 'string' || !config.adminPassword || /[\r\n]/.test(config.adminPassword)) {
+    throw new Error('Invalid adminPassword in configuration: must be non-empty string without newlines');
+  }
+  const proxy = validateProxy(config.proxy);
+  return {
+    version: 1,
+    port,
+    apiKey: config.apiKey,
+    adminUsername: config.adminUsername,
+    adminPassword: config.adminPassword,
+    proxy
+  };
+}
+
+// serviceEnv is the fixed settings the service runs with. The service is started with them and
+// they are written to its .env, which it reads again when its generation service restarts.
+function serviceEnv(dataDir, config, options = {}) {
+  const authDir = path.resolve(dataDir, 'auth');
+  if (/[\r\n]/.test(authDir) || /[\r\n]/.test(config.apiKey) || /[\r\n]/.test(config.adminUsername) || /[\r\n]/.test(config.adminPassword)) {
+    throw new Error('Configuration paths or credentials must not contain newlines');
+  }
+  return {
+    LISTEN_ADDR: `127.0.0.1:${config.port}`,
+    AISTUDIO_AUTH_STATES: authDir,
+    PROXY_API_KEY: config.apiKey,
+    ADMIN_AUTH_ENABLED: 'true',
+    ADMIN_USERNAME: config.adminUsername,
+    ADMIN_PASSWORD: config.adminPassword,
+    AUTO_START: 'true',
+    REQUEST_BODY_LOG: 'false',
+    LOG_FILE: 'false',
+    WAA_BACKEND: 'go',
+    UPSTREAM_CHANNELS: 'playground',
+    BUILD_NATIVE_NONSTREAM: 'false',
+    TEMPORARY_CHAT: 'true',
+    PER_ACCOUNT_CONCURRENCY: '1',
+    WARM_WORKER_LIMIT: '1',
+    MAX_ACTIVE_WORKERS: '1',
+    WARM_STARTUP_CONCURRENCY: '1',
+    ROUTING_STRATEGY: 'fill-first',
+    REQUEST_TIMEOUT: '5m',
+    INIT_TIMEOUT: '2m',
+    PROXY: effectiveProxy(options.proxy, config.proxy)
+  };
+}
+
+export function generateEnv(dataDir, config, options = {}) {
+  return Object.entries(serviceEnv(dataDir, config, options)).map(([k, v]) => `${k}=${v}\n`).join('');
+}
+
+// ensureStudioConfig reads config.json, writing a new one if there is none: on options.port when
+// given (see pickStudioPort), else on DEFAULT_STUDIO_PORT.
+export function ensureStudioConfig(dataDir, explicitProxy = undefined, options = {}) {
+  fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+  fs.chmodSync(dataDir, 0o700);
+
+  const configPath = path.join(dataDir, 'config.json');
+  let config;
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (parseErr) {
+      throw new Error(`Invalid JSON in configuration file ${configPath}: ${parseErr.message}`);
+    }
+    config = validateConfig(parsed);
+    fs.chmodSync(configPath, 0o600);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      config = {
+        version: 1,
+        port: options.port ?? DEFAULT_STUDIO_PORT,
+        apiKey: 'as_' + crypto.randomBytes(32).toString('hex'),
+        adminUsername: 'magpie',
+        adminPassword: crypto.randomBytes(32).toString('hex'),
+        proxy: validateProxy(explicitProxy ?? '')
+      };
+      const tmp = `${configPath}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+      fs.renameSync(tmp, configPath);
+      fs.chmodSync(configPath, 0o600);
+    } else {
+      throw err;
+    }
+  }
+
+  const envPath = path.join(dataDir, '.env');
+  const envContent = generateEnv(dataDir, config, { proxy: explicitProxy });
+  const tmpEnv = `${envPath}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(tmpEnv, envContent, { mode: 0o600 });
+  fs.renameSync(tmpEnv, envPath);
+  fs.chmodSync(envPath, 0o600);
+
+  const authDir = path.join(dataDir, 'auth');
+  fs.mkdirSync(authDir, { recursive: true, mode: 0o700 });
+  fs.chmodSync(authDir, 0o700);
+
+  return config;
+}
+
+export function localStudio(options = {}) {
+  const dataDir = options.dataDir || studioDataDir();
+  const platform = options.platform || process.platform;
+  const binPath = binaryPath(dataDir, platform);
+  if (!fs.existsSync(binPath)) return null;
+
+  const configPath = path.join(dataDir, 'config.json');
+  if (!fs.existsSync(configPath)) return null;
+  let config;
+  try {
+    config = validateConfig(JSON.parse(fs.readFileSync(configPath, 'utf8')));
+  } catch {
+    return null;
+  }
+
+  const origin = `http://127.0.0.1:${config.port}`;
+  return {
+    origin,
+    baseURL: `${origin}/v1`,
+    apiKey: config.apiKey,
+    adminUsername: config.adminUsername,
+    adminPassword: config.adminPassword,
+    port: config.port,
+    dataDir
+  };
+}
+
+export async function studioAdmin(local, method, pathname, body = null, options = {}) {
+  if (!local || typeof local !== 'object') {
+    throw new Error('localStudio configuration required for studioAdmin');
+  }
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const origin = local.origin;
+  const sessionKey = `${origin}\n${local.adminUsername}\n${local.adminPassword}`;
+
+  let timeoutMs = options.timeoutMs;
+  if (!timeoutMs) {
+    if (pathname === '/api/accounts' && method.toUpperCase() === 'POST') {
+      timeoutMs = 15 * 60 * 1000;
+    } else if (pathname.includes('/control/start')) {
+      timeoutMs = 180 * 1000;
+    } else {
+      timeoutMs = 5 * 1000;
+    }
+  }
+
+  async function login() {
+    const loginUrl = `${origin}/api/auth/login`;
+    let res;
+    try {
+      res = await fetchFn(loginUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ username: local.adminUsername, password: local.adminPassword }),
+        redirect: 'error',
+        signal: AbortSignal.timeout(Math.min(timeoutMs, 10000))
+      });
+    } catch (err) {
+      adminSessions.delete(sessionKey);
+      if (err.foreign) throw err;
+      if (err.cause?.message?.includes('redirect') || err.message?.includes('redirect')) {
+        const e = new Error('Admin login returned redirect; foreign listener detected');
+        e.foreign = true;
+        throw e;
+      }
+      throw err;
+    }
+    if (res.status >= 300 && res.status < 400) {
+      adminSessions.delete(sessionKey);
+      const err = new Error('Admin login returned redirect; foreign listener detected');
+      err.foreign = true;
+      throw err;
+    }
+    if (!res.ok) {
+      adminSessions.delete(sessionKey);
+      const err = new Error(`Admin login failed: HTTP ${res.status}`);
+      err.status = res.status;
+      // A server error or a rate limit is the service having trouble; any other refusal of this
+      // setup's credentials means the service isn't this setup's.
+      err.foreign = res.status < 500 && res.status !== 429;
+      throw err;
+    }
+    // Each Set-Cookie on its own: joined, a cookie set after another one isn't found by name.
+    const cookie = res.headers.getSetCookie()
+      .map(line => /^\s*(aistudio_admin=[^;]+)/.exec(line)?.[1])
+      .find(Boolean);
+    if (!cookie) {
+      const err = new Error('Admin login did not provide aistudio_admin session cookie');
+      err.foreign = true;
+      throw err;
+    }
+    adminSessions.set(sessionKey, cookie);
+    return cookie;
+  }
+
+  let cookie = adminSessions.get(sessionKey);
+  if (!cookie) {
+    cookie = await login();
+  }
+
+  async function executeRequest(activeCookie) {
+    const url = `${origin}${pathname}`;
+    const headers = new Headers();
+    if (activeCookie) headers.set('Cookie', activeCookie);
+    let payload = null;
+    if (body !== null && body !== undefined) {
+      if (typeof body === 'object') {
+        payload = JSON.stringify(body);
+        headers.set('Content-Type', 'application/json');
+      } else {
+        payload = String(body);
+      }
+    }
+    return fetchFn(url, {
+      method,
+      headers,
+      body: payload,
+      redirect: 'error',
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  }
+
+  let res;
+  try {
+    res = await executeRequest(cookie);
+  } catch (err) {
+    if (err.foreign) throw err;
+    if (err.cause?.message?.includes('redirect') || err.message?.includes('redirect')) {
+      const e = new Error(`Admin request ${method} ${pathname} returned redirect; foreign listener detected`);
+      e.foreign = true;
+      throw e;
+    }
+    const e = new Error(`Admin request ${method} ${pathname} failed: ${err.message}`, { cause: err });
+    if (err.code) e.code = err.code;
+    throw e;
+  }
+
+  if (res.status >= 300 && res.status < 400) {
+    const err = new Error(`Admin request ${method} ${pathname} returned redirect; foreign listener detected`);
+    err.foreign = true;
+    throw err;
+  }
+
+  if (res.status === 401) {
+    cookie = await login();
+    try {
+      res = await executeRequest(cookie);
+    } catch (err) {
+      if (err.foreign) throw err;
+      if (err.cause?.message?.includes('redirect') || err.message?.includes('redirect')) {
+        const e = new Error(`Admin request ${method} ${pathname} returned redirect on retry`);
+        e.foreign = true;
+        throw e;
+      }
+      const e = new Error(`Admin request ${method} ${pathname} retry failed: ${err.message}`, { cause: err });
+      if (err.code) e.code = err.code;
+      throw e;
+    }
+    if (res.status >= 300 && res.status < 400) {
+      const err = new Error(`Admin request ${method} ${pathname} returned redirect on retry`);
+      err.foreign = true;
+      throw err;
+    }
+  }
+
+  if (res.status === 204) return null;
+  const contentType = res.headers.get('content-type') || '';
+  if (contentType.includes('application/json')) {
+    const json = await res.json();
+    if (!res.ok) {
+      throw new Error(json?.error?.message || json?.message || `Admin request failed: HTTP ${res.status}`);
+    }
+    return json;
+  }
+
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Admin request failed: HTTP ${res.status}: ${text.slice(0, 500)}`);
+  }
+  return text;
+}
+
+export async function studioAccounts(options = {}) {
+  const local = localStudio(options);
+  if (!local) return [];
+  const res = await studioAdmin(local, 'GET', '/api/accounts', null, options);
+  const accounts = Array.isArray(res?.accounts) ? res.accounts : [];
+  return accounts.filter(a => a.enabled !== false);
+}
+
+export function isConnectRefused(err) {
+  if (!err) return false;
+  const visited = new Set();
+  let current = err;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    if (current.code === 'ECONNREFUSED' || current.code === 'ENOENT') return true;
+    if (Array.isArray(current.errors)) {
+      for (const sub of current.errors) {
+        if (isConnectRefused(sub)) return true;
+      }
+    }
+    current = current.cause;
+  }
+  return false;
+}
+
+// checkStudioHealth says what answers on the setup's port: 'down' (nothing), 'up' (this setup's
+// service, at the pinned version), 'outdated' (this setup's service, at another version),
+// 'foreign' (something else) or 'unresponsive' (something that times out or fails, as the
+// service can while it starts or when it hangs).
+export async function checkStudioHealth(local, fetchFn) {
+  let status;
+  try {
+    status = await studioAdmin(local, 'GET', '/api/status', null, { fetchFn, timeoutMs: 2000 });
+  } catch (err) {
+    if (isConnectRefused(err)) {
+      return { state: 'down', reason: 'ECONNREFUSED' };
+    }
+    return { state: err.foreign ? 'foreign' : 'unresponsive', reason: err.message };
+  }
+
+  if (!status || typeof status !== 'object') {
+    return { state: 'foreign', reason: 'Status response is not an object' };
+  }
+  if (typeof status.ready !== 'boolean' || typeof status.running !== 'boolean') {
+    return { state: 'foreign', reason: 'Missing boolean ready or running in status' };
+  }
+  if (!status.accounts || typeof status.accounts !== 'object') {
+    return { state: 'foreign', reason: 'Missing accounts object in status' };
+  }
+
+  if (status.ready) {
+    try {
+      const modelsRes = await fetchFn(`${local.baseURL}/models`, {
+        headers: { Authorization: `Bearer ${local.apiKey}` },
+        redirect: 'error',
+        signal: AbortSignal.timeout(2000)
+      });
+      await modelsRes.body?.cancel();
+      if (modelsRes.status === 401 || (modelsRes.status >= 300 && modelsRes.status < 400)) {
+        return { state: 'foreign', reason: 'Models auth key mismatch' };
+      }
+    } catch (err) {
+      if (isConnectRefused(err)) {
+        return { state: 'down', reason: 'ECONNREFUSED' };
+      }
+      return { state: 'unresponsive', reason: err.message };
+    }
+  }
+
+  // The service took this setup's own admin credentials, so this plugin installed it. Another
+  // version is an earlier install still running, as after a plugin update pinned a new one.
+  if (String(status.version).replace(/^v/, '') !== release.version) {
+    return { state: 'outdated', status, reason: `Running version ${status.version}, expected ${STUDIO_VERSION}` };
+  }
+
+  return { state: 'up', status };
+}
+
+export async function studioStatus(options = {}) {
+  const dataDir = options.dataDir || studioDataDir();
+  const platform = options.platform || process.platform;
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const local = localStudio({ dataDir, platform });
+  if (!local) return { status: 'not_installed', dataDir };
+
+  const health = await checkStudioHealth(local, fetchFn);
+  if (health.state === 'up') {
+    return { status: 'running', ...health.status, port: local.port, dataDir };
+  }
+  if (health.state === 'down') {
+    return { status: 'stopped', port: local.port, dataDir };
+  }
+  if (health.state === 'outdated') {
+    return { ...health.status, status: 'outdated', expected: STUDIO_VERSION, port: local.port, dataDir };
+  }
+  return { status: health.state, reason: health.reason, port: local.port, dataDir };
+}
+
+export function verifyProcessIdentity(pid, expectedBinaryPath, platform = process.platform) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (!fs.existsSync(expectedBinaryPath)) return false;
+
+  const expectedReal = fs.realpathSync(expectedBinaryPath);
+
+  if (platform === 'win32') {
+    try {
+      const out = execFileSync('powershell', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        `Get-CimInstance Win32_Process -Filter "ProcessId = $env:TARGET_PID" | Select-Object -ExpandProperty ExecutablePath`
+      ], {
+        env: { ...process.env, TARGET_PID: String(pid) },
+        encoding: 'utf8',
+        windowsHide: true
+      }).trim();
+      if (!out) return false;
+      return fs.realpathSync(out).toLowerCase() === expectedReal.toLowerCase();
+    } catch {
+      return false;
+    }
+  }
+
+  // Linux /proc/<pid>/exe
+  const linuxProcExe = `/proc/${pid}/exe`;
+  if (fs.existsSync(linuxProcExe)) {
+    try {
+      const targetReal = fs.realpathSync(linuxProcExe);
+      return targetReal === expectedReal;
+    } catch {}
+  }
+
+  // macOS / fallback: ps -p <pid> -o comm=
+  try {
+    const comm = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], { encoding: 'utf8' }).trim();
+    if (!comm) return false;
+    if (fs.existsSync(comm)) {
+      return fs.realpathSync(comm) === expectedReal;
+    }
+    if (path.basename(comm) === path.basename(expectedReal)) {
+      const command = execFileSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' }).trim();
+      const firstArg = command.split(' ')[0];
+      if (fs.existsSync(firstArg) && fs.realpathSync(firstArg) === expectedReal) {
+        return true;
+      }
+    }
+  } catch {}
+
+  return false;
+}
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+async function withLock(dataDir, fn, timeoutMs = 600000) {
+  const lockPath = path.join(dataDir, '.setup.lock');
+  const token = crypto.randomBytes(16).toString('hex');
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx', 0o600);
+      fs.writeFileSync(fd, `${process.pid}\n${Date.now()}\n${token}\n`);
+      fs.closeSync(fd);
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+
+      let ownerAlive = false;
+      let ownerPid = NaN;
+      let stat = null;
+      try {
+        stat = fs.statSync(lockPath);
+        const content = fs.readFileSync(lockPath, 'utf8');
+        const lines = content.split('\n');
+        ownerPid = parseInt(lines[0], 10);
+        if (Number.isInteger(ownerPid) && ownerPid > 0) {
+          process.kill(ownerPid, 0);
+          ownerAlive = true;
+        }
+      } catch {
+        ownerAlive = false;
+      }
+
+      if (Number.isInteger(ownerPid) && ownerPid > 0) {
+        if (!ownerAlive) {
+          try {
+            fs.rmSync(lockPath, { force: true });
+            continue;
+          } catch {}
+        }
+      } else if (stat && Date.now() - stat.mtimeMs > 30000) {
+        try {
+          fs.rmSync(lockPath, { force: true });
+          continue;
+        } catch {}
+      }
+
+      if (Date.now() > deadline) {
+        throw new Error(`Timed out waiting for another AI Studio setup lock (${lockPath})`);
+      }
+      await sleep(250);
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    try {
+      const current = fs.readFileSync(lockPath, 'utf8');
+      if (current.includes(token)) {
+        fs.rmSync(lockPath, { force: true });
+      }
+    } catch {}
+  }
+}
+
+export async function installStudio(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const pinKey = `${platform}-${arch}`;
+  const pin = PINNED_ARCHIVES[pinKey];
+  if (!pin) {
+    throw new Error(`Unsupported platform/arch: ${platform}/${arch}. Only darwin-x64, darwin-arm64, linux-x64, linux-arm64, win32-x64 are supported.`);
+  }
+
+  const dataDir = options.dataDir || studioDataDir();
+  fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+  fs.chmodSync(dataDir, 0o700);
+
+  // Validate existing config first, throw if corrupted
+  const configPath = path.join(dataDir, 'config.json');
+  const savedConfig = fs.existsSync(configPath)
+    ? validateConfig(JSON.parse(fs.readFileSync(configPath, 'utf8')))
+    : null;
+
+  // Refuse install/update while running or foreign
+  const localExisting = localStudio({ dataDir, platform });
+  if (localExisting) {
+    const health = await checkStudioHealth(localExisting, options.fetchFn || globalThis.fetch);
+    if (health.state === 'up') {
+      throw new Error('Cannot install or update AIStudio2API while service is running. Stop the service first.');
+    }
+    if (health.state === 'outdated') {
+      throw new Error(`Cannot install AIStudio2API ${STUDIO_VERSION} while ${health.status.version} from an earlier install is running. Stop the service first.`);
+    }
+    if (health.state === 'foreign') {
+      throw new Error(`Cannot install AIStudio2API: Port ${localExisting.port} is occupied by an unknown/foreign listener. Change "port" in config.json.`);
+    }
+    if (health.state === 'unresponsive') {
+      throw new Error(`Cannot install AIStudio2API while something on port ${localExisting.port} is not responding (${health.reason}). Stop the service first.`);
+    }
+  }
+
+  const expectedHash = pin.sha256;
+  let archivePath = options.archivePath;
+  // The archive kept from an earlier install sets a damaged binary right again without a download.
+  const retainedArchive = path.join(dataDir, pin.asset);
+  if (!archivePath && fs.existsSync(retainedArchive) && computeFileHash(retainedArchive) === expectedHash) {
+    archivePath = retainedArchive;
+  }
+  const port = await newConfigPort(dataDir, options);
+  const stageDir = path.join(dataDir, `.install.tmp.${crypto.randomBytes(4).toString('hex')}`);
+  fs.mkdirSync(stageDir, { recursive: true, mode: 0o700 });
+
+  try {
+    if (archivePath) {
+      if (!fs.existsSync(archivePath)) {
+        throw new Error(`Provided archive does not exist: ${archivePath}`);
+      }
+      const actualHash = computeFileHash(archivePath);
+      if (actualHash !== expectedHash) {
+        throw new Error(`SHA256 checksum mismatch for archive: expected ${expectedHash}, got ${actualHash}`);
+      }
+    } else {
+      const downloadUrl = `https://github.com/${release.repository}/releases/download/${release.tag}/${pin.asset}`;
+      archivePath = path.join(stageDir, pin.asset);
+      const proxy = effectiveProxy(options.proxy, savedConfig?.proxy);
+
+      if (options.fetchFn && options.fetchFn !== globalThis.fetch) {
+        const res = await options.fetchFn(downloadUrl, { signal: AbortSignal.timeout(300000) });
+        if (!res.ok) {
+          throw new Error(`Failed to download AIStudio2API archive from ${downloadUrl}: HTTP ${res.status}`);
+        }
+        const buffer = Buffer.from(await res.arrayBuffer());
+        const downloadedHash = crypto.createHash('sha256').update(buffer).digest('hex');
+        if (downloadedHash !== expectedHash) {
+          throw new Error(`SHA256 checksum mismatch for downloaded archive: expected ${expectedHash}, got ${downloadedHash}`);
+        }
+        fs.writeFileSync(archivePath, buffer, { mode: 0o600 });
+      } else {
+        // Without a progress meter curl's stderr holds just the reason a download failed.
+        const curlArgs = ['--fail', '--location', '--silent', '--show-error', '--connect-timeout', '15', '--max-time', '300'];
+        if (proxy) {
+          curlArgs.push('--proxy', proxy);
+        }
+        curlArgs.push('-o', archivePath, downloadUrl);
+        await new Promise((resolve, reject) => {
+          execFile('curl', curlArgs, (err, _stdout, stderr) => {
+            if (err) {
+              const status = err.code || err.status || 'failed';
+              const reason = String(stderr || '').trim().slice(0, 500);
+              reject(new Error(`Failed to download AIStudio2API archive via curl (status: ${status})${reason ? `: ${reason}` : ''}`));
+            } else {
+              resolve();
+            }
+          });
+        });
+        const downloadedHash = computeFileHash(archivePath);
+        if (downloadedHash !== expectedHash) {
+          throw new Error(`SHA256 checksum mismatch for downloaded archive: expected ${expectedHash}, got ${downloadedHash}`);
+        }
+      }
+    }
+
+    if (archivePath !== retainedArchive) {
+      fs.copyFileSync(archivePath, retainedArchive);
+      fs.chmodSync(retainedArchive, 0o600);
+    }
+
+    const extractDir = path.join(stageDir, 'extracted');
+    fs.mkdirSync(extractDir, { recursive: true, mode: 0o700 });
+
+    if (platform === 'win32') {
+      execFileSync('powershell', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        'Expand-Archive -LiteralPath $env:ARCHIVE_PATH -DestinationPath $env:DEST_PATH -Force'
+      ], {
+        env: { ...process.env, ARCHIVE_PATH: archivePath, DEST_PATH: extractDir },
+        windowsHide: true
+      });
+    } else {
+      const listOutput = execFileSync('tar', ['-tvf', archivePath], { encoding: 'utf8' }).split('\n').filter(Boolean);
+      for (const line of listOutput) {
+        const parts = line.split(/\s+/);
+        const mode = parts[0];
+        if (mode.startsWith('l') || mode.startsWith('s')) {
+          throw new Error(`Symlinks or special files in archive rejected: ${line}`);
+        }
+      }
+      const listing = execFileSync('tar', ['-tf', archivePath], { encoding: 'utf8' }).split('\n').filter(Boolean);
+      for (const entry of listing) {
+        const entryParts = entry.replace(/\\/g, '/').split('/');
+        if (entryParts.includes('..') || entry.startsWith('/') || entry.startsWith('\\') || /^[a-zA-Z]:/.test(entry)) {
+          throw new Error(`Dangerous member in archive rejected: ${entry}`);
+        }
+      }
+      execFileSync('tar', ['-xzf', archivePath, '-C', extractDir]);
+    }
+
+    let topDir = extractDir;
+    const entries = fs.readdirSync(extractDir);
+    if (entries.length === 1 && fs.statSync(path.join(extractDir, entries[0])).isDirectory()) {
+      topDir = path.join(extractDir, entries[0]);
+    }
+
+    const binName = platform === 'win32' ? 'aistudio2api.exe' : 'aistudio2api';
+    const foundBin = path.join(topDir, binName);
+    if (!fs.existsSync(foundBin)) {
+      throw new Error(`Could not find ${binName} in extracted package`);
+    }
+    fs.chmodSync(foundBin, 0o755);
+
+    const binarySha256 = computeFileHash(foundBin);
+    const manifestPath = path.join(dataDir, 'install-manifest.json');
+    const oldManifestExists = fs.existsSync(manifestPath);
+    const oldManifestBytes = oldManifestExists ? fs.readFileSync(manifestPath) : null;
+
+    const finalPackageDir = path.join(dataDir, 'package');
+    const stagePackageDir = path.join(dataDir, `.package.stage.${crypto.randomBytes(4).toString('hex')}`);
+    const backupPackageDir = path.join(dataDir, `.package.backup.${crypto.randomBytes(4).toString('hex')}`);
+
+    fs.renameSync(topDir, stagePackageDir);
+
+    let hasBackup = false;
+    let installedNewFinal = false;
+    if (fs.existsSync(finalPackageDir)) {
+      fs.renameSync(finalPackageDir, backupPackageDir);
+      hasBackup = true;
+    }
+
+    try {
+      fs.renameSync(stagePackageDir, finalPackageDir);
+      installedNewFinal = true;
+
+      const manifest = {
+        version: release.version,
+        platform,
+        arch,
+        archiveSha256: expectedHash,
+        binarySha256
+      };
+      const tmpManifest = `${manifestPath}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+      fs.writeFileSync(tmpManifest, JSON.stringify(manifest, null, 2) + '\n', { mode: 0o600 });
+      fs.renameSync(tmpManifest, manifestPath);
+      fs.chmodSync(manifestPath, 0o600);
+
+      ensureStudioConfig(dataDir, options.proxy, { port });
+
+      if (hasBackup) {
+        fs.rmSync(backupPackageDir, { recursive: true, force: true });
+      }
+      removeOtherArchives(dataDir, pin.asset);
+    } catch (swapErr) {
+      if (installedNewFinal) {
+        try { fs.rmSync(finalPackageDir, { recursive: true, force: true }); } catch {}
+      }
+      if (hasBackup) {
+        try { fs.renameSync(backupPackageDir, finalPackageDir); } catch {}
+      }
+      if (oldManifestExists && oldManifestBytes) {
+        try { fs.writeFileSync(manifestPath, oldManifestBytes, { mode: 0o600 }); } catch {}
+      } else {
+        try { fs.rmSync(manifestPath, { force: true }); } catch {}
+      }
+      throw swapErr;
+    }
+  } finally {
+    fs.rmSync(stageDir, { recursive: true, force: true });
+  }
+
+  return localStudio({ dataDir, platform });
+}
+
+// removeOtherArchives deletes the release archives earlier installs kept, all but keep.
+function removeOtherArchives(dataDir, keep) {
+  for (const name of fs.readdirSync(dataDir)) {
+    if (name !== keep && /^aistudio2api-v[^/\\]+\.(?:tar\.gz|zip)$/.test(name)) {
+      try { fs.rmSync(path.join(dataDir, name), { force: true }); } catch {}
+    }
+  }
+}
+
+// readyStudio waits until the service takes generation requests, starting it when stopped.
+// Once it is RUNNING it takes them: with no account ready, the backend answers each request
+// saying why, so there is nothing to wait for.
+async function readyStudio(local, initial, options = {}) {
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  let status = initial;
+  if (status.running || status.accounts.total === 0) return local;
+  if (status.state === 'STOPPED' && !needsSignIn(status.accounts)) {
+    await studioAdmin(local, 'POST', '/api/control/start', null, { fetchFn, timeoutMs: 180000 });
+  }
+  const deadline = Date.now() + (options.generationTimeoutMs ?? 120000);
+  for (;;) {
+    if (status.running) return local;
+    if (needsSignIn(status.accounts)) {
+      throw new Error(`AI Studio cannot start: its Google accounts need to sign in again (${status.accounts.auth_required} of ${status.accounts.total}). In Magpie, sign in to AI Studio with "重新登录失效的 AI Studio 账号", or run: ${studioCommand('relogin')}`);
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(`AI Studio generation did not become ready (state ${status.state}, ${status.accounts.ready ?? 0}/${status.accounts.total} accounts ready); see ${path.join(local.dataDir, 'backend.log')}`);
+    }
+    await sleep(Math.min(250, Math.max(1, deadline - Date.now())));
+    const h = await checkStudioHealth(local, fetchFn);
+    if (h.state === 'unresponsive') continue;
+    if (h.state !== 'up') throw new Error('AI Studio became unavailable while starting');
+    status = h.status;
+  }
+}
+
+// needsSignIn says whether no account can serve until one signs in again: none is ready, busy
+// or cooling down, and some need to sign in.
+function needsSignIn(accounts) {
+  const usable = (accounts.ready ?? 0) + (accounts.busy ?? 0) + (accounts.cooldown ?? 0);
+  return usable === 0 && (accounts.auth_required ?? 0) > 0;
+}
+
+// settle waits out a service that answers but not properly, as one does while it starts, for up
+// to ms.
+async function settle(local, health, fetchFn, ms) {
+  const deadline = Date.now() + ms;
+  while (health.state === 'unresponsive' && Date.now() < deadline) {
+    await sleep(250);
+    health = await checkStudioHealth(local, fetchFn);
+  }
+  return health;
+}
+
+function portTaken(local) {
+  return new Error(`Port ${local.port} is already used by another service; change "port" in ${path.join(local.dataDir, 'config.json')}`);
+}
+
+function notResponding(local, health) {
+  return new Error(`The AI Studio service on port ${local.port} is not responding (${health.reason}). If it is stuck, run: ${studioCommand('stop')}; if another program uses the port, change "port" in ${path.join(local.dataDir, 'config.json')}`);
+}
+
+// rotateLog sets a log past LOG_ROTATE_BYTES aside as <log>.1, replacing the one before.
+function rotateLog(logPath) {
+  try {
+    if (fs.statSync(logPath).size > LOG_ROTATE_BYTES) fs.renameSync(logPath, `${logPath}.1`);
+  } catch {}
+}
+
+// shared runs fn once for key while it is in flight: later callers get the same promise.
+function shared(map, key, fn) {
+  if (!map.has(key)) map.set(key, fn().finally(() => map.delete(key)));
+  return map.get(key);
+}
+
+// ensureStudio makes sure the service is installed and running, and, unless managementOnly,
+// that it takes generation requests. Callers share one start of the service and one wait for
+// it to take requests; a managementOnly caller doesn't wait for the latter.
+export async function ensureStudio(options = {}) {
+  const dataDir = options.dataDir || studioDataDir();
+  const { local, status } = await shared(inFlightStarts, dataDir, () => launchStudio({ ...options, dataDir }));
+  if (options.managementOnly) return local;
+  return shared(inFlightReady, dataDir, () => readyStudio(local, status, options));
+}
+
+// launchStudio gets the service up, installing it when missing, outdated or untrusted, and
+// returns how to reach it with the status it last reported.
+async function launchStudio(options) {
+  const { dataDir } = options;
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const spawnFn = options.spawnFn || spawn;
+  const startTimeoutMs = options.startTimeoutMs ?? 60000;
+
+  let local = localStudio({ dataDir, platform });
+  if (local) {
+    const health = await checkStudioHealth(local, fetchFn);
+    if (health.state === 'up') return { local, status: health.status };
+    if (health.state === 'foreign') throw portTaken(local);
+  }
+
+  fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+  return withLock(dataDir, async () => {
+    local = localStudio({ dataDir, platform });
+    if (local) {
+      const health = await settle(local, await checkStudioHealth(local, fetchFn), fetchFn, options.unresponsiveTimeoutMs ?? 10000);
+      if (health.state === 'up') return { local, status: health.status };
+      if (health.state === 'unresponsive') throw notResponding(local, health);
+      if (health.state === 'outdated') await stopOutdated(local, health, { dataDir, platform, fetchFn });
+    }
+
+    // Check config validity before touching binaries
+    const configPath = path.join(dataDir, 'config.json');
+    if (fs.existsSync(configPath)) {
+      validateConfig(JSON.parse(fs.readFileSync(configPath, 'utf8')));
+    }
+
+    const binPath = binaryPath(dataDir, platform);
+    const manifestPath = path.join(dataDir, 'install-manifest.json');
+    const pin = PINNED_ARCHIVES[`${platform}-${arch}`];
+    let manifestValid = false;
+
+    if (fs.existsSync(binPath) && fs.existsSync(manifestPath) && pin) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        const currentHash = computeFileHash(binPath);
+        if (
+          manifest.version === release.version &&
+          manifest.platform === platform &&
+          manifest.arch === arch &&
+          manifest.archiveSha256 === pin.sha256
+        ) {
+          if (currentHash === manifest.binarySha256) {
+            manifestValid = true;
+          } else {
+            throw new Error('Binary checksum verification failed (mutated binary refused on launch)');
+          }
+        }
+      } catch (err) {
+        if (err.message.includes('mutated binary')) throw err;
+      }
+    }
+
+    if (!manifestValid) {
+      await installStudio({ dataDir, platform, arch, fetchFn, archivePath: options.archivePath, proxy: options.proxy, preferredPort: options.preferredPort });
+    }
+
+    const config = ensureStudioConfig(dataDir, options.proxy, { port: await newConfigPort(dataDir, options) });
+    local = localStudio({ dataDir, platform });
+    if (!local) throw new Error(`Invalid AI Studio configuration in ${dataDir}`);
+
+    const health = await checkStudioHealth(local, fetchFn);
+    if (health.state === 'up') return { local, status: health.status };
+    if (health.state === 'foreign') throw portTaken(local);
+    if (health.state !== 'down') throw notResponding(local, health);
+
+    // Clean environment: no arbitrary host AISTUDIO_* or WAA_* vars
+    const cleanEnv = {};
+    for (const [k, v] of Object.entries(process.env)) {
+      if (!k.startsWith('AISTUDIO_') && !k.startsWith('WAA_')) {
+        cleanEnv[k] = v;
+      }
+    }
+    Object.assign(cleanEnv, serviceEnv(dataDir, config, { proxy: options.proxy }));
+
+    const logPath = path.join(dataDir, 'backend.log');
+    rotateLog(logPath);
+    const logFd = fs.openSync(logPath, 'a', 0o600);
+    try {
+      const child = spawnFn(binPath, ['-open-ui=false'], {
+        cwd: dataDir,
+        env: cleanEnv,
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+        windowsHide: true
+      });
+      child.on?.('error', () => {});
+      if (child.pid) {
+        fs.writeFileSync(path.join(dataDir, 'backend.pid'), `${child.pid}\n`, { mode: 0o600 });
+      }
+      child.unref?.();
+    } finally {
+      fs.closeSync(logFd);
+    }
+
+    // The service can answer with errors while it starts: only 'up' ends the wait.
+    const deadline = Date.now() + startTimeoutMs;
+    while (Date.now() < deadline) {
+      const h = await checkStudioHealth(local, fetchFn);
+      if (h.state === 'up') return { local, status: h.status };
+      if (h.state === 'foreign') throw portTaken(local);
+      if (h.state === 'outdated') {
+        throw new Error(`AIStudio2API on port ${local.port} reports version ${h.status.version}, expected ${STUDIO_VERSION}`);
+      }
+      await sleep(250);
+    }
+    throw new Error(`AI Studio service did not start within ${Math.round(startTimeoutMs / 1000)}s; see ${logPath}`);
+  });
+}
+
+// stopOutdated stops an earlier install of the service that is still running, so the pinned
+// version can be installed and started in its place.
+async function stopOutdated(local, health, options) {
+  const result = await stopStudio(options).catch(err => ({ stopped: false, reported: err.message }));
+  const after = await checkStudioHealth(local, options.fetchFn);
+  if (result.stopped && after.state === 'down') return;
+  const why = result.stopped ? `it still answers on port ${local.port}` : result.reported;
+  throw new Error(`AIStudio2API ${health.status.version} from an earlier install is still running and could not be stopped (${why}). End that process, then try again.`);
+}
+
+export async function stopStudio(options = {}) {
+  const dataDir = options.dataDir || studioDataDir();
+  const platform = options.platform || process.platform;
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const pidFile = path.join(dataDir, 'backend.pid');
+
+  const configPath = path.join(dataDir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    throw new Error('Cannot stop: missing configuration in data directory');
+  }
+  let local;
+  try {
+    local = localStudio({ dataDir, platform });
+    if (!local) throw new Error('invalid config');
+  } catch {
+    throw new Error('Cannot stop: invalid configuration in data directory');
+  }
+
+  let health = await checkStudioHealth(local, fetchFn);
+  if (health.state === 'foreign') {
+    throw new Error(`Cannot stop unknown or foreign process listening on port ${local.port}`);
+  }
+
+  let pid = NaN;
+  try {
+    pid = parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
+  } catch {}
+
+  let alive = Number.isInteger(pid) && pid > 0;
+  if (alive) {
+    try {
+      process.kill(pid, 0);
+    } catch {
+      alive = false;
+    }
+  }
+
+  // Without a live process in backend.pid there is nothing this setup can signal. That only
+  // means stopped when nothing answers on the port either.
+  if (!alive) {
+    fs.rmSync(pidFile, { force: true });
+    if (health.state === 'down') return { stopped: true };
+    return { stopped: false, reported: `AIStudio2API still answers on port ${local.port}, but ${pidFile} names no running process; end it yourself` };
+  }
+
+  const bin = binaryPath(dataDir, platform);
+  if (!verifyProcessIdentity(pid, bin, platform)) {
+    throw new Error(`Process ${pid} does not match expected binary path ${bin}; refusal to signal unverified process`);
+  }
+
+  health = await checkStudioHealth(local, fetchFn);
+  if (health.state === 'foreign') {
+    throw new Error(`Cannot stop unknown or foreign process listening on port ${local.port}`);
+  }
+
+  if (health.state === 'up' || health.state === 'outdated') {
+    try {
+      await studioAdmin(local, 'POST', '/api/control/stop', null, { fetchFn, timeoutMs: 5000 });
+    } catch {}
+  }
+
+  if (!verifyProcessIdentity(pid, bin, platform)) {
+    throw new Error(`Process identity changed before signal for PID ${pid}`);
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {}
+
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    try {
+      process.kill(pid, 0);
+      await sleep(150);
+    } catch {
+      alive = false;
+      break;
+    }
+  }
+
+  if (alive) {
+    return { stopped: false, reported: `Process ${pid} did not exit after SIGTERM` };
+  }
+
+  fs.rmSync(pidFile, { force: true });
+  return { stopped: true };
+}