@simonyea/holysheep-cli 2.0.4 → 2.0.6

package/README.md

@@ -107,6 +107,60 @@ If you forget the port, check `~/.openclaw/openclaw.json` (`gateway.port`) or ru
 | Anthropic SDK / Claude Code | `https://api.holysheep.ai` (no `/v1`) |
 | OpenAI-compatible / Codex / Aider | `https://api.holysheep.ai/v1` (with `/v1`) |
 
+### AionUi mode (experimental, opt-in)
+
+`hs web` ships a lightweight legacy WebUI by default — Windows / macOS / Linux, zero extra dependencies.
+
+For a richer UI, `hs web --aionui` boots the **AionUi runtime** behind a zero-dep Node proxy that turns your HolySheep API key into a one-click auto-login. No username, no password — your HS key **is** your credential.
+
+```bash
+# Regular install (legacy WebUI, always works, ~90 kB)
+npm install -g @simonyea/holysheep-cli
+
+# Optional — enable AionUi mode. Requires the AionUi runtime locally.
+hs web --aionui
+```
+
+**How it works**
+
+1. Wrapper on port `9876` (public) proxies to an AionUi server on `127.0.0.1:9877` (loopback-only).
+2. Your saved HolySheep API key is POSTed to AionUi's `/login` route, which returns a JWT cookie.
+3. A single-use bootstrap token (≤30 s TTL, loopback-only) copies the cookie into your browser → you land on `/guid` authenticated.
+4. `/api/holysheep/tools`, `/api/holysheep/balance`, `/api/holysheep/whoami` etc. are served directly by the wrapper (reuses the legacy handlers in-process, no cross-port coupling).
+
+**Runtime resolution order** (first match wins):
+
+1. `~/.holysheep/aionui-runtime/` (installed / cached)
+2. `<cli>/src/webui/vendor/aionui/` (developer checkout — not shipped to npm)
+3. `HOLYSHEEP_AIONUI_RUNTIME_URL` env var (advanced escape hatch — downloads + SHA256-verifies into `~/.holysheep/aionui-runtime/`)
+
+**Install the runtime — one-command** (recommended — 21 MB prebuilt, HolySheep-auth-ready):
+
+```bash
+export HOLYSHEEP_AIONUI_RUNTIME_URL=https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.17-holysheep.tar.gz
+export HOLYSHEEP_AIONUI_RUNTIME_SHA256=d75adcea3c57c85f64b5db96d18c593f20ad150888f47283dc2da0a440fb652c
+hs web --aionui --setup-runtime
+```
+
+The fetcher downloads to `~/.holysheep/aionui-runtime/`, verifies SHA256, extracts `dist-server/` + `out/` + `package.json`, boots AionUi, and opens your browser at the bootstrap redirect (auto-logged-in with your HS API key). Runs macOS / Linux. Windows support depends on `bun` availability.
+
+**Alternative — build from AionUi source** (advanced):
+
+```bash
+git clone https://github.com/iOfficeAI/AionUi.git ~/AionUi
+cd ~/AionUi && bun install && bun run build:renderer:web && bun run build:server
+mkdir -p ~/.holysheep/aionui-runtime
+cp -R ~/AionUi/{dist-server,out,package.json} ~/.holysheep/aionui-runtime/
+hs web --aionui
+```
+Note: upstream AionUi's `/login` still expects `{ username, password }`; the legacy wrapper path handles that via an auto-provisioned bridge admin in `~/.holysheep/aionui-bridge.json` (0600).
+
+**Recovery / advanced**
+
+- `/login` is still reachable at `http://127.0.0.1:9876/login` for direct apiKey entry.
+- To rotate credentials: `rm -rf ~/.holysheep/aionui-runtime && hs web --aionui --setup-runtime` (or edit `~/.holysheep/config.json`).
+- Startup logs showing `[AionUi] Could not find builtin src/process/resources/...` are harmless — the prebuilt tarball ships only `dist-server/` + `out/` (not the source tree), so template assistants/skills load from built-in fallbacks instead. The UI works fully; only the "source-tree" assistant templates are unavailable.
+
 ---
 
 <a name="chinese"></a>
@@ -198,21 +252,60 @@ npx openclaw gateway --port <显示的端口>
 | Anthropic SDK / Claude Code | `https://api.holysheep.ai`（不带 /v1） |
 | OpenAI 兼容 / Codex / Aider | `https://api.holysheep.ai/v1`（带 /v1） |
 
-### AionUi runtime（实验性，opt-in）
+### AionUi 模式（实验性，opt-in）
 
 `hs web` 默认启动轻量版 WebUI，所有平台（Windows / macOS / Linux）开箱即用，无额外依赖。
 
