@mearl/cloud-server 3.0.0-beta.0 → 3.0.0-beta.10

package/README.md

@@ -1,74 +1,71 @@
 # @mearl/cloud-server
 
-云端 WebSocket Server，用于中转云端 Agent 请求到本地连接器。
+[English](README.md) | [简体中文](README.zh-CN.md)
 
-## 安装
+A cloud WebSocket server routing cloud Agent requests to local connectors.
 
-推荐通过 setup 安装完整的云端 Agent 环境（cloud-server、统一 client 与 Agent Skill）：
+## Installation
+
+Use setup to install a complete cloud Agent environment: cloud-server, the unified client, and Agent Skill.
 
 ```bash
 npx @mearl/setup --cloud
 ```
 
-Qoder Cloud Agent 使用同一套包和 server 命令，只在 setup 时选择配对模式：
-
-```bash
-npx @mearl/setup --qoder-cloud --yes
-```
+Installed capability packages provide optional connection protocols. See [`@mearl/plugin-qoder`](../../plugin-qoder/README.md) for Qoder pairing; the core does not include its pairing implementation.
 
-在 Docker 或自定义进程托管等只需要 Server 包的场景，可单独安装 `@mearl/cloud-server`。
+Install `@mearl/cloud-server` separately when only the server package is needed, such as Docker or custom process management.
 
-## 使用
+## Usage
 
-### 命令行方式
+### Command line
 
-Server **默认以后台守护进程方式运行**，启动后立即返回，并打印本地机器需要执行的连接命令。
-POSIX 环境下后台进程会进入独立 session，可在启动命令结束后继续运行。
-Qoder 模式保持相同的 `start/status/restart/stop/logs` 交互；`start` 和 `restart` 生成新的
-pair/connector 信息后退出，不监听端口或创建守护进程。
+The server **runs as a background daemon by default**, returns immediately after startup, and prints the connection command to run on the local machine.
+On POSIX systems, the background process enters its own session and continues after the launching command exits.
+Other cloud modes load through installed `cloud.server.<id>` capabilities and fail explicitly if absent.
 
 ```bash
 mearl-cloud-server [command] [options]
 ```
 
-**子命令：**
+**Subcommands:**
 
-- `start` - 后台启动 server（默认，不写也等价于 `start`）
-- `stop` - 停止后台 server
-- `restart` - 重启后台 server
-- `status` - 查看运行状态及连接信息
-- `logs` - 打印 server 日志末尾
+- `start` — Start in the background (default when no subcommand is given).
+- `stop` — Stop the background server.
+- `restart` — Restart the background server.
+- `status` — Show status and connection information.
+- `logs` — Print the end of the server log.
 
-**选项：**
+**Options:**
 
-- `--foreground` / `-f` - 前台运行（不守护化，适合 systemd / Docker / PM2）
-- `--port <port>` - 服务器端口（默认 8080）
-- `--path <path>` - WebSocket 路径（默认 /ws）
-- `--token <token>` - 鉴权密钥（未指定时自动生成）
-- `--heartbeat <seconds>` - 心跳超时时间（默认 90 秒）
-- `--max-connections <n>` - 最大连接数（默认 100）
+- `--foreground` / `-f` — Run without daemonizing, suitable for systemd / Docker / PM2.
+- `--port <port>` — Server port (default 8080).
+- `--path <path>` — WebSocket path (default /ws).
+- `--token <token>` — Authentication token (generated if omitted).
+- `--heartbeat <seconds>` — Heartbeat timeout (default 90 seconds).
+- `--max-connections <n>` — Maximum connections (default 100).
 
