@bitseek/hermes-webui 0.1.1 → 0.1.3

package/README.md

@@ -1,9 +1,6 @@
-# Bitseek Hermes WebUI
+# BitSeek Claw WebUI
 
-`@bitseek/hermes-webui` 用来在本机启动和管理 Bitseek Hermes WebUI。
-
-它是一个轻量级 npm 包装器，负责进程生命周期、健康检查、日志和运行时状态。
-WebUI 本体来自 vendored `agent-frontend-shell` 运行时。
+`@bitseek/hermes-webui` 用来在本机启动和管理 BitSeek Claw WebUI。
 
 ## 快速开始
 
@@ -39,7 +36,7 @@ hermes-webui start --port 8788 --open
 - 如果 WebUI 要调用 Hermes Agent，需要准备 Hermes Agent checkout，并确保其中有
   `run_agent.py`。
 
-默认情况下，包装器会尝试从以下位置查找 Hermes Agent：
+默认情况下，WebUI 会尝试从以下位置查找 Hermes Agent：
 
 ```text
 $HERMES_HOME/hermes-agent
@@ -79,13 +76,16 @@ hermes-webui doctor
 
 ## 首次启动会做什么
 
-第一次运行 `hermes-webui start` 时，包装器会：
+第一次运行 `hermes-webui start` 时，WebUI 会：
 
 - 创建运行时状态目录。
 - 创建并管理 Python venv。
-- 按 vendored WebUI 的 `requirements.txt` 安装 Python 依赖。
+- 安装 WebUI 所需的 Python 依赖。
+- 检查当前 Python 是否能导入 Hermes Agent；如果不能，会把
+  `HERMES_WEBUI_AGENT_DIR` 指向的 Hermes Agent 以 editable 模式安装到 WebUI
+  venv。
 - 默认启用 BitSeek 外观和扩展入口，包括 “AI 同事” 页面。
-- 启动 vendored `agent-frontend-shell/server.py`。
+- 启动 BitSeek Claw WebUI 服务。
 - 等待 `/health` 健康检查通过。
 - 把 PID、日志路径和运行时信息写入状态目录。
 
@@ -140,9 +140,8 @@ HERMES_WEBUI_EXTENSION_SCRIPT_URLS        默认 /extensions/themes/bitseek/inde
 HERMES_WEBUI_BOT_NAME                     默认 BitSeek Claw
 ```
 
-这些默认值在 macOS、Linux、Windows 上都可用。`./extensions` 会由 vendored
-WebUI 按运行时源码目录解析，不依赖当前 shell 的工作目录。显式设置同名环境变量
-可以覆盖默认值。
+这些默认值在 macOS、Linux、Windows 上都可用。显式设置同名环境变量可以覆盖
+默认值。
 
 示例：
 
@@ -152,7 +151,7 @@ export HERMES_WEBUI_AGENT_DIR="$HERMES_HOME/hermes-agent"
 hermes-webui start --port 8787 --open
 ```
 
-如果不想使用包装器管理的 venv，可以指定已有 Python：
+如果不想使用默认 venv，可以指定已有 Python：
 
 ```bash
 export HERMES_WEBUI_PYTHON=/usr/bin/python3
@@ -174,23 +173,14 @@ hermes-webui doctor
   `HERMES_WEBUI_PYTHON`。
 - `Hermes Agent dir: not found`：设置 `HERMES_WEBUI_AGENT_DIR` 指向包含
   `run_agent.py` 的 Hermes Agent 目录。
-- `Vendored agent-frontend-shell runtime is missing`：发布包缺少 vendored
-  运行时，需要维护者重新同步并发布包。
+- `AIAgent importable: fail`：当前 WebUI Python 不能导入 Hermes Agent。运行
+  `hermes-webui start` 会自动尝试修复；如果仍失败，请查看 `server.log` 和
+  `pip install -e` 的错误输出。
+- `WebUI runtime is missing`：发布包缺少必要文件，需要维护者重新打包并发布。
 
 ## 维护者说明
 
-打包的 WebUI 运行时来自：
-
-```text
-repo: adv-org/agent-frontend-shell
-branch: dev-zkp
-source checkout: /home/boj/hermes/agent-frontend-shell
-```
-
-该包装器不会把 Python + 原生 JavaScript WebUI 重写成 Node 应用，只负责用 npm
-包形式分发和启动 vendored 运行时。
-
-更新 vendored 运行时：
+同步 WebUI 文件：
 
 ```bash
 npm run sync:vendor
@@ -209,7 +199,7 @@ npm pack --dry-run
 bin/
 scripts/
 templates/
-vendor/agent-frontend-shell/
+vendor/
 README.md
 ```
 

package/bin/hermes-webui.mjs

@@ -218,6 +218,54 @@ function pythonImportsOk(python) {
   return result.status === 0
 }
 
