codexpanel 0.1.7 → 0.1.8

package/README.md

@@ -10,10 +10,10 @@ codexpanel is a mobile control plane for managing local Codex work from a phone.
 - `apps/relay`: HTTP/SSE/WSS relay service, PostgreSQL/SQLite storage, and device onboarding scripts
 - `apps/agent`: desktop-side agent entrypoint
 - `packages/protocol`: shared schemas and transport helpers
-- `packages/codex-app-server`: Codex app-server connector bindings
+- `packages/codex-app-server`: Codex app-server schema and method snapshots
 - `packages/ui`: shared React UI primitives
 
-Human reference files, local databases, deployment bundles, server handoff notes, and old demo artifacts live outside the production tree in `files_for_human/` and are ignored by Git.
+Human reference files, local databases, deployment bundles, server handoff notes, and retired prototype artifacts live outside the production tree in `files_for_human/` and are ignored by Git.
 
 ## Commands
 
@@ -44,7 +44,7 @@ npx -y codexpanel --server local
 npx -y codexpanel --server https://example.com
 ```
 
-`--server test` uses `https://jd.6a.gs`. `--server local` dynamically finds a free local relay port instead of assuming `4871`. A full URL connects to a self-hosted relay. Useful options include `--device-name`, `--workspace`, `--terminal-login`, `--token-login`, `--no-browser`, `--no-autostart`, `--no-tunnel`, `--dry-run`, and `--print-command`.
+`--server test` uses `https://jd.6a.gs`. `--server local` dynamically finds a free local relay port instead of assuming `4871`. A full URL connects to a self-hosted relay. Useful options include `--device-name`, `--workspace`, `--token-login`, `--no-browser`, `--no-autostart`, `--dry-run`, and `--print-command`. The retired `--legacy-tunnel` flag is rejected because direct tunnel access is not part of the final control path.
 
 For terminal token login, open the printed `/desktop/setup?flowId=...` link, sign in, click the one-time terminal token button, then run `npx -y codexpanel login --token-login` and paste the token. The token is scoped to the current setup flow and expires quickly.
 
@@ -58,21 +58,34 @@ Web/admin login uses a session cookie. Configure at least one of these before ex
 
 ```env
 CODEXPANEL_ADMIN_USERNAME=admin
-CODEXPANEL_ADMIN_PASSWORD=change_me
+CODEXPANEL_ADMIN_USER_ID=admin
+CODEXPANEL_ADMIN_PASSWORD=ChangeRoot9361A
 CODEXPANEL_SESSION_SECRET=long_random_secret
 CODEXPANEL_LOGIN_MAX_ATTEMPTS=8
+CODEXPANEL_LOGIN_IP_MAX_ATTEMPTS=24
 CODEXPANEL_LOGIN_WINDOW_MS=900000
 CODEXPANEL_LOGIN_LOCKOUT_MS=900000
-CODEXPANEL_REGISTRATION_ENABLED=true
+CODEXPANEL_LOGIN_MAX_BUCKETS=5000
+CODEXPANEL_EMAIL_CODE_IP_MAX_ATTEMPTS=10
+CODEXPANEL_EMAIL_CODE_IP_WINDOW_MS=900000
+CODEXPANEL_EMAIL_CODE_MAX_VERIFY_ATTEMPTS=8
+CODEXPANEL_EMAIL_CODE_MAX_CODES=5000
+CODEXPANEL_DESKTOP_SETUP_MAX_PENDING=1000
+CODEXPANEL_DESKTOP_SETUP_START_WINDOW_MS=900000
+CODEXPANEL_DESKTOP_SETUP_START_MAX_ATTEMPTS=20
+CODEXPANEL_DESKTOP_SETUP_START_MAX_IP_BUCKETS=5000
+CODEXPANEL_REGISTRATION_ENABLED=false
 ```
 
-Desktop setup uses browser login binding or terminal username/password/token login. Extra users can be provided with `CODEXPANEL_USERS_JSON` using `username`, `password`, `userId`, `role`, and `name`.
+Desktop setup uses browser login binding or a one-time terminal token. `CODEXPANEL_ADMIN_*` only bootstraps the first admin; additional users must be created through registration or admin operations.
 
-`CODEXPANEL_REGISTRATION_ENABLED=true` opens self-service web registration and is the current default. New users are stored in the existing relay users table with PBKDF2 password hashes and receive `CODEXPANEL_REGISTRATION_DEFAULT_ROLE` (`operator` or `viewer`, default `operator`). Set it to `false` if you need to close public onboarding again.
+`CODEXPANEL_REGISTRATION_ENABLED=true` opens self-service web registration. If the variable is omitted, development defaults to open and production defaults to closed; production onboarding must opt in explicitly. New users are stored in the existing relay users table with PBKDF2 password hashes and receive `CODEXPANEL_REGISTRATION_DEFAULT_ROLE` (`operator` or `viewer`, default `operator`).
+
+Desktop setup start requests are also rate-limited by source IP and capped by pending flow count. Tune `CODEXPANEL_DESKTOP_SETUP_*` only if installer traffic legitimately exceeds the defaults.
 
 ## First-batch user operations
 
-Use `/admin.html` with an admin session for first-batch testing:
+Use `/admin/` with an admin session for first-batch testing:
 
 - Enable/disable users, change roles, and reset passwords. These actions invalidate existing local-user sessions.
 - Recharge, gift, or deduct balance through the wallet adjustment action. Every change requires an idempotency key and is recorded in the user wallet ledger; do not edit `balance` directly.
@@ -87,7 +100,7 @@ Rollback for a test user is done by disabling the user, revoking the monthly car
 - `/console/`: mobile control console and PWA start URL.
 - `/desktop/setup`: browser sign-in and desktop device binding flow.
 - `/device.html`: migration page that points users to `npx -y codexpanel`.