-**示例：**
+**Examples:**
 
 ```bash
-# 后台启动（自动生成 token），打印连接命令后立即返回
+# Start in background, generate a token, print the connection command, and return
 mearl-cloud-server
 
-# 查看状态与连接信息
+# Status and connection information
 mearl-cloud-server status
 
-# 停止 / 重启
+# Stop / restart
 mearl-cloud-server stop
 mearl-cloud-server restart
 
-# 自定义端口和鉴权
+# Custom port and authentication
 mearl-cloud-server start --port 9000 --token your-secret-token
 
-# 前台运行（交给外部进程管理器托管）
+# Foreground execution for an external process manager
 mearl-cloud-server --foreground
 ```
 
-后台启动后会打印供本地机器使用的连接命令，例如：
+Background startup prints a connection command for the local machine, for example:
 
 ```
 [CloudServer] Started in background (pid 12345)
@@ -78,30 +75,30 @@ mearl-cloud-server --foreground
     npx @mearl/cloud-connector start "ws://10.0.1.100:8080/ws?token=xxx"
 ```
 
-部署在反向代理或沙箱中时，由部署宿主或 preset 安装器通过 `MEARL_CLOUD_PUBLIC_URL` 提供外部入口，可使用 `{port}` 占位符。核心不探测组织专属沙箱变量或内部端口映射接口；相关自动发现由独立能力包处理。当前阶段尚未接通这些内部适配，内部产品仍保留原实现。
+Behind a reverse proxy or in a sandbox, set `MEARL_CLOUD_PUBLIC_URL` to the external endpoint, optionally using `{port}`. The deployment host or Preset installer provides the connection address.
 
-普通入口的连接命令保持双引号参数形式。外部路径含 `$` 等 shell 元字符时，输出命令使用 POSIX 字面量引用；这类命令在 POSIX 兼容终端执行，其他终端应将完整 publicUrl 作为一个字面量参数传给 `start`。
+Normal connection commands use double-quoted arguments. When an external path contains shell metacharacters such as `$`, output uses POSIX literal quoting. Run these commands in a POSIX-compatible terminal; other terminals must pass the full publicUrl as one literal argument to `start`.
 
-运行时文件位于 `~/.mearl/`：
+Runtime files live in `~/.mearl/`:
 
-- `cloud-server.json` - 连接配置（含 server URL、pid、端口等），统一 `@mearl/client` 自动读取
-- `cloud-server-mode.json` - setup 在 Qoder 模式下写入的标识；普通 `--cloud` 会删除它
-- `cloud-server.log` - 后台进程日志（`logs` 子命令读取，或 `tail -f` 跟踪）；超过 5MB 会在下次启动时滚动为 `cloud-server.log.1`
+- `cloud-server.json` — Connection configuration, including URL, PID, and port; read automatically by `@mearl/client`.
+- `cloud-server-mode.json` — Optional cloud mode marker written by setup; ordinary `--cloud` removes it.
+- `cloud-server.log` — Background log, read with `logs` or `tail -f`; rotates to `cloud-server.log.1` on the next startup if over 5MB.
 
-> 守护进程的启停、状态、日志滚动等生命周期逻辑由共享包 [`@mearl/daemon-core`](../../daemon-core) 提供（与 cloud-connector 复用同一套实现）。
+> The shared [`@mearl/daemon-core`](../../daemon-core/README.md) supplies lifecycle operations, status, and log rotation, also used by cloud-connector.
 
-**关于 token：**
+**Tokens:**
 
-- 未指定 `--token` 时会自动生成。`restart` 会**沿用当前 token**，因此之前打印的连接命令重启后仍然有效。
-- `stop` 后再 `start` 属于全新启动，会重新生成 token；若希望连接命令长期固定，请显式传入 `--token` 或设置 `MEARL_TOKEN`。
+- A token is generated when `--token` is omitted. `restart` **preserves the current token**, keeping previously printed connection commands valid.
+- `stop` followed by `start` is a fresh startup and generates a new token. For a stable connection command, supply `--token` or set `MEARL_TOKEN`.
 
-**环境变量：**
+**Environment variables:**
 