+function aiAgentImportCheck(python, agentDir) {
+  if (!python || !agentDir) {
+    return { ok: false, error: 'python or Hermes Agent dir not found' }
+  }
+  const env = {
+    ...process.env,
+    HERMES_WEBUI_AGENT_DIR: agentDir,
+    PYTHONPATH: process.env.PYTHONPATH
+      ? `${agentDir}${delimiter}${process.env.PYTHONPATH}`
+      : agentDir,
+  }
+  const result = spawnSync(python, ['-c', 'from run_agent import AIAgent; print("ok")'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+    encoding: 'utf8',
+  })
+  return {
+    ok: result.status === 0,
+    error: (result.stderr || result.stdout || '').trim(),
+  }
+}
+
+function ensureAiAgentImportable(python, agentDir) {
+  if (!agentDir) return
+
+  let check = aiAgentImportCheck(python, agentDir)
+  if (check.ok) return
+
+  const pyprojectPath = join(agentDir, 'pyproject.toml')
+  if (!existsSync(pyprojectPath)) {
+    throw new Error(`Hermes Agent cannot be imported and pyproject.toml was not found: ${pyprojectPath}`)
+  }
+
+  console.log(`Installing Hermes Agent into WebUI Python env: ${agentDir}`)
+  const install = spawnSync(python, ['-m', 'pip', 'install', '-e', agentDir], {
+    stdio: 'inherit',
+    env: process.env,
+  })
+  if (install.status !== 0) {
+    throw new Error(`Failed to install Hermes Agent into WebUI Python env (exit ${install.status})`)
+  }
+
+  check = aiAgentImportCheck(python, agentDir)
+  if (!check.ok) {
+    throw new Error(`Hermes Agent still cannot be imported after install:\n${check.error}`)
+  }
+}
+
 function preparePython() {
   if (process.env.HERMES_WEBUI_PYTHON) {
     return resolve(expandHome(process.env.HERMES_WEBUI_PYTHON))
@@ -311,7 +359,7 @@ async function waitForHealth(host, port, child, timeoutMs = 30000) {
 
 async function start(options) {
   if (!existsSync(bootstrapPath) || !existsSync(serverPath)) {
-    throw new Error('Vendored agent-frontend-shell runtime is missing. Run npm run sync:vendor.')
+    throw new Error('WebUI runtime is missing. Run npm run sync:vendor.')
   }
 
   const existing = readPid()
@@ -329,6 +377,7 @@ async function start(options) {
   mkdirSync(paths.dir, { recursive: true })
   const python = preparePython()
   const env = buildEnv(python, options)
+  ensureAiAgentImportable(python, env.HERMES_WEBUI_AGENT_DIR)
   const args = [serverPath]
 
   if (options.foreground) {
@@ -383,7 +432,7 @@ async function start(options) {
     started_at: new Date().toISOString(),
   })
 
-  console.log(`Starting Bitseek Hermes WebUI (PID ${child.pid}, port ${options.port})...`)
+  console.log(`Starting BitSeek Claw WebUI (PID ${child.pid}, port ${options.port})...`)
   const health = await waitForHealth(options.host, options.port, child)
   if (!health.ok) {
     console.log(`Health check failed: ${health.error || health.status || 'unknown error'}`)
@@ -391,7 +440,7 @@ async function start(options) {
     process.exit(1)
   }
 
-  console.log('Bitseek Hermes WebUI started')
+  console.log('BitSeek Claw WebUI started')
   console.log(`URL: http://${options.host === '127.0.0.1' ? 'localhost' : options.host}:${options.port}`)
   console.log(`Log: ${paths.log}`)
   if (options.open) openBrowser(options.host, options.port)
@@ -408,13 +457,13 @@ async function stop() {
         process.exit(1)
       }
     }
-    console.log('Bitseek Hermes WebUI is not running')
+    console.log('BitSeek Claw WebUI is not running')
     return
   }
 
   if (!isRunning(pid)) {
     removePid()
-    console.log(`Bitseek Hermes WebUI was not running; cleaned stale PID ${pid}`)
+    console.log(`BitSeek Claw WebUI was not running; cleaned stale PID ${pid}`)
     return
   }
 
@@ -427,7 +476,7 @@ async function stop() {
     process.kill(pid, 'SIGKILL')
   }
   removePid()
-  console.log(`Bitseek Hermes WebUI stopped (PID ${pid})`)
+  console.log(`BitSeek Claw WebUI stopped (PID ${pid})`)
 }
 
 async function restart(options) {
@@ -510,11 +559,17 @@ async function doctor(options) {
   const agentDir = resolveAgentDir()
   add('Hermes Agent dir', Boolean(agentDir), agentDir || 'not found')
   add('run_agent.py', Boolean(agentDir && existsSync(join(agentDir, 'run_agent.py'))), agentDir ? join(agentDir, 'run_agent.py') : 'not found')
+  if (python && agentDir) {
+    const importCheck = aiAgentImportCheck(python, agentDir)
+    add('AIAgent importable', importCheck.ok, importCheck.ok ? python : importCheck.error || python)
+  } else {
+    add('AIAgent importable', false, 'python or Hermes Agent dir not found')
+  }
   add('port available', !(await portOccupied(options.host, options.port)), `${options.host}:${options.port}`)
-  add('no vendored .env', !existsSync(join(vendorRoot, '.env')), join(vendorRoot, '.env'))
-  add('no vendored .git', !existsSync(join(vendorRoot, '.git')), join(vendorRoot, '.git'))
-  add('no vendored .venv', !existsSync(join(vendorRoot, '.venv')), join(vendorRoot, '.venv'))
-  add('no vendored node_modules', !existsSync(join(vendorRoot, 'node_modules')), join(vendorRoot, 'node_modules'))
+  add('no bundled .env', !existsSync(join(vendorRoot, '.env')), join(vendorRoot, '.env'))
+  add('no bundled .git', !existsSync(join(vendorRoot, '.git')), join(vendorRoot, '.git'))
+  add('no bundled .venv', !existsSync(join(vendorRoot, '.venv')), join(vendorRoot, '.venv'))
+  add('no bundled node_modules', !existsSync(join(vendorRoot, 'node_modules')), join(vendorRoot, 'node_modules'))
 
   for (const check of checks) {
     console.log(`${check.ok ? 'ok' : 'fail'} - ${check.name}${check.detail ? `: ${check.detail}` : ''}`)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bitseek/hermes-webui",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
-  "description": "Npm wrapper for Bitseek Hermes WebUI runtime.",
+  "description": "BitSeek Claw WebUI launcher.",
   "bin": {
     "hermes-webui": "bin/hermes-webui.mjs"
   },