-- `/admin.html` and `/project.html`: admin and product documentation pages.
+- `/admin/` and `/project.html`: admin and product documentation pages.
 
 ## Storage and deployment
 

package/README.zh.md

@@ -10,10 +10,10 @@ codexpanel 是一个面向 Codex 本地工作的移动控制平面。它把手
 - `apps/relay`：HTTP/SSE/WSS relay 服务、PostgreSQL/SQLite 存储、设备接入脚本。
 - `apps/agent`：电脑端 agent 入口。
 - `packages/protocol`：共享 schema 和传输 helper。
-- `packages/codex-app-server`：Codex app-server 连接绑定。
+- `packages/codex-app-server`：Codex app-server schema 与 method 快照。
 - `packages/ui`：共享 React UI 基础组件。
 
-人工参考文件、本地数据库、部署包、服务器交接说明和旧 demo 产物放在 `files_for_human/`，该目录不属于生产树并被 Git 忽略。
+人工参考文件、本地数据库、部署包、服务器交接说明和已退役原型产物放在 `files_for_human/`，该目录不属于生产树并被 Git 忽略。
 
 ## 常用命令
 
@@ -44,7 +44,7 @@ npx -y codexpanel --server local
 npx -y codexpanel --server https://example.com
 ```
 
-`--server test` 使用 `https://jd.6a.gs`。`--server local` 会动态寻找可用本地端口，不再假定 `4871`。完整 URL 会连接自部署 relay。常用参数包括 `--device-name`、`--workspace`、`--terminal-login`、`--token-login`、`--no-browser`、`--no-autostart`、`--no-tunnel`、`--dry-run` 和 `--print-command`。
+`--server test` 使用 `https://jd.6a.gs`。`--server local` 会动态寻找可用本地端口，不再假定 `4871`。完整 URL 会连接自部署 relay。常用参数包括 `--device-name`、`--workspace`、`--token-login`、`--no-browser`、`--no-autostart`、`--dry-run` 和 `--print-command`。已退役的 `--legacy-tunnel` 会被拒绝，因为 direct tunnel 不属于最终控制路径。
 
 终端 token 登录的使用方式是：打开安装器打印的 `/desktop/setup?flowId=...` 链接，在浏览器登录后点击一次性终端 token 按钮，再运行 `npx -y codexpanel login --token-login` 并粘贴 token。该 token 只绑定当前安装流，过期很快。
 
@@ -58,21 +58,34 @@ Web/admin 登录使用 session cookie。公网暴露 relay 前至少配置以下
 
 ```env
 CODEXPANEL_ADMIN_USERNAME=admin
-CODEXPANEL_ADMIN_PASSWORD=change_me
+CODEXPANEL_ADMIN_USER_ID=admin
+CODEXPANEL_ADMIN_PASSWORD=ChangeRoot9361A
 CODEXPANEL_SESSION_SECRET=long_random_secret
 CODEXPANEL_LOGIN_MAX_ATTEMPTS=8
+CODEXPANEL_LOGIN_IP_MAX_ATTEMPTS=24
 CODEXPANEL_LOGIN_WINDOW_MS=900000
 CODEXPANEL_LOGIN_LOCKOUT_MS=900000
-CODEXPANEL_REGISTRATION_ENABLED=true
+CODEXPANEL_LOGIN_MAX_BUCKETS=5000
+CODEXPANEL_EMAIL_CODE_IP_MAX_ATTEMPTS=10
+CODEXPANEL_EMAIL_CODE_IP_WINDOW_MS=900000
+CODEXPANEL_EMAIL_CODE_MAX_VERIFY_ATTEMPTS=8
+CODEXPANEL_EMAIL_CODE_MAX_CODES=5000
+CODEXPANEL_DESKTOP_SETUP_MAX_PENDING=1000
+CODEXPANEL_DESKTOP_SETUP_START_WINDOW_MS=900000
+CODEXPANEL_DESKTOP_SETUP_START_MAX_ATTEMPTS=20
+CODEXPANEL_DESKTOP_SETUP_START_MAX_IP_BUCKETS=5000
+CODEXPANEL_REGISTRATION_ENABLED=false
 ```
 
-电脑端 setup 支持浏览器登录绑定、终端用户名密码登录和终端一次性 token 登录。额外用户可以通过 `CODEXPANEL_USERS_JSON` 提供，字段包括 `username`、`password`、`userId`、`role` 和 `name`。
+电脑端 setup 支持浏览器登录绑定和终端一次性 token 登录。`CODEXPANEL_ADMIN_*` 只用于启动首个管理员；其他用户必须通过注册或后台运营创建。
 
-`CODEXPANEL_REGISTRATION_ENABLED=true` 会打开自助注册，目前默认开启。新用户写入 relay 的 users 表，密码使用 PBKDF2 hash，角色来自 `CODEXPANEL_REGISTRATION_DEFAULT_ROLE`，默认 `operator`。需要关闭公开接入时设为 `false`。
+`CODEXPANEL_REGISTRATION_ENABLED=true` 会打开自助注册。未配置该变量时，开发环境默认开放、生产环境默认关闭；生产环境如需开放注册必须显式设置为 `true`。新用户写入 relay 的 users 表，密码使用 PBKDF2 hash，角色来自 `CODEXPANEL_REGISTRATION_DEFAULT_ROLE`，默认 `operator`。
+
+电脑端 setup 启动请求会按来源 IP 限流，并受 pending flow 总量限制。只有安装流量确实超过默认值时，才需要调整 `CODEXPANEL_DESKTOP_SETUP_*`。
 
 ## 第一批用户运营
 