-- `MEARL_TOKEN` - 鉴权密钥（覆盖 --token 选项）
-- `CLOUD_SERVER_HOST` - 公网主机名（默认自动获取）
-- `MEARL_CLOUD_PUBLIC_URL` - 明确配置的外部入口，支持 `{port}` 占位符；有显式路径和查询参数时保留，根路径使用 `path` 选项，鉴权 token 由 Server 设置。HTTP/WS 入口生成 `ws://`，HTTPS/WSS 入口生成 `wss://`。
+- `MEARL_TOKEN` — Authentication token, overriding --token.
+- `CLOUD_SERVER_HOST` — Public hostname (automatically detected by default).
+- `MEARL_CLOUD_PUBLIC_URL` — Explicit external endpoint supporting `{port}`. Explicit paths and query parameters are preserved; a root path uses the `path` option. The server sets the authentication token. HTTP/WS endpoints produce `ws://`; HTTPS/WSS endpoints produce `wss://`.
 
-### 编程方式
+### Programmatic usage
 
 ```typescript
 import { CloudServer } from '@mearl/cloud-server';
@@ -117,52 +114,50 @@ const server = new CloudServer({
 
 await server.start();
 
-// 获取统计信息
+// Get statistics
 const stats = server.getStats();
 console.log(stats);
 // { connections: 2, agents: 1, connectors: 1, pendingRequests: 0 }
 
-// 优雅关闭
+// Graceful shutdown
 await server.stop();
 ```
 
-Qoder 模式只复用 cloud-server CLI 作为建联入口。配对完成后的 action 继续通过 Qoder
-Client-Side `mearl` 工具、Session API 和本地 connector 转发，不会连接一个本地
-cloud-server 端口。
+The corresponding capability package handles handshakes and forwarding for optional modes.
 
-## 架构
+## Architecture
 
 ```
-云端 Agent
+Cloud Agent
   ↓
 @mearl/client
   ↓ (WebSocket)
-@mearl/cloud-server (本进程)
+@mearl/cloud-server (this process)
   ↓ (WebSocket)
-@mearl/cloud-connector (本地)
+@mearl/cloud-connector (local)
   ↓ (Unix Socket)
 @mearl/native-host
   ↓
 Chrome Extension / CDP
 ```
 
-## 连接类型
+## Connection types
 
-Server 接受两种类型的连接：
+The server accepts two connection types:
 
-1. **Agent 连接** - 发起请求的云端客户端
-2. **Connector 连接** - 转发请求到 native-host 的本地连接器
+1. **Agent connection** — A cloud client issuing requests.
+2. **Connector connection** — A local connector forwarding requests to native-host.
 
-两类客户端建连后会分别发送 `agent_hello` 和 `connector_hello`。Connector 会注册
-稳定 ID、名称和版本；同一 ID 重连时，新连接会替换旧连接。
+After connecting, clients send `agent_hello` and `connector_hello`, respectively. Connectors register
+a stable ID, name, and version; a reconnection with the same ID replaces the previous connection.
 
-只有一个 Connector 在线时，Server 自动选择它。多个 Connector 同时在线时，Agent
-先调用 `connector_list` 获取清单，再在请求中传 `connector`；未指定目标时
-Server 会拒绝请求，避免把浏览器操作发到错误机器。
+With one online Connector, the server selects it automatically. With multiple Connectors, the Agent
+first calls `connector_list`, then passes `connector` with requests. Without an explicit target,
+the server rejects the request to avoid sending browser operations to the wrong machine.
 
-## 消息协议
+## Message protocol
 
-### 请求格式（Agent → Server）
+### Request format (Agent → Server)
 
 ```json
 {
@@ -174,10 +169,10 @@ Server 会拒绝请求，避免把浏览器操作发到错误机器。
 }
 ```
 
-`connector` 接受 connector ID 或可唯一匹配的名称。`connector_list` 是
-Server 内置命令，不会转发到浏览器侧。
+`connector` accepts an ID or a uniquely matching name. `connector_list` is
+a built-in server command and is not forwarded to the browser.
 