-还有一个实验性的 AionUi runtime 提供更丰富的界面，但它只随本地 `src/webui/vendor/` 目录存在（npm 包里不包含，保持 ~90 kB 体积），目前仅支持 **macOS arm64 + [Bun](https://bun.sh)**。
+要体验完整的 AionUi 界面，用 `hs web --aionui`。它会通过一个零依赖的 Node 代理把 AionUi 套在外面，**用 HolySheep API Key 代替账号密码**，一键自动登录。
+
+```bash
+# 普通安装（始终可用的轻量 WebUI）
+npm install -g @simonyea/holysheep-cli
+
+# 可选：启用 AionUi 模式（需本地安装 AionUi runtime）
+hs web --aionui
+```
+
+**原理**
 
-在有 vendor/ 的机器上启用：
+1. 代理监听公开端口 `9876`，将请求转发到 `127.0.0.1:9877` 上的 AionUi 服务（仅回环）。
+2. 自动将保存在 `~/.holysheep/config.json` 的 HS API Key POST 到 AionUi 的 `/login`，拿到 JWT cookie。
+3. 一次性 bootstrap token（≤30 s TTL，仅回环，拒绝 `X-Forwarded-For` / `X-Real-IP`）把 cookie 交给浏览器 → 用户直接落到 `/guid`，无需再输入任何凭据。
+4. `/api/holysheep/tools`、`/api/holysheep/balance`、`/api/holysheep/whoami` 等由代理自己就地处理（复用 legacy WebUI 的 handler，不跨端口），所以 HolySheep 多终端配置能力在 AionUi 界面里可用。
+
+**runtime 查找顺序**（命中即用）：
+
+1. `~/.holysheep/aionui-runtime/`（已安装 / 已缓存）
+2. `<cli>/src/webui/vendor/aionui/`（开发者本地仓库 —— npm 包不携带）
+3. `HOLYSHEEP_AIONUI_RUNTIME_URL` 环境变量（高级逃生口 —— 下载 + SHA256 校验后写入 `~/.holysheep/aionui-runtime/`）
+
+**安装 runtime —— 一条命令**（推荐，21 MB 预编译包，内置 HolySheep Key 登录）：
 
 ```bash
-# 单次
-HOLYSHEEP_WEBUI_AIONUI=1 hs web
+export HOLYSHEEP_AIONUI_RUNTIME_URL=https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.17-holysheep.tar.gz
+export HOLYSHEEP_AIONUI_RUNTIME_SHA256=d75adcea3c57c85f64b5db96d18c593f20ad150888f47283dc2da0a440fb652c
+hs web --aionui --setup-runtime
+```
+
+fetcher 会下载到 `~/.holysheep/aionui-runtime/`，校验 SHA256，解压 `dist-server/ + out/ + package.json`，启动 AionUi，然后直接把浏览器带到 bootstrap 重定向（用你的 HS API Key 自动登录）。macOS / Linux 都行，Windows 视 `bun` 支持情况而定。
 
-# 或写到 ~/.zshrc / ~/.bashrc
-export HOLYSHEEP_WEBUI_AIONUI=1
+**备用方案 —— 从 AionUi 源码构建**（高级用户）：
+
+```bash
+git clone https://github.com/iOfficeAI/AionUi.git ~/AionUi
+cd ~/AionUi && bun install && bun run build:renderer:web && bun run build:server
+mkdir -p ~/.holysheep/aionui-runtime
+cp -R ~/AionUi/{dist-server,out,package.json} ~/.holysheep/aionui-runtime/
+hs web --aionui
 ```
+注意：上游 AionUi 的 `/login` 仍然是账号密码模式；wrapper 会自动走 legacy 路径，在 `~/.holysheep/aionui-bridge.json` (0600) 建一个桥接管理员账号，不影响使用。
+
+**恢复 / 高级**
+
+- `/login` 仍可直接访问：`http://127.0.0.1:9876/login`，里面可以手动粘 HS API Key 再登录。
+- 要重置：`rm -rf ~/.holysheep/aionui-runtime && hs web --aionui --setup-runtime`，或直接编辑 `~/.holysheep/config.json`。
+- runtime 缺失时：`hs web --aionui` 会打印清晰的安装指引并自动回退到 legacy WebUI，不会静默失败。
+- 启动日志里 `[AionUi] Could not find builtin src/process/resources/...` 是已知噪音 —— 预编译 tarball 只带 `dist-server/` 和 `out/`，不含源码目录，所以模板 assistants/skills 会走内置 fallback。界面完全可用，只是少几个"源码级"模板。
 
 不设置该环境变量时 `hs web` 走 legacy WebUI，**不会再打印任何黄色警告**。
 
@@ -275,7 +368,7 @@ A: OpenClaw 需要 Node.js 20+，运行 `node --version` 确认版本后重试
 ## License
 
 MIT
-��持，自动写入配置并启动 Gateway
+��持，自动写入配置并启动 Gateway
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simonyea/holysheep-cli",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Claude Code/Cursor/Cline API relay for China — ¥1=$1, WeChat/Alipay payment, no credit card, no VPN. One command setup for all AI coding tools.",
   "scripts": {
     "test": "node tests/droid.test.js && node tests/workspace-store.test.js",

package/src/commands/webui.js

@@ -1,83 +1,155 @@
 /**
- * hs webui — 启动 WebUI 本地管理面板
+ * hs web — 启动 WebUI 本地管理面板
+ *
+ * Modes (resolution order):
+ *   --aionui                 → AionUi proxy wrapper (HolySheep API key login)
+ *   HOLYSHEEP_WEBUI_AIONUI=1 → same as --aionui (back-compat)
+ *   HOLYSHEEP_WEBUI_LEGACY=1 → no-op (legacy is already the default)
+ *   <none>                   → legacy WebUI (default, always ships in npm)
  */
 'use strict'
 
 const chalk = require('chalk')
 const { execSync } = require('child_process')
+const fs = require('fs')
+const path = require('path')
 
-// AionUi runtime is opt-in. The bundled vendor/ directory is stripped from
-// the npm package (see .npmignore) because it only works on darwin-arm64 and
-// bloated 2.0.2 to 160MB. Developers who keep vendor/ around locally can
-// still run AionUi via HOLYSHEEP_WEBUI_AIONUI=1. The legacy WebUI is the
-// default for everyone else.
-function shouldTryAionUi() {
+function wantsAionUi(opts) {
+  if (opts && opts.aionui) return true
   if (process.env.HOLYSHEEP_WEBUI_AIONUI === '1') return true
-  // Back-compat: HOLYSHEEP_WEBUI_LEGACY used to be the only way to force
-  // legacy. It now has no effect (legacy is already the default) but we
-  // intentionally don't crash if someone still sets it.
   return false
 }
 
-async function webui(opts) {
+function resolveBunPath() {
+  // Dev bundle: holysheep-cli/src/webui/vendor/bun-darwin-arm64
+  const bundledBun = path.join(__dirname, '..', 'webui', 'vendor', 'bun-darwin-arm64')
+  if (process.platform === 'darwin' && process.arch === 'arm64' && fs.existsSync(bundledBun)) {
+    return bundledBun
+  }
+  if (process.env.BUN && fs.existsSync(process.env.BUN)) return process.env.BUN
+  try {
+    const resolved = execSync('which bun', {
+      stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 2000,
+    }).trim()
+    return resolved || null
+  } catch { return null }
+}
+
+async function startAionUiMode(opts) {
   const port = Number(opts.port) || 9876
+  const { resolveRuntime, describeInstallGuidance } = require('../webui/aionui-runtime-fetcher')
+  const { startWrapper } = require('../webui/aionui-wrapper')
+  const { getApiKey } = require('../utils/config')
 
-  console.log()
-  console.log(chalk.bold('🌐  HolySheep WebUI'))
-  console.log(chalk.gray('━'.repeat(50)))
-  console.log()
+  const allowDownload = opts.setupRuntime || process.env.HOLYSHEEP_AIONUI_RUNTIME_URL
+  const runtime = await resolveRuntime({
+    allowDownload: !!allowDownload,
+    logger: (m) => console.log(chalk.gray(`  ${m}`)),
+  })
+
+  if (!runtime) {
+    console.log(chalk.red('✗ AionUi runtime not installed'))
+    console.log()
+    console.log(chalk.gray(describeInstallGuidance()))
+    console.log()
+    console.log(chalk.yellow('Falling back to legacy WebUI. Run `hs web --aionui --setup-runtime` once you provide HOLYSHEEP_AIONUI_RUNTIME_URL, or install manually.'))
+    console.log()
+    return startLegacyMode(opts)
+  }
+
+  const bunPath = resolveBunPath()
+  if (!bunPath) {
+    console.log(chalk.red('✗ bun is required to start the AionUi runtime (install: https://bun.sh)'))
+    console.log(chalk.yellow('Falling back to legacy WebUI.'))
+    return startLegacyMode(opts)
+  }
+
+  console.log(chalk.cyan(`▶ AionUi mode (runtime: ${runtime.version}, source: ${runtime.source})`))
 
+  let handle
   try {
-    let child = null
-    let mode = 'legacy'
-
-    if (shouldTryAionUi()) {
-      try {
-        const { startAionUiRuntime } = require('../webui/aionui-runtime')
-        const result = await startAionUiRuntime(port)
-        child = result.child
-        mode = 'aionui'
-        console.log(chalk.green('✓ AionUi runtime 已接管 hs web'))
-      } catch (error) {
-        console.log(chalk.yellow(`! AionUi runtime 启动失败，回退旧版 WebUI: ${error.message}`))
-      }
-    }
+    handle = await startWrapper({
+      port,
+      runtimeDir: runtime.dir,
+      runtimeVersion: runtime.version,
+      runtimeSource: runtime.source,
+      bunPath,
+    })
+  } catch (e) {
+    console.log(chalk.red(`✗ AionUi wrapper failed to start: ${e.message}`))
+    console.log(chalk.yellow('Falling back to legacy WebUI.'))
+    return startLegacyMode(opts)
+  }
 
-    if (!child) {
-      const { startServer } = require('../webui/server')
-      await startServer(port)
-    }
+  const baseUrl = `http://127.0.0.1:${port}`
+  const apiKey = getApiKey()
 
-    const url = `http://127.0.0.1:${port}`
-    console.log(chalk.green(`✓ WebUI 已启动: ${chalk.cyan.bold(url)}`))
-    if (mode === 'aionui') {
-      console.log(chalk.gray('  当前模式: AionUi runtime'))
-    }
-    console.log(chalk.gray('  按 Ctrl+C 停止'))
-    console.log()
+  // Auto-bootstrap: if we already have an HS key, mint a single-use token and
+  // open the browser at /api/auth/holysheep-bootstrap?token=… so the user
+  // lands authenticated without touching AionUi's /login form.
+  let launchUrl = baseUrl
+  if (apiKey) {
+    const token = handle.mintBootstrapToken()
+    launchUrl = `${baseUrl}/api/auth/holysheep-bootstrap?token=${token}`
+    console.log(chalk.green(`✓ HolySheep API key detected — auto-login via bootstrap token`))
+  } else {
+    console.log(chalk.yellow(`! No HolySheep API key saved. POST it to ${baseUrl}/api/auth/holysheep-login or run 'hs login' first.`))
+  }
 
-    if (opts.open !== false) {
-      try {
-        const platform = process.platform
-        if (platform === 'darwin') execSync(`open "${url}"`)
-        else if (platform === 'win32') execSync(`start "" "${url}"`)
-        else execSync(`xdg-open "${url}"`)
-      } catch {}
-    }
+  console.log(chalk.green(`✓ WebUI 已启动: ${chalk.cyan.bold(launchUrl)}`))
+  console.log(chalk.gray('  Mode: AionUi runtime + HolySheep API key bridge'))
+  console.log(chalk.gray('  Press Ctrl+C to stop'))
+  console.log()
 
-    if (child) {
-      const stopChild = () => {
-        if (!child.killed) child.kill('SIGTERM')
-      }
-      process.on('SIGINT', stopChild)
-      process.on('SIGTERM', stopChild)
-      child.on('exit', (code) => {
-        process.exit(code || 0)
-      })
-    }
+  if (opts.open !== false) {
+    try {
+      const platform = process.platform
+      if (platform === 'darwin') execSync(`open "${launchUrl}"`)
+      else if (platform === 'win32') execSync(`start "" "${launchUrl}"`)
+      else execSync(`xdg-open "${launchUrl}"`)
+    } catch {}
+  }
+
+  const stopChildren = () => {
+    try { handle.aionui.kill('SIGTERM') } catch {}
+    try { handle.server.close() } catch {}
+  }
+  process.on('SIGINT', stopChildren)
+  process.on('SIGTERM', stopChildren)
+
+  await new Promise(() => {})
+}
+
+async function startLegacyMode(opts) {
+  const port = Number(opts.port) || 9876
+  const { startServer } = require('../webui/server')
+  await startServer(port)
+  const url = `http://127.0.0.1:${port}`
+  console.log(chalk.green(`✓ WebUI 已启动: ${chalk.cyan.bold(url)}`))
+  console.log(chalk.gray('  按 Ctrl+C 停止'))
+  console.log()
+  if (opts.open !== false) {
+    try {
+      const platform = process.platform
+      if (platform === 'darwin') execSync(`open "${url}"`)
+      else if (platform === 'win32') execSync(`start "" "${url}"`)
+      else execSync(`xdg-open "${url}"`)
+    } catch {}
+  }
+  await new Promise(() => {})
+}
 
-    // Keep alive
-    await new Promise(() => {})
+async function webui(opts) {
+  console.log()
+  console.log(chalk.bold('🌐  HolySheep WebUI'))
+  console.log(chalk.gray('━'.repeat(50)))
+  console.log()
+
+  try {
+    if (wantsAionUi(opts)) {
+      return await startAionUiMode(opts)
+    }
+    return await startLegacyMode(opts)
   } catch (err) {
     console.log(chalk.red(`✗ 启动失败: ${err.message}`))
     process.exit(1)

package/src/index.js

@@ -174,9 +174,11 @@ program
 program
   .command('web')
   .alias('webui')
-  .description('启动 WebUI 本地管理面板')
+  .description('启动 WebUI 本地管理面板 (--aionui 启用 AionUi 界面 + HolySheep API Key 登录)')
   .option('-p, --port <port>', '指定端口', '9876')
   .option('--no-open', '不自动打开浏览器')
+  .option('--aionui', '使用 AionUi 运行时 (需本地已安装 runtime；npm 包不打包，保持轻量)')
+  .option('--setup-runtime', '允许首次运行时从 HOLYSHEEP_AIONUI_RUNTIME_URL 下载 AionUi runtime')
   .action(async (opts) => {
     printBanner()
     await require('./commands/webui')(opts)

package/src/webui/aionui-runtime-fetcher.js

@@ -0,0 +1,177 @@
+/**
+ * AionUi runtime resolver
+ *
+ * Resolution order:
+ *   1. ~/.holysheep/aionui-runtime/  (installed / cached)
+ *   2. <cli>/src/webui/vendor/aionui/  (dev checkout — not shipped to npm)
+ *   3. HOLYSHEEP_AIONUI_RUNTIME_URL env var  (advanced user escape hatch,
+ *      downloads + SHA256-verifies when the constant below is also populated)
+ *   4. null → caller must show a clear "runtime not installed" error
+ *
+ * We DO NOT ship a hard-coded GitHub Release URL in this version because
+ * the release asset has not been uploaded yet. Shipping a 404 URL is a
+ * "code that lies" anti-pattern — explicit null + clear error message is
+ * honest. A follow-up PR will add the URL + SHA256 constant once the
+ * prebuilt tarball is published.
+ */
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const crypto = require('crypto')
+const https = require('https')
+const http = require('http')
+
+const USER_CACHE_DIR = path.join(os.homedir(), '.holysheep', 'aionui-runtime')
+const VENDOR_DIR = path.join(__dirname, 'vendor', 'aionui')
+
+function isValidRuntimeDir(dir) {
+  if (!dir) return false
+  try {
+    return (
+      fs.existsSync(path.join(dir, 'dist-server', 'server.mjs')) &&
+      fs.existsSync(path.join(dir, 'out', 'renderer', 'index.html'))
+    )
+  } catch {
+    return false
+  }
+}
+
+function readVersion(dir) {
+  try {
+    const pkgPath = path.join(dir, 'package.json')
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+      return pkg.version || 'unknown'
+    }
+  } catch {}
+  return 'unknown'
+}
+
+/**
+ * Resolve an AionUi runtime directory.
+ * @returns {{ dir: string, version: string, source: 'user-cache'|'vendor'|'env-download' } | null}
+ */
+async function resolveRuntime({ allowDownload = false, logger = () => {} } = {}) {
+  // 1. User cache
+  if (isValidRuntimeDir(USER_CACHE_DIR)) {
+    return { dir: USER_CACHE_DIR, version: readVersion(USER_CACHE_DIR), source: 'user-cache' }
+  }
+
+  // 2. Dev vendor checkout
+  if (isValidRuntimeDir(VENDOR_DIR)) {
+    return { dir: VENDOR_DIR, version: readVersion(VENDOR_DIR), source: 'vendor' }
+  }
+
+  // 3. Environment-provided download URL (advanced escape hatch)
+  const url = process.env.HOLYSHEEP_AIONUI_RUNTIME_URL
+  const expectedSha = process.env.HOLYSHEEP_AIONUI_RUNTIME_SHA256
+  if (url && allowDownload) {
+    try {
+      await downloadAndExtract(url, USER_CACHE_DIR, expectedSha, logger)
+      if (isValidRuntimeDir(USER_CACHE_DIR)) {
+        return { dir: USER_CACHE_DIR, version: readVersion(USER_CACHE_DIR), source: 'env-download' }
+      }
+      logger('AionUi runtime downloaded but directory structure invalid')
+    } catch (e) {
+      logger(`AionUi runtime download failed: ${e.message}`)
+    }
+  }
+
+  return null
+}
+
+/**
+ * Download a tar.gz from url, verify optional SHA256, extract into destDir.
+ * Uses only Node built-ins (https + tar via exec) — zero new deps.
+ */
+function downloadAndExtract(url, destDir, expectedSha, logger) {
+  return new Promise((resolve, reject) => {
+    const tmpFile = path.join(os.tmpdir(), `aionui-runtime-${Date.now()}.tar.gz`)
+    logger(`Downloading AionUi runtime from ${url}`)
+
+    const client = url.startsWith('https:') ? https : http
+    const file = fs.createWriteStream(tmpFile)
+    const hasher = crypto.createHash('sha256')
+    let totalBytes = 0
+
+    const req = client.get(url, (res) => {
+      // Follow redirects (GitHub Releases → S3 CDN)
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        file.close()
+        fs.unlinkSync(tmpFile)
+        return resolve(downloadAndExtract(res.headers.location, destDir, expectedSha, logger))
+      }
+      if (res.statusCode !== 200) {
+        file.close()
+        try { fs.unlinkSync(tmpFile) } catch {}
+        return reject(new Error(`HTTP ${res.statusCode} from ${url}`))
+      }
+      res.on('data', (chunk) => {
+        hasher.update(chunk)
+        totalBytes += chunk.length
+      })
+      res.pipe(file)
+      file.on('finish', () => {
+        file.close(() => {
+          const actualSha = hasher.digest('hex')
+          if (expectedSha && expectedSha.toLowerCase() !== actualSha.toLowerCase()) {
+            try { fs.unlinkSync(tmpFile) } catch {}
+            return reject(new Error(`SHA256 mismatch: expected ${expectedSha}, got ${actualSha}`))
+          }
+          logger(`Downloaded ${(totalBytes / 1024 / 1024).toFixed(1)} MB, sha256=${actualSha.slice(0, 12)}…`)
+          try {
+            fs.mkdirSync(destDir, { recursive: true })
+            const { execSync } = require('child_process')
+            execSync(`tar -xzf "${tmpFile}" -C "${destDir}" --strip-components=0`, { stdio: 'ignore' })
+            fs.unlinkSync(tmpFile)
+            resolve()
+          } catch (e) {
+            try { fs.unlinkSync(tmpFile) } catch {}
+            reject(new Error(`extract failed: ${e.message}`))
+          }
+        })
+      })
+    })
+
+    req.on('error', (e) => {
+      file.close()
+      try { fs.unlinkSync(tmpFile) } catch {}
+      reject(e)
+    })
+    req.setTimeout(120_000, () => {
+      req.destroy(new Error('download timeout (120s)'))
+    })
+  })
+}
+
+function describeInstallGuidance() {
+  return [
+    'AionUi runtime not installed. To enable `hs web --aionui`, install it via ONE of:',
+    '',
+    '  Option 1 — Build from source (requires bun):',
+    '    git clone https://github.com/iOfficeAI/AionUi.git ~/AionUi',
+    '    cd ~/AionUi && bun install && bun run build:renderer:web && bun run build:server',
+    `    mkdir -p ${USER_CACHE_DIR}`,
+    `    cp -R ~/AionUi/{dist-server,out,package.json} ${USER_CACHE_DIR}/`,
+    '',
+    '  Option 2 — Supply a prebuilt tarball URL:',
+    '    export HOLYSHEEP_AIONUI_RUNTIME_URL=https://your.host/aionui-runtime.tar.gz',
+    '    export HOLYSHEEP_AIONUI_RUNTIME_SHA256=<sha256>',
+    '    hs web --aionui',
+    '',
+    '  Option 3 — Fall back to legacy WebUI:',
+    '    hs web',
+  ].join('\n')
+}
+
+module.exports = {
+  USER_CACHE_DIR,
+  VENDOR_DIR,
+  isValidRuntimeDir,
+  readVersion,
+  resolveRuntime,
+  describeInstallGuidance,
+}

package/src/webui/aionui-wrapper.js

@@ -0,0 +1,646 @@
+/**
+ * AionUi wrapper — zero-dep Node http proxy in front of AionUi.
+ *
+ * Architecture:
+ *   user browser :9876 (this wrapper)
+ *     ├─ POST /api/auth/holysheep-login      → validate HS key, mint bootstrap token
+ *     ├─ GET  /api/auth/holysheep-bootstrap  → loopback-only, one-shot, copy AionUi cookie, 302 /
+ *     ├─ GET  /api/holysheep/status|tools|config
+ *     ├─ POST /api/holysheep/login (alias for holysheep-login, convenience)
+ *     ├─ POST /api/holysheep/setup/:tool, install, launch, configure, reset
+ *     └─ *                                    → proxied to AionUi 127.0.0.1:<internalPort>
+ *                                                  + WebSocket upgrade support
+ *
+ * Security invariants:
+ *   - AionUi server binds 127.0.0.1 only (ALLOW_REMOTE never set)
+ *   - /api/auth/holysheep-bootstrap refuses non-loopback remoteAddress
+ *   - /api/auth/holysheep-bootstrap refuses X-Forwarded-For / X-Real-IP
+ *   - Bootstrap tokens: single-use, ≤ 30s TTL, 24-byte CSRNG random
+ *   - Bridge admin credential file perms enforced 0600, startup refuses otherwise
+ *   - Bridge credential never logged — only the masked form
+ *
+ * Vendor independence:
+ *   AionUi's dist-server/server.mjs is NEVER modified. We speak HTTP to it.
+ */
+
+'use strict'
+
+const http = require('http')
+const net = require('net')
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const crypto = require('crypto')
+const { execSync, spawn } = require('child_process')
+
+const {
+  getApiKey, loadConfig, saveConfig,
+  BASE_URL_OPENAI,
+} = require('../utils/config')
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const BRIDGE_DIR = path.join(os.homedir(), '.holysheep')
+const BRIDGE_CRED_FILE = path.join(BRIDGE_DIR, 'aionui-bridge.json')
+const TOKEN_TTL_MS = 30_000
+const INTERNAL_PORT_START = 9877
+const INTERNAL_PORT_TRIES = 10
+const UPSTREAM_STARTUP_TIMEOUT_MS = 25_000
+const UPSTREAM_CONNECT_TIMEOUT_MS = 30_000
+
+// Bootstrap token store — Map<token, { createdAt, used }>
+const bootstrapTokens = new Map()
+
+// Periodic GC so idle wrappers don't grow memory unboundedly. .unref() so the
+// timer doesn't block process exit on SIGINT. No-op if TTL-cleanup already
+// happened via the lazy path in pruneExpiredTokens().
+let tokenCleanupInterval = null
+function startTokenCleanup() {
+  if (tokenCleanupInterval) return
+  tokenCleanupInterval = setInterval(() => pruneExpiredTokens(), 60_000)
+  if (typeof tokenCleanupInterval.unref === 'function') tokenCleanupInterval.unref()
+}
+
+// Cached AionUi session cookie obtained by internal /login. Refreshed lazily.
+let cachedAionUiCookie = null
+let cachedAionUiCookieAt = 0
+const AIONUI_COOKIE_TTL_MS = 10 * 60 * 1000
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function log(msg) {
+  // eslint-disable-next-line no-console
+  console.log(`[aionui-wrapper] ${msg}`)
+}
+
+function randomToken(bytes = 24) {
+  return crypto.randomBytes(bytes).toString('hex')
+}
+
+function randomPassword() {
+  // 24-char URL-safe password. Long enough for bcrypt, avoids shell-meta headaches.
+  return crypto.randomBytes(18).toString('base64').replace(/[+/=]/g, '').slice(0, 24)
+}
+
+function nowMs() { return Date.now() }
+
+function isLoopbackRequest(req) {
+  if (req.headers['x-forwarded-for']) return false
+  if (req.headers['x-real-ip']) return false
+  const addr = req.socket.remoteAddress || ''
+  return addr === '127.0.0.1' || addr === '::1' || addr === '::ffff:127.0.0.1'
+}
+
+function sendJson(res, statusCode, body) {
+  const payload = JSON.stringify(body)
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(payload),
+  })
+  res.end(payload)
+}
+
+function readBody(req, maxBytes = 1024 * 512) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (c) => {
+      size += c.length
+      if (size > maxBytes) {
+        reject(new Error('payload too large'))
+        try { req.destroy() } catch {}
+        return
+      }
+      chunks.push(c)
+    })
+    req.on('end', () => {
+      try {
+        const raw = Buffer.concat(chunks).toString('utf8')
+        if (!raw) return resolve({})
+        if (req.headers['content-type']?.includes('application/json')) {
+          return resolve(JSON.parse(raw))
+        }
+        resolve({ _raw: raw })
+      } catch (e) { reject(e) }
+    })
+    req.on('error', reject)
+  })
+}
+
+function pruneExpiredTokens() {
+  const now = nowMs()
+  for (const [t, meta] of bootstrapTokens) {
+    if (meta.used || now - meta.createdAt > TOKEN_TTL_MS) {
+      bootstrapTokens.delete(t)
+    }
+  }
+}
+
+// ── Bridge credential: persistent admin user for AionUi internal /login ──────
+
+function ensureBridgeDir() {
+  if (!fs.existsSync(BRIDGE_DIR)) fs.mkdirSync(BRIDGE_DIR, { recursive: true, mode: 0o700 })
+}
+
+function loadBridgeCredentials() {
+  if (!fs.existsSync(BRIDGE_CRED_FILE)) return null
+  try {
+    // Enforce 0600 perms — world-readable bridge creds defeat the whole loopback story
+    const stat = fs.statSync(BRIDGE_CRED_FILE)
+    if (process.platform !== 'win32' && (stat.mode & 0o077)) {
+      throw new Error(
+        `Refusing to read ${BRIDGE_CRED_FILE} with perms ${(stat.mode & 0o777).toString(8)} — ` +
+        `must be 0600. Run: chmod 600 ${BRIDGE_CRED_FILE}`
+      )
+    }
+    return JSON.parse(fs.readFileSync(BRIDGE_CRED_FILE, 'utf8'))
+  } catch (e) {
+    if (e.message.startsWith('Refusing')) throw e
+    return null
+  }
+}
+
+function saveBridgeCredentials(creds) {
+  ensureBridgeDir()
+  fs.writeFileSync(BRIDGE_CRED_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 })
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(BRIDGE_CRED_FILE, 0o600) } catch {}
+  }
+}
+
+/**
+ * The vendored AionUi v1.9.17 build has already been customized upstream so
+ * that `POST /login` accepts `{ apiKey }` (NOT username/password) and validates
+ * against HolySheep. That means the wrapper does NOT need to provision or
+ * maintain a bridge admin password at all — we simply forward the HS API key
+ * to AionUi's own /login endpoint.
+ *
+ * The `loadBridgeCredentials()` / `saveBridgeCredentials()` helpers remain
+ * above as a fallback codepath for any AionUi build that still uses legacy
+ * username/password auth. When the vendored build is HolySheep-aware
+ * (detected below), we prefer the direct apiKey-to-/login path.
+ */
+function detectHolySheepAionUi(runtimeDir) {
+  try {
+    const serverPath = path.join(runtimeDir, 'dist-server', 'server.mjs')
+    // Scan for the HolySheep validation marker — fast regex, file is large
+    // but we stop after finding the first match.
+    const buf = fs.readFileSync(serverPath, 'utf8')
+    return buf.includes('validateHolySheepApiKey') ||
+           buf.includes('HolySheep API key is required') ||
+           buf.includes('HOLYSHEEP_PROVIDER_NAME')
+  } catch { return false }
+}
+
+// ── Validate HolySheep API key ───────────────────────────────────────────────
+
+async function validateHolySheepKey(apiKey) {
+  // Reuse the same validation contract as `hs login`: GET /v1/models with Bearer.
+  const fetch = require('node-fetch')
+  try {
+    const res = await fetch(`${BASE_URL_OPENAI}/models`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+      timeout: 15_000,
+    })
+    return res.status === 200
+  } catch {
+    return false
+  }
+}
+
+// ── AionUi internal login: mint a cookie we can hand to the browser ──────────
+
+/**
+ * POST the HolySheep API key to the internal AionUi /login endpoint.
+ * AionUi's customized build (detectHolySheepAionUi above) accepts
+ * `{ apiKey: 'cr_...' }` and returns a JWT cookie via Set-Cookie.
+ * Works for vendored v1.9.17 and any future build that preserves this contract.
+ */
+function aionuiInternalLoginWithApiKey({ internalPort, apiKey }) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({ apiKey })
+    const req = http.request({
+      host: '127.0.0.1', port: internalPort, path: '/login', method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      },
+      timeout: 15_000,
+    }, (res) => {
+      let buf = ''
+      res.on('data', (c) => { buf += c.toString() })
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          return reject(new Error(`AionUi /login returned ${res.statusCode}: ${buf.slice(0, 200)}`))
+        }
+        const setCookie = res.headers['set-cookie']
+        if (!setCookie || setCookie.length === 0) {
+          return reject(new Error('AionUi /login succeeded but no Set-Cookie header returned'))
+        }
+        resolve(setCookie)
+      })
+    })
+    req.on('error', reject)
+    req.setTimeout(15_000, () => { req.destroy(new Error('AionUi /login timed out')) })
+    req.write(body)
+    req.end()
+  })
+}
+
+async function getAionUiCookieFresh({ internalPort }) {
+  if (cachedAionUiCookie && nowMs() - cachedAionUiCookieAt < AIONUI_COOKIE_TTL_MS) {
+    return cachedAionUiCookie
+  }
+  const apiKey = getApiKey()
+  if (!apiKey) throw new Error('no HolySheep API key — call /api/auth/holysheep-login first')
+  const cookies = await aionuiInternalLoginWithApiKey({ internalPort, apiKey })
+  cachedAionUiCookie = cookies
+  cachedAionUiCookieAt = nowMs()
+  return cookies
+}
+
+// ── Wrapper endpoint handlers ────────────────────────────────────────────────
+
+async function handleHolySheepLogin(req, res) {
+  try {
+    const body = await readBody(req)
+    const apiKey = (body.apiKey || '').trim()
+    if (!apiKey || !apiKey.startsWith('cr_')) {
+      return sendJson(res, 400, { success: false, message: 'API Key must start with cr_' })
+    }
+    const valid = await validateHolySheepKey(apiKey)
+    if (!valid) return sendJson(res, 401, { success: false, message: 'HolySheep API key invalid' })
+    saveConfig({ apiKey, savedAt: new Date().toISOString() })
+
+    // Issue bootstrap token. Browser will hit /api/auth/holysheep-bootstrap next.
+    pruneExpiredTokens()
+    const token = randomToken()
+    bootstrapTokens.set(token, { createdAt: nowMs(), used: false })
+    sendJson(res, 200, { success: true, bootstrapUrl: `/api/auth/holysheep-bootstrap?token=${token}` })
+  } catch (e) {
+    sendJson(res, 500, { success: false, message: e.message })
+  }
+}
+
+async function handleBootstrap(req, res, ctx) {
+  if (!isLoopbackRequest(req)) {
+    return sendJson(res, 403, { success: false, message: 'bootstrap endpoint is loopback-only' })
+  }
+  const url = new URL(req.url, `http://${req.headers.host}`)
+  const token = url.searchParams.get('token')
+  pruneExpiredTokens()
+  const entry = token ? bootstrapTokens.get(token) : null
+  if (!entry || entry.used || nowMs() - entry.createdAt > TOKEN_TTL_MS) {
+    return sendJson(res, 401, { success: false, message: 'bootstrap token invalid or expired' })
+  }
+  entry.used = true
+
+  try {
+    const cookies = await getAionUiCookieFresh({ internalPort: ctx.internalPort })
+    res.writeHead(302, {
+      'Set-Cookie': cookies,
+      'Location': '/',
+      'Cache-Control': 'no-store',
+    })
+    res.end()
+  } catch (e) {
+    sendJson(res, 502, { success: false, message: `AionUi bridge login failed: ${e.message}` })
+  }
+}
+
+async function handleHolySheepStatus(req, res) {
+  const apiKey = getApiKey()
+  sendJson(res, 200, {
+    loggedIn: !!apiKey,
+    apiKeyMasked: apiKey ? `${apiKey.slice(0, 6)}...${apiKey.slice(-4)}` : null,
+    mode: 'aionui-wrapper',
+    version: require('../../package.json').version,
+  })
+}
+
+// Reuse legacy handlers in-process — no cross-port hops.
+let legacyModule = null
+function legacy() {
+  if (!legacyModule) legacyModule = require('./server')
+  return legacyModule
+}
+
+// ── HTTP proxy to AionUi internal server ─────────────────────────────────────
+
+const BODYLESS_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+function proxyHttp(req, res, internalPort) {
+  const headers = { ...req.headers }
+  // Host header must match internal target for Express routing to behave consistently
+  headers.host = `127.0.0.1:${internalPort}`
+  // Strip hop-by-hop per RFC 7230 §6.1
+  delete headers['connection']
+  delete headers['keep-alive']
+  delete headers['proxy-connection']
+  delete headers['te']
+  delete headers['trailer']
+  delete headers['transfer-encoding']
+  delete headers['upgrade']
+
+  const upstream = http.request({
+    host: '127.0.0.1',
+    port: internalPort,
+    method: req.method,
+    path: req.url,
+    headers,
+    timeout: UPSTREAM_CONNECT_TIMEOUT_MS,
+  }, (upRes) => {
+    // Clone upstream headers; drop hop-by-hop coming back
+    const outHeaders = { ...upRes.headers }
+    delete outHeaders['connection']
+    delete outHeaders['keep-alive']
+    delete outHeaders['proxy-connection']
+    res.writeHead(upRes.statusCode, upRes.statusMessage, outHeaders)
+    upRes.pipe(res)
+  })
+  upstream.on('error', (e) => {
+    try {
+      if (!res.headersSent) res.writeHead(502, { 'Content-Type': 'text/plain' })
+      res.end(`upstream error: ${e.code || e.message}`)
+    } catch {}
+  })
+  upstream.on('timeout', () => {
+    try { upstream.destroy(new Error('upstream timeout')) } catch {}
+  })
+
+  // For body-less methods, end immediately — otherwise Node waits for `req` to
+  // emit 'end', which may have already fired for header-only IncomingMessages.
+  if (BODYLESS_METHODS.has((req.method || 'GET').toUpperCase())) {
+    upstream.end()
+  } else {
+    req.pipe(upstream)
+  }
+
+  // Client disconnect → kill upstream
+  req.on('close', () => { if (!upstream.destroyed) upstream.destroy() })
+}
+
+// ── WebSocket proxy (upgrade event) ──────────────────────────────────────────
+
+function proxyWebSocket(req, clientSocket, head, internalPort) {
+  const upstream = net.connect({ host: '127.0.0.1', port: internalPort }, () => {
+    // Replay upgrade request verbatim
+    const lines = [
+      `${req.method} ${req.url} HTTP/1.1`,
+      `Host: 127.0.0.1:${internalPort}`,
+    ]
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (k.toLowerCase() === 'host') continue
+      if (Array.isArray(v)) {
+        for (const vv of v) lines.push(`${k}: ${vv}`)
+      } else {
+        lines.push(`${k}: ${v}`)
+      }
+    }
+    upstream.write(lines.join('\r\n') + '\r\n\r\n')
+    if (head && head.length) upstream.write(head)
+
+    // Bidirectional pipe. `end: false` prevents premature close on one side dying.
+    upstream.pipe(clientSocket, { end: false })
+    clientSocket.pipe(upstream, { end: false })
+  })
+
+  const killBoth = (why) => {
+    try { upstream.destroy() } catch {}
+    try { clientSocket.destroy() } catch {}
+  }
+  upstream.on('error', killBoth)
+  upstream.on('close', () => killBoth('upstream-close'))
+  clientSocket.on('error', killBoth)
+  clientSocket.on('close', () => killBoth('client-close'))
+
+  // Prevent zombie connections on slow upstream
+  upstream.setTimeout(UPSTREAM_CONNECT_TIMEOUT_MS, () => killBoth('upstream-timeout'))
+}
+
+// ── Wait for internal AionUi server to become ready ──────────────────────────
+
+function waitForUpstreamReady(internalPort, timeoutMs = UPSTREAM_STARTUP_TIMEOUT_MS) {
+  const startedAt = nowMs()
+  return new Promise((resolve, reject) => {
+    const tick = () => {
+      const req = http.get({
+        host: '127.0.0.1', port: internalPort, path: '/', family: 4, timeout: 1500,
+      }, (res) => {
+        res.resume()
+        if (res.statusCode && res.statusCode < 500) return resolve(true)
+        retry()
+      })
+      req.on('error', retry)
+      req.on('timeout', () => { req.destroy(); retry() })
+    }
+    const retry = () => {
+      if (nowMs() - startedAt >= timeoutMs) return reject(new Error('upstream not ready in time'))
+      setTimeout(tick, 500)
+    }
+    tick()
+  })
+}
+
+// ── Find a free internal port ────────────────────────────────────────────────
+
+function findFreeInternalPort(start = INTERNAL_PORT_START, tries = INTERNAL_PORT_TRIES) {
+  for (let i = 0; i < tries; i++) {
+    const p = start + i
+    try {
+      const server = net.createServer()
+      // Sync-ish port probe using Node's listen on 127.0.0.1
+      const ok = new Promise((resolve) => {
+        server.once('error', () => resolve(false))
+        server.once('listening', () => { server.close(() => resolve(true)) })
+        server.listen(p, '127.0.0.1')
+      })
+      // eslint-disable-next-line no-unused-expressions
+      ok // we use the returned probe below
+      return { port: p, probe: ok }
+    } catch {}
+  }
+  return null
+}
+
+async function pickInternalPort() {
+  for (let i = 0; i < INTERNAL_PORT_TRIES; i++) {
+    const p = INTERNAL_PORT_START + i
+    const server = net.createServer()
+    const ok = await new Promise((resolve) => {
+      server.once('error', () => resolve(false))
+      server.once('listening', () => { server.close(() => resolve(true)) })
+      server.listen(p, '127.0.0.1')
+    })
+    if (ok) return p
+  }
+  throw new Error(`no free internal port in ${INTERNAL_PORT_START}..${INTERNAL_PORT_START + INTERNAL_PORT_TRIES - 1}`)
+}
+
+// ── Router ───────────────────────────────────────────────────────────────────
+
+function buildRouter(ctx) {
+  return async function onRequest(req, res) {
+    try {
+      const url = new URL(req.url, `http://${req.headers.host}`)
+      const route = url.pathname
+
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204, {
+          'Access-Control-Allow-Origin': '*',
+          'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+          'Access-Control-Allow-Headers': 'Content-Type',
+        })
+        return res.end()
+      }
+
+      // 1. HolySheep authentication endpoints
+      if (route === '/api/auth/holysheep-login' && req.method === 'POST') {
+        return await handleHolySheepLogin(req, res)
+      }
+      if (route === '/api/auth/holysheep-bootstrap' && req.method === 'GET') {
+        return await handleBootstrap(req, res, ctx)
+      }
+
+      // 2. HolySheep multi-tool config & status (reuse legacy handlers in-process)
+      if (route === '/api/holysheep/status' && req.method === 'GET') {
+        return await handleHolySheepStatus(req, res)
+      }
+      if (route === '/api/holysheep/tools' && req.method === 'GET') {
+        return await legacy().handleTools(req, res)
+      }
+      if (route === '/api/holysheep/models' && req.method === 'GET') {
+        return await legacy().handleModels(req, res)
+      }
+      if (route === '/api/holysheep/balance' && req.method === 'GET') {
+        return await legacy().handleBalance(req, res)
+      }
+      if (route === '/api/holysheep/doctor' && req.method === 'GET') {
+        return await legacy().handleDoctor(req, res)
+      }
+      if (route === '/api/holysheep/env' && req.method === 'GET') {
+        return legacy().handleEnv(req, res)
+      }
+      if (route === '/api/holysheep/whoami' && req.method === 'GET') {
+        return await legacy().handleWhoami(req, res)
+      }
+      // POST handlers: install, configure, reset, launch for a named tool
+      if (route === '/api/holysheep/tool/install' && req.method === 'POST') {
+        return await legacy().handleToolInstall(req, res)
+      }
+      if (route === '/api/holysheep/tool/configure' && req.method === 'POST') {
+        return await legacy().handleToolConfigure(req, res)
+      }
+      if (route === '/api/holysheep/tool/reset' && req.method === 'POST') {
+        return await legacy().handleToolReset(req, res)
+      }
+      if (route === '/api/holysheep/tool/launch' && req.method === 'POST') {
+        return await legacy().handleToolLaunch(req, res)
+      }
+
+      // 3. Health probe (wrapper itself)
+      if (route === '/api/holysheep/__wrapper/healthz') {
+        return sendJson(res, 200, {
+          ok: true,
+          wrapper: require('../../package.json').version,
+          aionuiRuntime: ctx.runtimeVersion,
+          aionuiSource: ctx.runtimeSource,
+        })
+      }
+
+      // 4. Default: proxy to AionUi
+      return proxyHttp(req, res, ctx.internalPort)
+    } catch (e) {
+      try {
+        if (!res.headersSent) sendJson(res, 500, { success: false, message: e.message })
+      } catch {}
+    }
+  }
+}
+
+// ── Public entry point ───────────────────────────────────────────────────────
+
+/**
+ * Start the wrapper.
+ * @param {object} opts
+ * @param {number} opts.port                public-facing port (e.g. 9876)
+ * @param {string} opts.runtimeDir          resolved AionUi runtime directory
+ * @param {string} opts.runtimeVersion      version string from package.json or 'unknown'
+ * @param {string} opts.runtimeSource       'user-cache' | 'vendor' | 'env-download'
+ * @param {string} opts.bunPath             path to bun binary
+ * @returns {Promise<{ server, aionui, internalPort, mintBootstrapToken }>}
+ */
+async function startWrapper({ port, runtimeDir, runtimeVersion, runtimeSource, bunPath }) {
+  // Detect if the vendored AionUi build natively speaks HolySheep auth.
+  // Vendored v1.9.17 does; upstream AionUi releases do not (use username/password).
+  const hsNative = detectHolySheepAionUi(runtimeDir)
+  log(`AionUi /login mode: ${hsNative ? 'holysheep-native (apiKey)' : 'legacy (username/password bridge)'}`)
+
+  // If the build is legacy username/password, eager pre-flight the bridge cred
+  // perms so a misconfigured file fails at boot rather than during a request.
+  if (!hsNative) {
+    loadBridgeCredentials() // throws if perms are wrong (0600 enforced on posix)
+  }
+
+  const internalPort = await pickInternalPort()
+  log(`internal AionUi port: ${internalPort}`)
+
+  // Spawn AionUi, bound 127.0.0.1 only (ALLOW_REMOTE never set)
+  const aionui = spawn(bunPath, ['dist-server/server.mjs'], {
+    cwd: runtimeDir,
+    env: {
+      ...process.env,
+      PORT: String(internalPort),
+      HOST: '127.0.0.1',
+      ALLOW_REMOTE: '',
+      NODE_ENV: 'production',
+    },
+    stdio: ['ignore', 'inherit', 'inherit'],
+  })
+  aionui.on('exit', (code) => {
+    log(`AionUi upstream exited (code=${code})`)
+    process.exit(code || 1)
+  })
+
+  await waitForUpstreamReady(internalPort)
+  log(`AionUi upstream ready (version=${runtimeVersion}, source=${runtimeSource})`)
+
+  const ctx = { internalPort, runtimeDir, runtimeVersion, runtimeSource, bunPath }
+  const server = http.createServer(buildRouter(ctx))
+  server.on('upgrade', (req, socket, head) => {
+    try {
+      proxyWebSocket(req, socket, head, internalPort)
+    } catch (e) {
+      try { socket.destroy() } catch {}
+    }
+  })
+  await new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, '127.0.0.1', resolve)
+  })
+  log(`wrapper listening on http://127.0.0.1:${port}`)
+  startTokenCleanup()
+
+  return {
+    server,
+    aionui,
+    internalPort,
+    mintBootstrapToken() {
+      pruneExpiredTokens()
+      const token = randomToken()
+      bootstrapTokens.set(token, { createdAt: nowMs(), used: false })
+      return token
+    },
+  }
+}
+
+module.exports = {
+  startWrapper,
+  // Exported for tests / inspection
+  isLoopbackRequest,
+  pruneExpiredTokens,
+  _tokens: bootstrapTokens,
+  TOKEN_TTL_MS,
+  BRIDGE_CRED_FILE,
+}

package/src/webui/server.js

@@ -1421,4 +1421,22 @@ async function bootstrapBackgroundServices() {
   } catch {}
 }
 
-module.exports = { startServer, bootstrapBackgroundServices }
+// Exported for in-process reuse by the AionUi wrapper.
+// Each handler is a pure `(req, res) => Promise<void>` and writes the HTTP response itself.
+module.exports = {
+  startServer,
+  bootstrapBackgroundServices,
+  // Handlers reused by src/webui/aionui-wrapper.js
+  handleTools,
+  handleSetup,
+  handleToolInstall,
+  handleToolConfigure,
+  handleToolReset,
+  handleToolLaunch,
+  handleBalance,
+  handleDoctor,
+  handleWhoami,
+  handleStatus,
+  handleModels,
+  handleEnv,
+}