-使用 admin session 打开 `/admin.html` 进行第一批测试：
+使用 admin session 打开 `/admin/` 进行第一批测试：
 
 - 启用/禁用用户、调整角色、重置密码。这些操作会让对应本地用户旧 session 失效。
 - 通过钱包调整操作充值、赠送或扣减余额。每次变更都需要幂等键，并写入钱包流水；不要直接改 `balance`。
@@ -87,7 +100,7 @@ CODEXPANEL_REGISTRATION_ENABLED=true
 - `/console/`：手机控制台和 PWA start URL。
 - `/desktop/setup`：浏览器登录和电脑设备绑定流程。
 - `/device.html`：迁移页，引导用户改用 `npx -y codexpanel`。
-- `/admin.html` 和 `/project.html`：管理后台和产品文档页。
+- `/admin/` 和 `/project.html`：管理后台和产品文档页。
 
 ## 存储与部署
 

package/bin/codexpanel.cjs

@@ -11,7 +11,7 @@ const crypto = require("crypto");
 const readline = require("readline");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.1.6";
+const VERSION = "0.1.8";
 const PROD_URL = "https://codexpanel.com";
 const TEST_URL = "https://jd.6a.gs";
 const LOCAL_HOST = "127.0.0.1";
@@ -31,11 +31,9 @@ Options:
   --server <name|url>           production/prod, test/jd, local, or a relay URL. Defaults to production
   --workspace, --cwd <path>     Default workspace for Codex Desktop/app-server
   --device-name, --name <name>  Device display name shown in CodexPanel
-  --terminal-login              Ask for username and password in this terminal
   --token-login                 Ask for a one-time terminal token from the setup page
   --no-browser                  Do not open a browser; print the login URL instead
   --no-autostart                Do not enable Windows login autostart
-  --no-tunnel                   Disable Cloudflare WSS direct tunnel
   --dry-run                     Print resolved installer details without installing
   --print-command               Print the equivalent PowerShell bootstrap command after login approval
   -h, --help                    Show help
@@ -56,11 +54,9 @@ function parseArgs(argv) {
     server: process.env.CODEXPANEL_SERVER || "production",
     workspace: process.env.CODEXPANEL_WORKSPACE || "",
     deviceName: process.env.CODEXPANEL_DEVICE_NAME || "",
-    terminalLogin: false,
     tokenLogin: false,
     browser: true,
     autoStart: true,
-    tunnelEnabled: true,
     dryRun: false,
     printCommand: false,
   };
@@ -80,17 +76,17 @@ function parseArgs(argv) {
     else if (arg === "--server") options.server = readValue(arg);
     else if (arg === "--workspace" || arg === "--cwd") options.workspace = readValue(arg);
     else if (arg === "--device-name" || arg === "--name") options.deviceName = readValue(arg);
-    else if (arg === "--terminal-login") options.terminalLogin = true;
+    else if (arg === "--terminal-login") throw new Error("--terminal-login has been retired. Use browser sign-in or --token-login.");
     else if (arg === "--token-login") options.tokenLogin = true;
     else if (arg === "--no-browser") options.browser = false;
     else if (arg === "--no-autostart") options.autoStart = false;
-    else if (arg === "--no-tunnel") options.tunnelEnabled = false;
+    else if (arg === "--legacy-tunnel") throw new Error("--legacy-tunnel has been retired. Device traffic uses the server WSS gateway.");
+    else if (arg === "--no-tunnel") throw new Error("--no-tunnel has been retired. Device traffic uses the server WSS gateway.");
     else if (arg === "--dry-run") options.dryRun = true;
     else if (arg === "--print-command") options.printCommand = true; else {
       throw new Error(`Unknown option: ${arg}`);
     }
   }
-  if (options.terminalLogin && options.tokenLogin) throw new Error("Choose only one of --terminal-login or --token-login.");
   return options;
 }
 
@@ -164,7 +160,6 @@ function computerProfile(options, resolvedServer) {
     deviceName: options.deviceName || `${os.hostname()} / ${defaultUsername()} Codex Desktop Agent`,
     workspace: options.workspace || process.env.USERPROFILE || process.env.HOME || process.cwd(),
     autoStart: options.autoStart,
-    tunnelEnabled: options.tunnelEnabled,
     panelPortHint: DEFAULT_PANEL_PORT_START,
   };
 }