-### 响应格式（Server → Agent）
+### Response format (Server → Agent)
 
 ```json
 {
@@ -188,30 +183,30 @@ Server 内置命令，不会转发到浏览器侧。
 }
 ```
 
-### 心跳格式
+### Heartbeat format
 
 ```json
 { "type": "ping", "timestamp": 1234567890 }
 { "type": "pong", "timestamp": 1234567890 }
 ```
 
-## 鉴权
+## Authentication
 
-设置 `token` 后，所有连接必须携带正确的 token：
+When `token` is set, every connection must supply the correct token:
 
 ```bash
-# Agent 连接
+# Agent connection
 ws://server.com/ws?token=your-secret-token
 
-# Connector 连接
+# Connector connection
 ws://server.com/ws?token=your-secret-token
 ```
 
-## 部署建议
+## Deployment recommendations
 
-> 交给外部进程管理器（systemd / Docker / PM2）托管时，请加 `--foreground`，让 server 在前台运行，由管理器负责守护与重启。
+> For systemd / Docker / PM2, add `--foreground` and let the external manager supervise and restart the server.
 
-### 使用 systemd（Linux）
+### systemd (Linux)
 
 ```ini
 [Unit]
@@ -229,7 +224,7 @@ RestartSec=5
 WantedBy=multi-user.target
 ```
 
-### 使用 Docker
+### Docker
 
 ```dockerfile
 FROM node:20-alpine
@@ -238,17 +233,17 @@ EXPOSE 8080
 CMD ["mearl-cloud-server", "--foreground", "--token", "your-token"]
 ```
 
-### 使用 PM2
+### PM2
 
 ```bash
-pm2 start mearl-cloud-server --name mtop-cloud-server -- --foreground --port 8080 --token your-token
+pm2 start mearl-cloud-server --name mearl-cloud-server -- --foreground --port 8080 --token your-token
 ```
 
-## 注意事项
+## Notes
 
-- 建议在生产环境使用 WSS（WebSocket Secure）加密传输
-- 使用反向代理（如 Nginx）处理 WSS 升级
-- 设置合理的 `maxConnections` 限制资源占用
-- 启用 `token` 鉴权保护服务安全
-- 在沙箱环境中启动时，会自动检测并使用平台分配的公网地址
-- 如果沙箱端口映射 API 不可用，会回退到使用本地 IP 地址
+- Use WSS (WebSocket Secure) in production for encrypted transport.
+- Use a reverse proxy such as Nginx for WSS upgrades.
+- Set an appropriate `maxConnections` limit to bound resource use.
+- Enable `token` authentication.
+- Sandbox startup automatically detects and uses the platform-assigned public address.
+- If the sandbox port-mapping API is unavailable, it falls back to the local IP address.

package/README.zh-CN.md