@@ -369,7 +364,12 @@ async function preloadResources(relayUrl) {
   let manifest = {};
   try { manifest = JSON.parse(manifestText); }
   catch { throw new Error("Server returned an invalid agent manifest."); }
-  const resources = [manifest.desktopAgent, manifest.connector, manifest.bootstrap].filter(Boolean);
+  const resources = [
+    manifest.hostRuntime,
+    manifest.hostRuntimeSchema,
+    ...(Array.isArray(manifest.hostRuntimeFiles) ? manifest.hostRuntimeFiles : []),
+    manifest.bootstrap,
+  ].filter(Boolean);
   for (const item of resources) {
     const resourceUrl = new URL(item.path, relayUrl).toString();
     console.log(`CodexPanel: 预下载资源 / Downloading ${item.fileName || item.path}`);
@@ -409,37 +409,18 @@ async function pollSetup(relayUrl, flowId, flowSecret) {
   throw new Error("Setup login timed out after 10 minutes.");
 }
 
-async function terminalLogin(relayUrl, flowId, flowSecret) {
-  const rl = createInterface();
-  try {
-    const username = (await question(rl, "CodexPanel username: ")).trim();
-    const password = await question(rl, "CodexPanel password: ", { silent: true });
-    try {
-      return await requestJson("POST", relayUrl, "/api/desktop/setup/login-token", { flowId, flowSecret, username, password }, {}, 30000);
-    } catch (error) {
-      if (error.data?.code !== "device_rebind_required") throw error;
-      console.log("这台电脑已绑定到其他账号，不会自动切换绑定。");
-      const answer = (await question(rl, "Type YES to rebind this computer to the current account / 输入 YES 切换绑定: ")).trim();
-      if (answer !== "YES") throw new Error("Setup kept the existing binding. Run npx -y codexpanel again if you want to switch later.");
-      return await requestJson("POST", relayUrl, "/api/desktop/setup/login-token", { flowId, flowSecret, username, password, confirmRebind: true }, {}, 30000);
-    }
-  } finally {
-    rl.close();
-  }
-}
-
 async function tokenLogin(relayUrl, flowId, flowSecret) {
   const rl = createInterface();
   try {
     const token = (await question(rl, "One-time CodexPanel terminal token from setup page: ")).trim();
     try {
-      return await requestJson("POST", relayUrl, "/api/desktop/setup/login-token", { flowId, flowSecret, token }, {}, 30000);
+      return await requestJson("POST", relayUrl, "/api/iam/desktop/setup/login-token", { flowId, flowSecret, token }, {}, 30000);
     } catch (error) {
       if (error.data?.code !== "device_rebind_required") throw error;
       console.log("这台电脑已绑定到其他账号，不会自动切换绑定。");
       const answer = (await question(rl, "Type YES to rebind this computer to the current account / 输入 YES 切换绑定: ")).trim();
       if (answer !== "YES") throw new Error("Setup kept the existing binding. Run npx -y codexpanel again if you want to switch later.");
-      return await requestJson("POST", relayUrl, "/api/desktop/setup/login-token", { flowId, flowSecret, token, confirmRebind: true }, {}, 30000);
+      return await requestJson("POST", relayUrl, "/api/iam/desktop/setup/login-token", { flowId, flowSecret, token, confirmRebind: true }, {}, 30000);
     }
   } finally {
     rl.close();
@@ -454,16 +435,15 @@ async function runBootstrap(relayUrl, approval, options) {
   url.searchParams.set("deviceId", approval.deviceId || stableDeviceId());
   if (approval.deviceName) url.searchParams.set("deviceName", approval.deviceName);
   if (options.workspace) url.searchParams.set("workspace", options.workspace);
-  url.searchParams.set("mode", "desktop-agent");
+  url.searchParams.set("mode", "host-runtime");
   url.searchParams.set("autoStart", options.autoStart ? "1" : "0");
-  url.searchParams.set("tunnelEnabled", options.tunnelEnabled ? "1" : "0");
 
   if (options.printCommand) console.log(powershellCommand(url));
   if (process.platform !== "win32") throw new Error("CodexPanel desktop agent installation currently supports Windows. Use the login URL on Windows to bind this computer.");
 
   console.log("\nCodexPanel: 正在下载最终安装脚本 / Downloading final bootstrap script...");
   const script = await downloadText(url.toString(), 30000);
-  if (!/CodexPanel/i.test(script) || !/desktop-agent/i.test(script)) throw new Error("Downloaded bootstrap script did not look like the CodexPanel Windows installer.");
+  if (!/CodexPanel/i.test(script) || !/host-runtime/i.test(script)) throw new Error("Downloaded bootstrap script did not look like the CodexPanel Windows installer.");
   const tmp = path.join(os.tmpdir(), `codexpanel-bootstrap-${Date.now()}-${Math.random().toString(16).slice(2)}.ps1`);
   fs.writeFileSync(tmp, Buffer.concat([Buffer.from([0xEF, 0xBB, 0xBF]), Buffer.from(script, "utf8")]));
   console.log("CodexPanel: 正在启动 Windows 安装器 / Starting Windows installer...");
@@ -487,11 +467,9 @@ async function install(options) {
       deviceId: profile.deviceId,
       deviceName: profile.deviceName,
       workspace: profile.workspace,
-      browserLogin: !options.terminalLogin && !options.tokenLogin,
-      terminalLogin: options.terminalLogin,
+      browserLogin: !options.tokenLogin,
       tokenLogin: options.tokenLogin,
       autoStart: options.autoStart,
-      tunnelEnabled: options.tunnelEnabled,
     }, null, 2));
     return;
   }
@@ -513,9 +491,7 @@ async function install(options) {
   if (start.oneTimeCode) console.log(`Binding code / 8 位绑定码: ${start.oneTimeCode}`);
 
   let approval;
-  if (options.terminalLogin) {
-    approval = await terminalLogin(resolved.relayUrl, start.flowId, start.flowSecret);
-  } else if (options.tokenLogin) {
+  if (options.tokenLogin) {
     approval = await tokenLogin(resolved.relayUrl, start.flowId, start.flowSecret);
   } else {
     if (options.browser) {

package/docs/desktop-npx-install-flow.md

@@ -12,7 +12,7 @@
 
 安装流程被分成两段。
 
-第一段是资源准备：CLI 会先读取安装清单，再下载并校验电脑端 agent、app-server 连接器和安装脚本探针。这样做的好处是，用户按下 Enter 的时候，系统已经知道安装所需资源是可用的，不会出现“浏览器已经打开了，但安装器还在等下载”的割裂感。
+第一段是资源准备：CLI 会先读取安装清单，再下载并校验电脑端 host-runtime agent、运行时模块和安装脚本探针。这样做的好处是，用户按下 Enter 的时候，系统已经知道安装所需资源是可用的，不会出现“浏览器已经打开了，但安装器还在等下载”的割裂感。
 
 第二段才是登录绑定：终端会提示 `资源已准备好。按 Enter 拉起浏览器登录并绑定这台电脑。`，用户确认后，浏览器才会打开登录页。这样更像一个正式安装流程，而不是悄悄弹出一个网页。
 
@@ -37,21 +37,7 @@
 
 页面完成绑定后会提示：`绑定成功，可以关闭浏览器，或回到安装界面查看进度。`
 
-## 终端登录方式
-
-除了浏览器登录，这个安装器也支持两种终端模式。
-
-### 用户名和密码
-
-运行：
-
-```powershell
-npx -y codexpanel login --terminal-login
-```
-
-然后按提示输入用户名和密码。它会像普通登录一样走 session，成功后继续完成设备绑定。
-
-### 一次性 token
+## 终端一次性 token
 
 如果你想在浏览器里登录，但让终端继续完成绑定，可以先打开安装器打印的 `/desktop/setup?flowId=...` 页面，登录后点击“生成终端一次性 token”。然后运行：
 
@@ -116,7 +102,7 @@ npx -y codexpanel --server https://example.com
 - relay 地址
 - 最近心跳
 - agent 运行状态
-- Codex app-server 状态
+- host-runtime / WSS 状态
 - 是否能打开或重启 agent
 
 这块面板的目的，是让不熟悉命令行的人也能看懂“现在装到哪一步了”。
@@ -149,7 +135,6 @@ CLI 同时生成本机 profile，包括：
 - `deviceName`
 - `workspace`
 - `autoStart`
-- `tunnelEnabled`
 - `panelPortHint`
 
 `deviceId` 来自本机 hostname、Windows domain、系统用户名和 user profile 路径的稳定 hash。它不是随机数，所以同一台电脑同一系统用户重复安装时会得到同一个 deviceId，方便识别换绑和 token 轮换。
@@ -165,21 +150,25 @@ GET /agent/version
 relay 返回 agent release manifest，里面包含：
 
 - `agentVersion`
-- `desktopAgent.path`
-- `desktopAgent.sha256`
-- `connector.path`
-- `connector.sha256`
+- `hostRuntime.path`
+- `hostRuntime.sha256`
+- `hostRuntimeFiles[]`
+- `hostRuntimeSchema.path`
+- `hostRuntimeSchema.sha256`
 - `bootstrap.path`
 - `bootstrap.sha256`
 
 CLI 随后下载 manifest 指向的资源：
 
 ```text
-GET /agent/desktop-agent.js
-GET /agent/app-server-connector.js
+GET /agent/host-runtime.cjs
+GET /agent/runtime/*.cjs
+GET /agent/generated/codex-app-server-schemas.ts
 GET /agent/bootstrap.ps1
 ```
 
+旧 `/agent/desktop-agent.js` 和 `/agent/app-server-connector.js` 下载入口已清退；安装器不再预检或下载旧 standalone bridge。
+
 每个资源下载后都会按 manifest 中的 `sha256` 校验。只有这些资源全部可下载、hash 正确，安装器才进入登录阶段。这样做的意义是：用户按 Enter 打开浏览器前，安装器已经确认服务端资源完整，后续失败更容易定位到登录、绑定或本机启动，而不是混在下载阶段。
 
 ### 3. 创建 setup flow
@@ -218,20 +207,20 @@ GET /desktop/setup?flowId=...&code=...
 页面会先调用：
 
 ```text
-GET /api/auth/status
+GET /api/iam/auth/status
 POST /api/desktop/setup/poll
 ```
 
 如果用户未登录，页面显示登录/注册表单。登录使用：
 
 ```text
-POST /api/auth/login
+POST /api/iam/auth/login
 ```
 
 注册使用：
 
 ```text
-POST /api/auth/register
+POST /api/iam/auth/register
 ```
 
 成功后 relay 设置 `codexpanel_session` cookie。浏览器后续审批靠 session cookie 鉴权。
@@ -284,29 +273,7 @@ relay 会校验：
 Binding succeeded. You can close this browser or return to the installer.
 ```
 
-### 5. 终端登录和一次性 token 登录
-
-如果用户选择终端用户名密码：
-
-```powershell
-npx -y codexpanel login --terminal-login
-```
-
-CLI 会在终端询问用户名和密码，然后调用：
-
-```text
-POST /api/desktop/setup/login-token
-```
-
-请求体包含：
-
-- `flowId`
-- `flowSecret`
-- `username`
-- `password`
-- 可选 `confirmRebind`
-
-relay 使用和 Web 登录相同的用户体系校验密码、登录失败限流、用户状态和角色，然后复用 setup approve 逻辑完成审批。
+### 5. 终端一次性 token 登录
 
 如果用户选择一次性 token 登录：
 
@@ -316,7 +283,7 @@ relay 使用和 Web 登录相同的用户体系校验密码、登录失败限流
 4. 页面调用：
 
 ```text
-POST /api/desktop/setup/terminal-token
+POST /api/iam/desktop/setup/terminal-token
 ```
 
 relay 校验当前浏览器 session、flowId 和 code，然后给这个 setup flow 写入短时 token hash。页面只显示 token 明文一次。
@@ -330,7 +297,7 @@ npx -y codexpanel login --token-login
 并调用：
 
 ```text
-POST /api/desktop/setup/login-token
+POST /api/iam/desktop/setup/login-token
 ```
 
 请求体包含：
@@ -362,14 +329,12 @@ Windows bootstrap 用 `setupToken` 向 relay 换取当前 flow 的安装上下
 - `DeviceName`
 - `Workspace`
 - `AgentVersion`
-- `TunnelEnabled`
-- `TunnelLocalHost`
-- `TunnelLocalPort`
 
 bootstrap 在 Windows 本机做这些事：
 
 1. 创建 `%LOCALAPPDATA%\CodexPanelAgent`。
-2. 下载 `desktop-agent.js` 和 `app-server-connector.js` 到本机。
+2. 下载 `host-runtime.cjs`、`runtime/*.cjs` 和
+   `generated/codex-app-server-schemas.ts`。
 3. 查找 Node 和 Codex 可执行文件。
 4. 动态选择本地状态面板端口。
 5. 生成 `agent-runtime.json`。
@@ -380,7 +345,7 @@ bootstrap 在 Windows 本机做这些事：
 POST /api/desktop/setup/complete
 ```
 
-8. 写入本地配置、启动 agent，并打开本地状态面板。
+8. 写入本地配置、启动 `host-runtime.cjs`，并打开本地状态面板。
 9. 有限次数确认云端是否已经看到这台设备在线；如果网络或心跳暂时未就绪，安装不会无限等待，会提示查看控制台、本地面板或日志。
 
 `agent-runtime.json` 是本机 agent 的主要数据来源，包含：
@@ -390,11 +355,11 @@ POST /api/desktop/setup/complete
 - deviceId
 - deviceName
 - deviceToken 明文
+- deviceWssUrl，最终 Device Agent WSS 入口，HTTPS relay 会派生为 `wss://<host>/device-wss`
 - workspace
 - Codex 路径
-- app-server listen 地址
+- provider transport（固定为 `stdio://`）
 - 本地 panel host/port/token
-- tunnel 配置
 - helper 脚本路径
 - 日志路径
 
@@ -425,93 +390,47 @@ relay 收到请求后会：
 
 ## 技术工作原理：agent 启动后做什么
 
-agent 启动入口是 `desktop-agent.js`。它先读取 `agent-runtime.json`，然后初始化几个循环和服务。
-
-启动时立即执行：
-
-1. `announceOnline("boot")`
-2. `checkForAgentUpdate("boot")`
-3. `startLocalPanel()`
-4. 如果开启 SSE，执行 `connectSse()`
-5. `startTunnelLoop()`
-6. `startPollLoop()`
-
-### 上线注册
-
-agent 调用：
-
-```text
-POST /api/device/register
-```
-
-请求体来自 `onlinePayload()`，包含：
-
-- `agentId`
-- `userId`
-- `deviceId`
-- `deviceName`
-- host、系统用户、domain、platform
-- agentVersion
-- desktopStatus
-- workspace
-- codexPath
-- sandbox 和 approvalPolicy
-- mode
-- appServerListen
-- tunnel 状态
-- panelUrl 和 panelPort
-- npmPackageVersion
-- capabilities
-
-capabilities 会告诉 relay 这台设备能做什么，例如：
-
-- `codex-cli`
-- `app-server-proxy`
-- `codex-desktop`
-- `threads`
-- `turns`
-- `approvals`
-- `cloudflare-tunnel-client`
-- `wss-direct-rpc`
-
-注册成功后，agent 还会发一个 `agent.online` event 到：
-
-```text
-POST /api/events
-```
-
-### 控制事件轮询和心跳
-
-agent 的主循环是 `startPollLoop()`。它每 10 秒执行一次 `pollOnce()`。
+workspace/package agent 的默认入口已经切到 `host-runtime.cjs`，并会读取
+`CODEXPANEL_AGENT_CONFIG` 指向的 `agent-runtime.json`，把 `userId`、`deviceId`、
+`deviceToken`、`workspace`、`codexPath` 和 `deviceWssUrl` 映射成
+`CODEXPANEL_*` 运行环境。relay 当前提供 `/device-wss` upgrade transport，
+用于 device-token `device.hello`、heartbeat、Agent Protocol event、command result
+和 `server.command` 下发。旧 `desktop-agent.js` Windows standalone 下载入口已清退。
 
-每次 poll 调用：
+standalone `host-runtime.cjs` 启动时会先读取 `agent-runtime.json`，然后初始化最终链路组件。
 
-```text
-POST /api/agent/pull-control
-```
+启动时立即执行：
 
-请求体包含：
+1. 创建 `DeviceWssClient`，使用 `deviceToken` 对 `/device-wss` 发送 `device.hello`。
+2. 启动 `HostRuntimeAdapter`，通过 `stdio://` JSONL 初始化 Codex app-server。
+3. 通过 WSS 上报 Agent Protocol v1 event、heartbeat、command result 和 resource chunk。
+4. 启动 `runtime/local-panel.cjs` 提供本机 `/api/status` 和固定 helper action。
 
-- `sinceId`：上次处理到的事件 ID。
-- `payload`：当前 `onlinePayload()`。
+legacy tunnel 已退役，agent 包内不再包含 `startTunnelLoop()`、
+cloudflared 启动器或本地 WSS direct RPC 服务。
+legacy poll fallback 也已退役，agent 包内不再包含 `startPollLoop()`、
+`pollOnce()` 或 `/api/agent/pull-control` 控制轮询。
 
-relay 返回：
+### 上线握手
 
-- 当前设备状态。
-- `events`：发给 agent 的控制事件。
-- `nextEventId`：下一次轮询游标。
-- `agentRelease`：服务端最新 agent release 信息。
-- agent client 数等运行信息。
+安装完成时，`POST /api/desktop/setup/complete` 会把设备记录写成
+`mode=host-runtime`，并保存服务端侧 device token hash。本机 agent 启动后不再信任
+client-supplied user/device 权限字段，而是通过 `/device-wss` 的 `device.hello`
+使用服务端签发的 device token 建立长连接。
 
-agent 收到后会：
+握手后，设备能力来自 host runtime 的 provider metadata 和 capability map。设备事件会保留
+Agent Protocol envelope 与 raw provider payload，不再通过旧 `/api/events` 或
+`/api/device/register` 作为主注册路径。
+旧 `/api/device/register`、`/api/device/update`、`/api/device/ping` 和
+`/api/device/offline` HTTP lifecycle route 已退役；在线、心跳和离线状态均由
+`/device-wss` 的 hello、heartbeat、close/stale heartbeat 决定。
 
-1. 用 `agentRelease` 检查是否需要自更新。
-2. 对每个 event 调用 `handleBridgeEvent()`。
-3. 更新 `lastPolledEventId`。
-4. 持久化本地 agent state。
-5. 更新本地状态面板里的 `lastHeartbeatAt`。
+### Legacy 控制事件轮询已删除
 
-如果请求失败，agent 会记录 `lastHeartbeatError`，10 秒后继续下一轮。失败不会让 agent 退出，这样断网、服务端重启、DNS 抖动后都能自动恢复。
+最终架构不把轮询作为正常交互路径。`enableLegacyPoll`、
+`CODEXPANEL_AGENT_ENABLE_LEGACY_POLL`、`startPollLoop()`、`pollOnce()` 和
+`POST /api/agent/pull-control` 都已退役；设备命令由服务端 command
+channel 下发，事件由 SSE 或设备 WSS 通道同步。
 
 ### 事件如何被处理
 
@@ -523,7 +442,7 @@ agent 收到后会：
 
 当前主要事件类型：
 
-- `agent.app.request`：代理到 Codex app-server，例如 status、start、connect、listThreads、readThread、startThread、resumeThread、startTurn、interrupt、resolveServerRequest。
+- `server.command`：由最终 `/commands` 网关下发到 host-runtime，例如 listSessions、readSession、startThread、resumeThread、startTurn、steerTurn、interruptTurn、resolveApproval。
 - `task.start`：启动 Codex CLI task，并先发 approval request。
 - `approval.resolve`：用户批准或拒绝后继续或取消任务。
 - `run.cancel`：取消当前运行中的 Codex CLI。
@@ -536,57 +455,22 @@ CLI task 启动后，agent 会把 stdout/stderr 和 Codex JSON event 转成 rela
 - `run.completed`
 - `agent.error`
 
-### SSE 辅助通道
-
-如果启用 SSE，agent 还会连接：
-
-```text
-GET /events?role=agent&client=<deviceId>
-```
-
-SSE 连接成功后，relay 可以直接推事件给 agent。SSE 失败或断开时：
-
-- 非 200 状态：2 秒后重连。
-- 连接 end：1.5 秒后重连。
-- 网络 error：1.5 秒后重连。
-
-即使 SSE 不可用，10 秒一次的 `/api/agent/pull-control` 轮询仍然是兜底控制通道。
+### Agent SSE 辅助通道已删除
 
-### WSS/直连 tunnel 循环
+`GET /events?role=agent&client=<deviceId>` 已退役。最终架构中，`GET /events`
+只服务 Web / Mobile / Admin 客户端的 SSE 读取；设备侧命令、心跳、事件上报和
+`command.result` 都通过 `/device-wss` 完成。
 
-如果 `tunnelEnabled` 为 true，agent 会运行 `startTunnelLoop()`。
+### Legacy WSS/直连 tunnel 已删除
 
-循环逻辑：
+最终架构不使用 direct tunnel/domain lease 作为主链路。`--legacy-tunnel`
+和 `--no-tunnel` 都已退役，CLI 会拒绝这些参数；relay bootstrap 不再写入
+tunnel/cloudflared 配置，agent 包内也不再包含本地 direct RPC tunnel 实现。
 
-1. 确保本机 tunnel local server 已启动。
-2. 如果没有有效 lease 或 cloudflared 不在运行，调用：
+历史上的 `/api/domain-lease/*`、cloudflared token、entry URL 和 WSS URL
+只作为 WS-F 清退对象保留，不再作为新安装或正式产品控制路径。
 
-```text
-POST /api/domain-lease/claim
-```
-
-3. 如果已有 lease，调用：
-
-```text
-POST /api/domain-lease/heartbeat
-```
-
-4. relay 返回更新后的 lease，agent 更新本地 tunnel 状态。
-
-lease 中包含 entry URL、data host、WSS URL、cloudflared token 等直连所需信息。agent 会启动 cloudflared，把外部 WSS 连接导到本机 tunnel local service。
-
-如果 heartbeat 失败，并且错误类似：
-
-- reclaim required
-- unknown domain lease
-- domain lease is released
-- hostname is outdated
-
-agent 会停止 cloudflared、清空 lease，并在 1 秒后重新 claim。其他失败则按 `TUNNEL_HEARTBEAT_MS` 继续重试。
-
-### 自更新循环
-
-agent 在启动和每次 control poll 时检查服务端 release。
+### Release 资源更新
 
 数据来源：
 
@@ -594,16 +478,16 @@ agent 在启动和每次 control poll 时检查服务端 release。
 GET /agent/version
 ```
 
-或 `/api/agent/pull-control` 返回的 `agentRelease`。
-
-如果 `agentVersion` 与本地不同，agent 会下载：
+安装器会预检并下载：
 
 ```text
-GET /agent/desktop-agent.js
-GET /agent/app-server-connector.js
+GET /agent/host-runtime.cjs
+GET /agent/runtime/*.cjs
+GET /agent/generated/codex-app-server-schemas.ts
 ```
 
-下载后校验 sha256，替换本地文件，发送 `agent.update.started`，停止 cloudflared，启动新 agent 进程，再退出旧进程。如果更新失败，发送 `agent.update.failed`，保留旧 agent 继续运行。
+下载后校验 sha256，再写入本机安装目录。旧 `desktop-agent.js` 和
+`app-server-connector.js` 不再作为安装、启动或自更新入口。
 
 ### 本地状态面板
 
@@ -636,8 +520,7 @@ POST /api/action
 - workspace
 - 当前工作模式、审批权限、sandbox、approvalPolicy、approvalsReviewer
 - 最近心跳和最近错误
-- Codex app-server 状态
-- WSS/tunnel 状态
+- host-runtime / Codex stdio bridge 状态
 - helper 脚本路径
 - 下一步建议
 
@@ -658,9 +541,9 @@ POST /api/action
 交互过程是：
 
 1. 用户在控制台选择“默认模式 / 计划模式 / 目标模式”或“请求批准 / 替我审批 / 完全访问”。
-2. 控制台调用 desktop-agent 直连 RPC `setControlState`；如果是 relay 直连 app-server 设备，则调用 `POST /api/app/control-state`。
+2. 控制台通过服务端控制门面下发状态更新，最终由 agent 处理标准化后的控制事件。
 3. 电脑端 agent 把标准化后的 `controlState` 写入本机 `agent-runtime.json` 和 agent state，字段包括 `sandbox`、`approvalPolicy`、`approvalsReviewer`、`networkAccess`、`workMode`、`permissionPreset`。
-4. agent 通过心跳、status RPC、本地状态面板 `/api/status` 把真实状态回传给 relay 和控制台。
+4. agent 通过服务端事件/心跳和本地状态面板 `/api/status` 把真实状态回传给 relay 和控制台。
 5. 后续 `thread/start`、`thread/resume`、`turn/start` 会从设备已保存的 `controlState` 补默认值，保证真正发给 Codex app-server 的权限和模式与控制台看到的一致。
 
 审批权限的映射是：
@@ -688,14 +571,14 @@ POST /api/action
 | deviceId | 本机 hostname/domain/user/profile hash | 识别同一台电脑和换绑 |
 | deviceName | CLI 参数或 hostname + 系统用户名 | 展示给用户确认 |
 | flowId/flowSecret/code | `/api/desktop/setup/start` | 连接 CLI、浏览器和 relay 的短时安装流 |
-| session cookie | `/api/auth/login` 或 `/api/auth/register` | 浏览器用户身份 |
+| session cookie | `/api/iam/auth/login` 或 `/api/iam/auth/register` | 浏览器用户身份 |
 | setupToken | `/api/desktop/setup/approve` 成功后生成 | Windows bootstrap 下载安装上下文 |
 | deviceToken | setup flow 审批后生成 | agent 长期鉴权，明文只在本机保存 |
 | deviceTokenHash | relay 计算并保存 | 服务端验证 deviceToken |
 | panelToken | bootstrap 本机生成 | 本地状态面板鉴权 |
-| controlState | 控制台 `/api/app/control-state` 或 desktop-agent `setControlState` RPC | 决定后续 Codex 工作模式、审批路由、sandbox 和网络权限 |
-| agentRelease | `/agent/version` 或 pull-control 返回 | agent 自更新 |
-| heartbeat 状态 | agent poll 和 tunnel heartbeat | 面板展示、服务端在线状态 |
+| controlState | 服务端控制门面下发的标准控制事件 | 决定后续 Codex 工作模式、审批路由、sandbox 和网络权限 |
+| agentRelease | `/agent/version` | agent 自更新 |
+| heartbeat 状态 | 设备 WSS/SSE 路径 | 面板展示、服务端在线状态 |
 
 ## 重试和失败提示
 
@@ -708,7 +591,6 @@ POST /api/action
 - PowerShell bootstrap 失败：终端显示安装目录、日志路径和失败原因。
 - agent 心跳失败：agent 记录 `lastHeartbeatError`，面板展示错误和建议，下一轮继续重试。
 - SSE 断开：1.5 到 2 秒后重连。
-- tunnel lease 失效：停止 cloudflared 并重新 claim。
 - 自更新失败：记录事件并继续运行旧版本。
 
 ## 版本和更新怎么看

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexpanel",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "CodexPanel mobile control plane monorepo.",
   "license": "UNLICENSED",
   "private": false,
@@ -28,16 +28,21 @@
     "verify:version": "node scripts/sync-product-version.mjs --check",
     "prebuild": "npm run sync:version",
     "build": "npm run build --workspaces --if-present",
-    "check": "npm run verify:version && npm run scan:encoding && npm run verify:api-contracts && npm run verify:storage && npm run check --workspaces --if-present",
+    "check": "npm run verify:version && npm run scan:encoding && npm run verify:api-contracts && npm run verify:client-gateway && npm run verify:server-gateway-boundary && npm run verify:iam && npm run verify:storage && npm run verify:domain-config && node scripts/money-smoke.cjs && npm run check --workspaces --if-present",
     "release:local": "node scripts/release-local.mjs",
     "release:server": "bash scripts/server-autodeploy.sh",
+    "release:test": "node scripts/test-release.mjs",
     "release:production": "node scripts/production-release.mjs",
     "verify:release": "node scripts/verify-release.mjs",
     "test:e2e": "playwright test",
     "scan:encoding": "node scripts/scan-encoding.cjs",
     "verify:api-contracts": "node scripts/verify-api-contracts.mjs",
+    "verify:client-gateway": "node scripts/verify-client-gateway-contract.mjs",
+    "verify:server-gateway-boundary": "node scripts/verify-server-gateway-boundary.mjs",
+    "verify:iam": "node scripts/verify-iam-contract.mjs && npm run check -w @codexpanel/iam-service",
     "generate:codex": "npm run generate -w @codexpanel/codex-app-server",
     "verify:storage": "node scripts/verify-storage-boundary.mjs",
+    "verify:domain-config": "node scripts/verify-domain-config.mjs",
     "smoke:storage": "node scripts/storage-smoke.cjs",
     "purge:retired-desktop-residue": "node scripts/purge-retired-desktop-residue.mjs"
   },