@@ -0,0 +1,249 @@
+# @mearl/cloud-server
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+云端 WebSocket Server，用于中转云端 Agent 请求到本地连接器。
+
+## 安装
+
+推荐通过 setup 安装完整的云端 Agent 环境（cloud-server、统一 client 与 Agent Skill）：
+
+```bash
+npx @mearl/setup --cloud
+```
+
+可选连接协议由已安装能力包提供。Qoder 配对见 [`@mearl/plugin-qoder`](../../plugin-qoder/README.zh-CN.md)；核心不内置其配对实现。
+
+在 Docker 或自定义进程托管等只需要 Server 包的场景，可单独安装 `@mearl/cloud-server`。
+
+## 使用
+
+### 命令行方式
+
+Server **默认以后台守护进程方式运行**，启动后立即返回，并打印本地机器需要执行的连接命令。
+POSIX 环境下后台进程会进入独立 session，可在启动命令结束后继续运行。
+其他 cloud mode 通过已安装的 `cloud.server.<id>` 加载，未安装时明确失败。
+
+```bash
+mearl-cloud-server [command] [options]
+```
+
+**子命令：**
+
+- `start` - 后台启动 server（默认，不写也等价于 `start`）
+- `stop` - 停止后台 server
+- `restart` - 重启后台 server
+- `status` - 查看运行状态及连接信息
+- `logs` - 打印 server 日志末尾
+
+**选项：**
+
+- `--foreground` / `-f` - 前台运行（不守护化，适合 systemd / Docker / PM2）
+- `--port <port>` - 服务器端口（默认 8080）
+- `--path <path>` - WebSocket 路径（默认 /ws）
+- `--token <token>` - 鉴权密钥（未指定时自动生成）
+- `--heartbeat <seconds>` - 心跳超时时间（默认 90 秒）
+- `--max-connections <n>` - 最大连接数（默认 100）
+
+**示例：**
+
+```bash
+# 后台启动（自动生成 token），打印连接命令后立即返回
+mearl-cloud-server
+
+# 查看状态与连接信息
+mearl-cloud-server status
+
+# 停止 / 重启
+mearl-cloud-server stop
+mearl-cloud-server restart
+
+# 自定义端口和鉴权
+mearl-cloud-server start --port 9000 --token your-secret-token
+
+# 前台运行（交给外部进程管理器托管）
+mearl-cloud-server --foreground
+```
+
+后台启动后会打印供本地机器使用的连接命令，例如：
+
+```
+[CloudServer] Started in background (pid 12345)
+[CloudServer] Logs: ~/.mearl/cloud-server.log
+
+  Connect from your local machine:
+    npx @mearl/cloud-connector start "ws://10.0.1.100:8080/ws?token=xxx"
+```
+
+部署在反向代理或沙箱中时，使用 `MEARL_CLOUD_PUBLIC_URL` 指定外部入口，可使用 `{port}` 占位符。连接地址由部署宿主或 Preset 安装器提供。
+
+普通入口的连接命令保持双引号参数形式。外部路径含 `$` 等 shell 元字符时，输出命令使用 POSIX 字面量引用；这类命令在 POSIX 兼容终端执行，其他终端应将完整 publicUrl 作为一个字面量参数传给 `start`。
+
+运行时文件位于 `~/.mearl/`：
+
+- `cloud-server.json` - 连接配置（含 server URL、pid、端口等），统一 `@mearl/client` 自动读取
+- `cloud-server-mode.json` - setup 为可选 cloud mode 写入的标识；普通 `--cloud` 会删除它
+- `cloud-server.log` - 后台进程日志（`logs` 子命令读取，或 `tail -f` 跟踪）；超过 5MB 会在下次启动时滚动为 `cloud-server.log.1`
+
+> 守护进程的启停、状态、日志滚动等生命周期逻辑由共享包 [`@mearl/daemon-core`](../../daemon-core/README.zh-CN.md) 提供（与 cloud-connector 复用同一套实现）。
+
+**关于 token：**
+
+- 未指定 `--token` 时会自动生成。`restart` 会**沿用当前 token**，因此之前打印的连接命令重启后仍然有效。
+- `stop` 后再 `start` 属于全新启动，会重新生成 token；若希望连接命令长期固定，请显式传入 `--token` 或设置 `MEARL_TOKEN`。
+
+**环境变量：**
+
+- `MEARL_TOKEN` - 鉴权密钥（覆盖 --token 选项）
+- `CLOUD_SERVER_HOST` - 公网主机名（默认自动获取）
+- `MEARL_CLOUD_PUBLIC_URL` - 明确配置的外部入口，支持 `{port}` 占位符；有显式路径和查询参数时保留，根路径使用 `path` 选项，鉴权 token 由 Server 设置。HTTP/WS 入口生成 `ws://`，HTTPS/WSS 入口生成 `wss://`。
+
+### 编程方式
+
+```typescript
+import { CloudServer } from '@mearl/cloud-server';
+
+const server = new CloudServer({
+  port: 8080,
+  path: '/ws',
+  token: 'your-secret-token',
+  heartbeatTimeout: 90,
+  maxConnections: 100,
+  maxMessageSize: 10 * 1024 * 1024,
+});
+
+await server.start();
+
+// 获取统计信息
+const stats = server.getStats();
+console.log(stats);
+// { connections: 2, agents: 1, connectors: 1, pendingRequests: 0 }
+
+// 优雅关闭
+await server.stop();
+```
+
+可选 mode 的握手和转发由对应能力包负责。
+
+## 架构
+
+```
+云端 Agent
+  ↓
+@mearl/client
+  ↓ (WebSocket)
+@mearl/cloud-server (本进程)
+  ↓ (WebSocket)
+@mearl/cloud-connector (本地)
+  ↓ (Unix Socket)
+@mearl/native-host
+  ↓
+Chrome Extension / CDP
+```
+
+## 连接类型
+
+Server 接受两种类型的连接：
+
+1. **Agent 连接** - 发起请求的云端客户端
+2. **Connector 连接** - 转发请求到 native-host 的本地连接器
+
+两类客户端建连后会分别发送 `agent_hello` 和 `connector_hello`。Connector 会注册
+稳定 ID、名称和版本；同一 ID 重连时，新连接会替换旧连接。
+
+只有一个 Connector 在线时，Server 自动选择它。多个 Connector 同时在线时，Agent
+先调用 `connector_list` 获取清单，再在请求中传 `connector`；未指定目标时
+Server 会拒绝请求，避免把浏览器操作发到错误机器。
+
+## 消息协议
+
+### 请求格式（Agent → Server）
+
+```json
+{
+  "id": "unique-id",
+  "action": "get_requests",
+  "data": { "count": 5 },
+  "connector": "work-mac",
+  "version": "1.30.0"
+}
+```
+
+`connector` 接受 connector ID 或可唯一匹配的名称。`connector_list` 是
+Server 内置命令，不会转发到浏览器侧。
+
+### 响应格式（Server → Agent）
+
+```json
+{
+  "id": "unique-id",
+  "success": true,
+  "data": { ... },
+  "versionWarning": "..."
+}
+```
+
+### 心跳格式
+
+```json
+{ "type": "ping", "timestamp": 1234567890 }
+{ "type": "pong", "timestamp": 1234567890 }
+```
+
+## 鉴权
+
+设置 `token` 后，所有连接必须携带正确的 token：
+
+```bash
+# Agent 连接
+ws://server.com/ws?token=your-secret-token
+
+# Connector 连接
+ws://server.com/ws?token=your-secret-token
+```
+
+## 部署建议
+
+> 交给外部进程管理器（systemd / Docker / PM2）托管时，请加 `--foreground`，让 server 在前台运行，由管理器负责守护与重启。
+
+### 使用 systemd（Linux）
+
+```ini
+[Unit]
+Description=Mearl Cloud Server
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+ExecStart=/usr/bin/mearl-cloud-server --foreground --port 8080 --token your-token
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 使用 Docker
+
+```dockerfile
+FROM node:20-alpine
+RUN npm install -g @mearl/cloud-server
+EXPOSE 8080
+CMD ["mearl-cloud-server", "--foreground", "--token", "your-token"]
+```
+
+### 使用 PM2
+
+```bash
+pm2 start mearl-cloud-server --name mearl-cloud-server -- --foreground --port 8080 --token your-token
+```
+
+## 注意事项
+
+- 建议在生产环境使用 WSS（WebSocket Secure）加密传输
+- 使用反向代理（如 Nginx）处理 WSS 升级
+- 设置合理的 `maxConnections` 限制资源占用
+- 启用 `token` 鉴权保护服务安全
+- 在沙箱环境中启动时，会自动检测并使用平台分配的公网地址
+- 如果沙箱端口映射 API 不可用，会回退到使用本地 IP 地址

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 import type { CloudServerOptions } from './index.js';
-import { type CloudServerCommand } from './qoder.js';
+type CloudServerCommand = 'start' | 'stop' | 'restart' | 'status' | 'logs';
 export interface ParsedCloudServerArgs {
     command: CloudServerCommand;
     daemonArgs: string[];
@@ -10,3 +10,4 @@ export interface ParsedCloudServerArgs {
 }
 export declare function parseCloudServerArgs(argv: string[]): ParsedCloudServerArgs;
 export declare function main(argv?: string[]): Promise<number>;
+export {};

package/dist/cli.js

@@ -8,6 +8,7 @@ import {
 } from "./chunks/chunk-LXICEBLN.js";
 
 // src/cli.ts
+import { capabilityDirectory } from "@mearl/daemon-core/page-runtimes";
 import { Command, CommanderError, InvalidArgumentError } from "commander";
 
 // src/daemon.ts
@@ -82,7 +83,7 @@ import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 var CLOUD_SERVER_MODE_ENV = "MEARL_CLOUD_MODE";
 function isCloudServerMode(value) {
-  return value === "websocket" || value === "qoder";
+  return typeof value === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(value);
 }
 function readStoredMode(storage) {
   const modeFile = storage.modeFile ?? MODE_FILE;
@@ -112,72 +113,18 @@ function resolveCloudServerMode(env = process.env, storage = {}) {
   const requested = env[CLOUD_SERVER_MODE_ENV];
   if (requested !== void 0) {
     if (!isCloudServerMode(requested)) {
-      throw new Error(`${CLOUD_SERVER_MODE_ENV} must be "websocket" or "qoder"`);
+      throw new Error(`${CLOUD_SERVER_MODE_ENV} must be a valid installed cloud mode ID`);
     }
-    if (requested === "qoder") writeStoredMode(requested, storage);
+    if (requested !== "websocket") writeStoredMode(requested, storage);
     else clearStoredMode(storage);
     return requested;
   }
   return readStoredMode(storage) ?? "websocket";
 }
 
-// src/qoder.ts
-import { randomBytes } from "node:crypto";
-function createQoderPairingInfo(options = {}) {
-  const pairingCode = (options.createCode ?? (() => randomBytes(24).toString("base64url")))();
-  if (!/^[A-Za-z0-9_-]{16,128}$/.test(pairingCode)) {
-    throw new Error("Qoder pairing code must be 16-128 URL-safe characters");
-  }
-  const createdAt = (options.now ?? Date.now)();
-  if (!Number.isSafeInteger(createdAt) || createdAt < 1e12 || createdAt > 9999999999999) {
-    throw new Error("Qoder pairing timestamp must be a 13-digit epoch millisecond value");
-  }
-  return {
-    pairingCode,
-    createdAt,
-    connectorUrl: `qoder://pair/${pairingCode}?created=${createdAt}`,
-    toolInput: { action: "pair", payload: { code: pairingCode } }
-  };
-}
-function formatQoderPairingOutput(info) {
-  const connectorCommand = `npx @mearl/cloud-connector start "${info.connectorUrl}"`;
-  return `[CloudServer] Qoder pairing mode is ready.
-
-  Connect from your local machine:
-    ${connectorCommand}
-
-  Then immediately invoke the Qoder client-side custom tool named "mearl" with this input:
-    ${JSON.stringify(info.toolInput)}
-
-The connector resolves QODER_PERSONAL_ACCESS_TOKEN from the local environment, ~/.mearl/.env, or supported local credential storage. Never add the PAT to the pairing URL.`;
-}
-async function runQoderCloudServerCommand(command, dependencies) {
-  const writeLine = dependencies.writeLine ?? console.log;
-  switch (command) {
-    case "start":
-    case "restart":
-      if (dependencies.isServerRunning()) await dependencies.stopServer();
-      writeLine(
-        formatQoderPairingOutput(
-          (dependencies.createPairing ?? (() => createQoderPairingInfo()))()
-        )
-      );
-      break;
-    case "status":
-      dependencies.printStatus();
-      writeLine("[CloudServer] Mode: qoder pairing (no listening service)");
-      break;
-    case "stop":
-      await dependencies.stopServer();
-      break;
-    case "logs":
-      dependencies.printLogs();
-      break;
-  }
-}
-
 // src/cli.ts
-var CLOUD_SERVER_VERSION = true ? "3.0.0-beta.0" : "unknown";
+import { NodeCapabilityRegistry } from "@mearl/daemon-core/capabilities";
+var CLOUD_SERVER_VERSION = true ? "3.0.0-beta.10" : "unknown";
 var COMMANDS = ["start", "stop", "restart", "status", "logs"];
 var START_OPTION_NAMES = /* @__PURE__ */ new Set([
   "foreground",
@@ -322,8 +269,11 @@ async function main(argv = process.argv.slice(2)) {
     return 0;
   }
   const mode = resolveCloudServerMode();
-  if (mode === "qoder") {
-    await runQoderCloudServerCommand(parsed.command, {
+  if (mode !== "websocket") {
+    const hook = `cloud.server.${mode}`;
+    const registry = new NodeCapabilityRegistry({ version: CLOUD_SERVER_VERSION }, capabilityDirectory(), { hooks: [hook] });
+    await registry.refresh();
+    await registry.require(hook)(parsed.command, {
       isServerRunning: isDaemonRunning,
       stopServer: stopDaemon,
       printStatus: statusDaemon,

package/dist/mode.d.ts

@@ -1,4 +1,4 @@
-export type CloudServerMode = 'websocket' | 'qoder';
+export type CloudServerMode = string;
 export declare const CLOUD_SERVER_MODE_ENV = "MEARL_CLOUD_MODE";
 interface CloudServerModeStorage {
     modeFile?: string;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mearl/cloud-server",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-beta.10",
   "description": "Cloud WebSocket server for Mearl — bridges cloud agents to local connectors",
   "type": "module",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=20.18.0"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,11 +33,11 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "commander": "^15.0.0",
+    "commander": "^14.0.3",
     "ws": "^8.18.0",
-    "@mearl/client": "3.0.0-beta.0",
-    "@mearl/cloud-types": "3.0.0-beta.0",
-    "@mearl/daemon-core": "3.0.0-beta.0"
+    "@mearl/client": "3.0.0-beta.10",
+    "@mearl/cloud-types": "3.0.0-beta.10",
+    "@mearl/daemon-core": "3.0.0-beta.10"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
@@ -45,6 +45,11 @@
     "esbuild": "^0.28.2",
     "typescript": "^5.8.3"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
+    "directory": "packages/cloud/cloud-server"
+  },
   "scripts": {
     "build": "rm -rf dist/ && node build.mjs",
     "dev": "tsc --watch",

package/dist/qoder.d.ts

@@ -1,29 +0,0 @@
-export interface QoderPairingInfo {
-    pairingCode: string;
-    createdAt: number;
-    connectorUrl: string;
-    toolInput: {
-        action: 'pair';
-        payload: {
-            code: string;
-        };
-    };
-}
-export interface QoderPairingOptions {
-    now?: () => number;
-    createCode?: () => string;
-}
-export type CloudServerCommand = 'start' | 'stop' | 'restart' | 'status' | 'logs';
-interface QoderCloudServerDependencies {
-    createPairing?: () => QoderPairingInfo;
-    isServerRunning: () => boolean;
-    printLogs: () => void;
-    printStatus: () => void;
-    stopServer: () => Promise<void>;
-    writeLine?: (message: string) => void;
-}
-/** Create a short-lived correlation handle without embedding Qoder credentials in the URL. */
-export declare function createQoderPairingInfo(options?: QoderPairingOptions): QoderPairingInfo;
-export declare function formatQoderPairingOutput(info: QoderPairingInfo): string;
-export declare function runQoderCloudServerCommand(command: CloudServerCommand, dependencies: QoderCloudServerDependencies): Promise<void>;
-export {};