@mearl/cloud-server 2.1.0 → 2.2.0

package/README.md

@@ -21,6 +21,7 @@ mearl-cloud-server [command] [options]
 ```
 
 **子命令：**
+
 - `start` - 后台启动 server（默认，不写也等价于 `start`）
 - `stop` - 停止后台 server
 - `restart` - 重启后台 server
@@ -28,6 +29,7 @@ mearl-cloud-server [command] [options]
 - `logs` - 打印 server 日志末尾
 
 **选项：**
+
 - `--foreground` / `-f` - 前台运行（不守护化，适合 systemd / Docker / PM2）
 - `--port <port>` - 服务器端口（默认 8080）
 - `--path <path>` - WebSocket 路径（默认 /ws）
@@ -36,6 +38,7 @@ mearl-cloud-server [command] [options]
 - `--max-connections <n>` - 最大连接数（默认 100）
 
 **示例：**
+
 ```bash
 # 后台启动（自动生成 token），打印连接命令后立即返回
 mearl-cloud-server
@@ -55,6 +58,7 @@ mearl-cloud-server --foreground
 ```
 
 后台启动后会打印供本地机器使用的连接命令，例如：
+
 ```
 [CloudServer] Started in background (pid 12345)
 [CloudServer] Logs: ~/.mearl/cloud-server.log
@@ -64,16 +68,19 @@ mearl-cloud-server --foreground
 ```
 
 运行时文件位于 `~/.mearl/`：
+
 - `cloud-server.json` - 连接配置（含 server URL、pid、端口等），cloud-client 自动读取
 - `cloud-server.log` - 后台进程日志（`logs` 子命令读取，或 `tail -f` 跟踪）；超过 5MB 会在下次启动时滚动为 `cloud-server.log.1`
 
 > 守护进程的启停、状态、日志滚动等生命周期逻辑由共享包 [`@mearl/daemon-core`](../../daemon-core) 提供（与 cloud-connector 复用同一套实现）。
 
 **关于 token：**
+
 - 未指定 `--token` 时会自动生成。`restart` 会**沿用当前 token**，因此之前打印的连接命令重启后仍然有效。
 - `stop` 后再 `start` 属于全新启动，会重新生成 token；若希望连接命令长期固定，请显式传入 `--token` 或设置 `MEARL_TOKEN`。
 
 **环境变量：**
+
 - `MEARL_TOKEN` - 鉴权密钥（覆盖 --token 选项）
 - `CLOUD_SERVER_HOST` - 公网主机名（默认自动获取）
 
@@ -125,21 +132,32 @@ Server 接受两种类型的连接：
 1. **Agent 连接** - 发起请求的云端客户端
 2. **Connector 连接** - 转发请求到 native-host 的本地连接器
 
-Server 会自动识别连接类型，并将 Agent 的请求转发到可用的 Connector。
+两类客户端建连后会分别发送 `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",
@@ -150,6 +168,7 @@ Server 会自动识别连接类型，并将 Agent 的请求转发到可用的 Co
 ```
 
 ### 心跳格式
+
 ```json
 { "type": "ping", "timestamp": 1234567890 }
 { "type": "pong", "timestamp": 1234567890 }
@@ -211,4 +230,4 @@ pm2 start mearl-cloud-server --name mtop-cloud-server -- --foreground --port 808
 - 设置合理的 `maxConnections` 限制资源占用
 - 启用 `token` 鉴权保护服务安全
 - 在沙箱环境中启动时，会自动检测并使用平台分配的公网地址
-- 如果沙箱端口映射 API 不可用，会回退到使用本地 IP 地址
+- 如果沙箱端口映射 API 不可用，会回退到使用本地 IP 地址

package/dist/cli.js

@@ -20,9 +20,12 @@ var LOG_FILE = join(CONFIG_DIR, "cloud-server.log");
 
 // src/index.ts
 import {
+  isAgentHelloMessage,
+  isConnectorHelloMessage,
   isHeartbeatMessage,
   isCloudMessage,
   isCloudResponse,
+  resolveCloudConnectorSelector,
   MAX_BUFFER_SIZE,
   DEFAULT_HEARTBEAT_TIMEOUT,
   DEFAULT_REQUEST_TIMEOUT
@@ -46,6 +49,7 @@ var DEFAULT_PATH = "/ws";
 var DEFAULT_MAX_CONNECTIONS = 100;
 var DEFAULT_MAX_MESSAGE_SIZE = 10 * 1024 * 1024;
 var RESPONSE_GRACE_MS = 5e3;
+var LEGACY_CONNECTOR_HELLO_GRACE_MS = 1e3;
 var CloudServer = class {
   options;
   connectorWss = null;
@@ -220,9 +224,8 @@ var CloudServer = class {
       ws,
       id: connId,
       lastHeartbeat: Date.now(),
-      // The loopback listener is agent-only. Marking it immediately prevents an
-      // idle local client from being mistaken for a connector during reconnects.
-      isAgent: fromLocal,
+      connectedAt: Date.now(),
+      role: fromLocal ? "agent" : "pending",
       fromLocal,
       messageBuffer: ""
     };
@@ -246,7 +249,7 @@ var CloudServer = class {
         if (!line.trim()) continue;
         try {
           const message = JSON.parse(line);
-          this.handleMessage(ws, message, connId);
+          this.handleMessage(ws, message);
         } catch (error) {
           console.error(`[CloudServer] Failed to parse message from ${connId}:`, line, error);
         }
@@ -261,7 +264,7 @@ var CloudServer = class {
       console.error(`[CloudServer] Connection error for ${connId}:`, error.message);
     });
   }
-  handleMessage(ws, message, connId) {
+  handleMessage(ws, message) {
     const conn = this.connections.get(ws);
     if (!conn) return;
     if (isHeartbeatMessage(message)) {
@@ -275,20 +278,61 @@ var CloudServer = class {
       }
       return;
     }
+    if (isAgentHelloMessage(message)) {
+      this.handleAgentHello(ws);
+      return;
+    }
+    if (isConnectorHelloMessage(message)) {
+      this.handleConnectorHello(ws, message);
+      return;
+    }
     if (isCloudResponse(message)) {
-      this.handleResponse(ws, message, connId);
+      this.handleResponse(ws, message);
       return;
     }
     if (isCloudMessage(message)) {
-      this.handleRequest(ws, message, connId);
+      this.handleRequest(ws, message);
       return;
     }
   }
-  handleRequest(ws, message, _connId) {
-    const { id, action, data } = message;
+  handleAgentHello(ws) {
     const conn = this.connections.get(ws);
     if (!conn) return;
     if (!conn.fromLocal && !this.options.allowRemoteAgent) {
+      ws.close(1008, "Agent must be local");
+      return;
+    }
+    conn.role = "agent";
+    delete conn.connector;
+  }
+  handleConnectorHello(ws, message) {
+    const conn = this.connections.get(ws);
+    if (!conn || conn.fromLocal) {
+      ws.close(1008, "Connector must use the connector listener");
+      return;
+    }
+    for (const [otherWs, other] of this.connections) {
+      if (otherWs !== ws && other.role === "connector" && other.connector?.connectorId === message.connectorId) {
+        this.connections.delete(otherWs);
+        this.rejectPendingForWs(otherWs);
+        otherWs.close(1e3, "Connector replaced by a newer connection");
+      }
+    }
+    conn.role = "connector";
+    conn.connector = {
+      connectorId: message.connectorId,
+      name: message.name,
+      ...message.version ? { version: message.version } : {}
+    };
+    console.log(
+      `[CloudServer] Connector registered: ${message.name} (${message.connectorId}, v${message.version ?? "unknown"})`
+    );
+  }
+  handleRequest(ws, message) {
+    const { id, action, data } = message;
+    const conn = this.connections.get(ws);
+    if (!conn) return;
+    if (conn.role !== "agent") {
       console.warn(
         `[CloudServer] Rejected agent request from non-local connection ${conn.id} (action: ${action})`
       );
@@ -296,57 +340,124 @@ var CloudServer = class {
         JSON.stringify({
           id,
           success: false,
-          error: "Agent requests are only accepted on the local interface (127.0.0.1). Run cloud-client on the same machine as cloud-server, or start the server with --allow-remote-agent to override."
+          error: this.options.allowRemoteAgent && !conn.fromLocal ? "Remote agents must identify themselves with an agent_hello message before issuing commands." : "Agent requests are only accepted on the local interface (127.0.0.1). Run cloud-client on the same machine as cloud-server, or start the server with --allow-remote-agent to override."
         }) + "\n"
       );
-      ws.close(1008, "Agent must be local");
       return;
     }
-    conn.isAgent = true;
-    const targetWs = this.findConnector();
-    if (!targetWs) {
-      ws.send(JSON.stringify({ id, success: false, error: "No local connector available" }) + "\n");
+    if (action === "connector_list") {
+      const response = {
+        id,
+        success: true,
+        data: this.getConnectorList()
+      };
+      ws.send(JSON.stringify(response) + "\n");
       return;
     }
-    if (this.pendingRequests.has(id)) {
-      ws.send(JSON.stringify({ id, success: false, error: "Duplicate request id" }) + "\n");
+    const target = this.resolveConnector(message.connector);
+    if ("error" in target) {
+      ws.send(JSON.stringify({ id, success: false, error: target.error }) + "\n");
       return;
     }
+    const routeId = randomBytes(12).toString("base64url");
     const requestedTimeoutSec = Number(message.timeoutSec);
     const timeoutSec = Number.isFinite(requestedTimeoutSec) && requestedTimeoutSec > 0 ? Math.min(requestedTimeoutSec, 3600) : resolveActionTimeoutSec(action, data, this.options.requestTimeout);
     const timer = setTimeout(
       () => {
-        this.pendingRequests.delete(id);
+        this.pendingRequests.delete(routeId);
         if (ws.readyState === WebSocket.OPEN) {
           ws.send(JSON.stringify({ id, success: false, error: "Request timeout" }) + "\n");
         }
       },
       timeoutSec * 1e3 + RESPONSE_GRACE_MS
     );
-    this.pendingRequests.set(id, { agentWs: ws, connectorWs: targetWs, timer });
-    targetWs.send(
-      JSON.stringify({ id, action, data, browser: message.browser, timeoutSec }) + "\n"
+    this.pendingRequests.set(routeId, {
+      agentRequestId: id,
+      agentWs: ws,
+      connectorWs: target.ws,
+      timer
+    });
+    target.ws.send(
+      JSON.stringify({
+        id: routeId,
+        action,
+        data,
+        browser: message.browser,
+        timeoutSec
+      }) + "\n"
     );
   }
-  handleResponse(ws, response, _connId) {
+  handleResponse(ws, response) {
     const conn = this.connections.get(ws);
     if (!conn) return;
-    if (conn.fromLocal || conn.isAgent) return;
+    if (conn.role !== "connector") return;
     const pending = this.pendingRequests.get(response.id);
     if (!pending || pending.connectorWs !== ws) return;
     this.pendingRequests.delete(response.id);
     clearTimeout(pending.timer);
     if (pending.agentWs.readyState === WebSocket.OPEN) {
-      pending.agentWs.send(JSON.stringify(response) + "\n");
+      pending.agentWs.send(
+        JSON.stringify({ ...response, id: pending.agentRequestId }) + "\n"
+      );
     }
   }
-  findConnector() {
+  connectorInfo(ws, conn) {
+    const pendingRequests = Array.from(this.pendingRequests.values()).filter(
+      (pending) => pending.connectorWs === ws
+    ).length;
+    return {
+      connectorId: conn.connector?.connectorId ?? conn.id,
+      name: conn.connector?.name ?? `legacy-${conn.id.slice(-8)}`,
+      ...conn.connector?.version ? { version: conn.connector.version } : {},
+      connectedAt: new Date(conn.connectedAt).toISOString(),
+      lastHeartbeatAt: new Date(conn.lastHeartbeat).toISOString(),
+      pendingRequests,
+      ...!conn.connector ? { legacy: true } : {}
+    };
+  }
+  getConnectorConnections() {
+    const connectors = [];
     for (const [ws, conn] of this.connections) {
-      if (!conn.fromLocal && !conn.isAgent && ws.readyState === WebSocket.OPEN) {
-        return ws;
+      if (conn.role === "pending" && Date.now() - conn.connectedAt >= LEGACY_CONNECTOR_HELLO_GRACE_MS) {
+        conn.role = "connector";
       }
+      if (conn.role !== "connector" || ws.readyState !== WebSocket.OPEN) continue;
+      connectors.push({ ws, conn, info: this.connectorInfo(ws, conn) });
     }
-    return null;
+    return connectors.sort((a, b) => a.info.name.localeCompare(b.info.name));
+  }
+  getConnectorList() {
+    const connectors = this.getConnectorConnections().map(({ info }) => info);
+    return { count: connectors.length, connectors };
+  }
+  resolveConnector(selector) {
+    const connectors = this.getConnectorConnections();
+    if (connectors.length === 0) return { error: "No local connector available" };
+    if (!selector) {
+      if (connectors.length === 1) {
+        return { ws: connectors[0].ws, info: connectors[0].info };
+      }
+      return {
+        error: `Multiple cloud connectors are connected (${connectors.length}). Run \`mearl connector_list\` and pass --connector <id|name>.`
+      };
+    }
+    const selection = resolveCloudConnectorSelector(
+      connectors.map(({ info }) => info),
+      selector
+    );
+    if (selection.status === "matched") {
+      const matched = connectors.find(({ info }) => info === selection.connector);
+      return { ws: matched.ws, info: matched.info };
+    }
+    const available = connectors.map(({ info }) => `${info.name} [${info.connectorId}]`).join(", ");
+    if (selection.status === "ambiguous") {
+      return {
+        error: `Cloud connector selector "${selector}" is ambiguous. Available: ${available}`
+      };
+    }
+    return {
+      error: `No cloud connector matches "${selector}". Available: ${available}`
+    };
   }
   rejectPendingForWs(ws) {
     this.pendingRequests.forEach((pending, id) => {
@@ -355,7 +466,11 @@ var CloudServer = class {
       this.pendingRequests.delete(id);
       if (pending.connectorWs === ws && pending.agentWs !== ws && pending.agentWs.readyState === WebSocket.OPEN) {
         pending.agentWs.send(
-          JSON.stringify({ id, success: false, error: "Connector connection closed" }) + "\n"
+          JSON.stringify({
+            id: pending.agentRequestId,
+            success: false,
+            error: "Connector connection closed"
+          }) + "\n"
         );
       }
     });
@@ -430,15 +545,13 @@ var CloudServer = class {
   }
   getStats() {
     let agents = 0;
-    let connectors = 0;
     for (const conn of this.connections.values()) {
-      if (conn.isAgent) agents++;
-      else connectors++;
+      if (conn.role === "agent") agents++;
     }
     return {
       connections: this.connections.size,
       agents,
-      connectors,
+      connectors: this.getConnectorConnections().length,
       pendingRequests: this.pendingRequests.size
     };
   }
@@ -507,7 +620,7 @@ async function runForeground(options) {
 }
 
 // src/cli.ts
-var CLOUD_SERVER_VERSION = true ? "2.1.0" : "unknown";
+var CLOUD_SERVER_VERSION = true ? "2.2.0" : "unknown";
 var argv = process.argv.slice(2);
 if (argv.includes("--version") || argv.includes("-v")) {
   console.log(CLOUD_SERVER_VERSION);

package/dist/index.d.ts

@@ -48,9 +48,14 @@ export declare class CloudServer {
     stop(): Promise<void>;
     private handleConnection;
     private handleMessage;
+    private handleAgentHello;
+    private handleConnectorHello;
     private handleRequest;
     private handleResponse;
-    private findConnector;
+    private connectorInfo;
+    private getConnectorConnections;
+    private getConnectorList;
+    private resolveConnector;
     private rejectPendingForWs;
     private startHeartbeatCheck;
     private getPublicIP;

package/dist/index.js

@@ -14,9 +14,12 @@ var LOG_FILE = join(CONFIG_DIR, "cloud-server.log");
 
 // src/index.ts
 import {
+  isAgentHelloMessage,
+  isConnectorHelloMessage,
   isHeartbeatMessage,
   isCloudMessage,
   isCloudResponse,
+  resolveCloudConnectorSelector,
   MAX_BUFFER_SIZE,
   DEFAULT_HEARTBEAT_TIMEOUT,
   DEFAULT_REQUEST_TIMEOUT
@@ -40,6 +43,7 @@ var DEFAULT_PATH = "/ws";
 var DEFAULT_MAX_CONNECTIONS = 100;
 var DEFAULT_MAX_MESSAGE_SIZE = 10 * 1024 * 1024;
 var RESPONSE_GRACE_MS = 5e3;
+var LEGACY_CONNECTOR_HELLO_GRACE_MS = 1e3;
 var CloudServer = class {
   options;
   connectorWss = null;
@@ -214,9 +218,8 @@ var CloudServer = class {
       ws,
       id: connId,
       lastHeartbeat: Date.now(),
-      // The loopback listener is agent-only. Marking it immediately prevents an
-      // idle local client from being mistaken for a connector during reconnects.
-      isAgent: fromLocal,
+      connectedAt: Date.now(),
+      role: fromLocal ? "agent" : "pending",
       fromLocal,
       messageBuffer: ""
     };
@@ -240,7 +243,7 @@ var CloudServer = class {
         if (!line.trim()) continue;
         try {
           const message = JSON.parse(line);
-          this.handleMessage(ws, message, connId);
+          this.handleMessage(ws, message);
         } catch (error) {
           console.error(`[CloudServer] Failed to parse message from ${connId}:`, line, error);
         }
@@ -255,7 +258,7 @@ var CloudServer = class {
       console.error(`[CloudServer] Connection error for ${connId}:`, error.message);
     });
   }
-  handleMessage(ws, message, connId) {
+  handleMessage(ws, message) {
     const conn = this.connections.get(ws);
     if (!conn) return;
     if (isHeartbeatMessage(message)) {
@@ -269,20 +272,61 @@ var CloudServer = class {
       }
       return;
     }
+    if (isAgentHelloMessage(message)) {
+      this.handleAgentHello(ws);
+      return;
+    }
+    if (isConnectorHelloMessage(message)) {
+      this.handleConnectorHello(ws, message);
+      return;
+    }
     if (isCloudResponse(message)) {
-      this.handleResponse(ws, message, connId);
+      this.handleResponse(ws, message);
       return;
     }
     if (isCloudMessage(message)) {
-      this.handleRequest(ws, message, connId);
+      this.handleRequest(ws, message);
       return;
     }
   }
-  handleRequest(ws, message, _connId) {
-    const { id, action, data } = message;
+  handleAgentHello(ws) {
     const conn = this.connections.get(ws);
     if (!conn) return;
     if (!conn.fromLocal && !this.options.allowRemoteAgent) {
+      ws.close(1008, "Agent must be local");
+      return;
+    }
+    conn.role = "agent";
+    delete conn.connector;
+  }
+  handleConnectorHello(ws, message) {
+    const conn = this.connections.get(ws);
+    if (!conn || conn.fromLocal) {
+      ws.close(1008, "Connector must use the connector listener");
+      return;
+    }
+    for (const [otherWs, other] of this.connections) {
+      if (otherWs !== ws && other.role === "connector" && other.connector?.connectorId === message.connectorId) {
+        this.connections.delete(otherWs);
+        this.rejectPendingForWs(otherWs);
+        otherWs.close(1e3, "Connector replaced by a newer connection");
+      }
+    }
+    conn.role = "connector";
+    conn.connector = {
+      connectorId: message.connectorId,
+      name: message.name,
+      ...message.version ? { version: message.version } : {}
+    };
+    console.log(
+      `[CloudServer] Connector registered: ${message.name} (${message.connectorId}, v${message.version ?? "unknown"})`
+    );
+  }
+  handleRequest(ws, message) {
+    const { id, action, data } = message;
+    const conn = this.connections.get(ws);
+    if (!conn) return;
+    if (conn.role !== "agent") {
       console.warn(
         `[CloudServer] Rejected agent request from non-local connection ${conn.id} (action: ${action})`
       );
@@ -290,57 +334,124 @@ var CloudServer = class {
         JSON.stringify({
           id,
           success: false,
-          error: "Agent requests are only accepted on the local interface (127.0.0.1). Run cloud-client on the same machine as cloud-server, or start the server with --allow-remote-agent to override."
+          error: this.options.allowRemoteAgent && !conn.fromLocal ? "Remote agents must identify themselves with an agent_hello message before issuing commands." : "Agent requests are only accepted on the local interface (127.0.0.1). Run cloud-client on the same machine as cloud-server, or start the server with --allow-remote-agent to override."
         }) + "\n"
       );
-      ws.close(1008, "Agent must be local");
       return;
     }
-    conn.isAgent = true;
-    const targetWs = this.findConnector();
-    if (!targetWs) {
-      ws.send(JSON.stringify({ id, success: false, error: "No local connector available" }) + "\n");
+    if (action === "connector_list") {
+      const response = {
+        id,
+        success: true,
+        data: this.getConnectorList()
+      };
+      ws.send(JSON.stringify(response) + "\n");
       return;
     }
-    if (this.pendingRequests.has(id)) {
-      ws.send(JSON.stringify({ id, success: false, error: "Duplicate request id" }) + "\n");
+    const target = this.resolveConnector(message.connector);
+    if ("error" in target) {
+      ws.send(JSON.stringify({ id, success: false, error: target.error }) + "\n");
       return;
     }
+    const routeId = randomBytes(12).toString("base64url");
     const requestedTimeoutSec = Number(message.timeoutSec);
     const timeoutSec = Number.isFinite(requestedTimeoutSec) && requestedTimeoutSec > 0 ? Math.min(requestedTimeoutSec, 3600) : resolveActionTimeoutSec(action, data, this.options.requestTimeout);
     const timer = setTimeout(
       () => {
-        this.pendingRequests.delete(id);
+        this.pendingRequests.delete(routeId);
         if (ws.readyState === WebSocket.OPEN) {
           ws.send(JSON.stringify({ id, success: false, error: "Request timeout" }) + "\n");
         }
       },
       timeoutSec * 1e3 + RESPONSE_GRACE_MS
     );
-    this.pendingRequests.set(id, { agentWs: ws, connectorWs: targetWs, timer });
-    targetWs.send(
-      JSON.stringify({ id, action, data, browser: message.browser, timeoutSec }) + "\n"
+    this.pendingRequests.set(routeId, {
+      agentRequestId: id,
+      agentWs: ws,
+      connectorWs: target.ws,
+      timer
+    });
+    target.ws.send(
+      JSON.stringify({
+        id: routeId,
+        action,
+        data,
+        browser: message.browser,
+        timeoutSec
+      }) + "\n"
     );
   }
-  handleResponse(ws, response, _connId) {
+  handleResponse(ws, response) {
     const conn = this.connections.get(ws);
     if (!conn) return;
-    if (conn.fromLocal || conn.isAgent) return;
+    if (conn.role !== "connector") return;
     const pending = this.pendingRequests.get(response.id);
     if (!pending || pending.connectorWs !== ws) return;
     this.pendingRequests.delete(response.id);
     clearTimeout(pending.timer);
     if (pending.agentWs.readyState === WebSocket.OPEN) {
-      pending.agentWs.send(JSON.stringify(response) + "\n");
+      pending.agentWs.send(
+        JSON.stringify({ ...response, id: pending.agentRequestId }) + "\n"
+      );
     }
   }
-  findConnector() {
+  connectorInfo(ws, conn) {
+    const pendingRequests = Array.from(this.pendingRequests.values()).filter(
+      (pending) => pending.connectorWs === ws
+    ).length;
+    return {
+      connectorId: conn.connector?.connectorId ?? conn.id,
+      name: conn.connector?.name ?? `legacy-${conn.id.slice(-8)}`,
+      ...conn.connector?.version ? { version: conn.connector.version } : {},
+      connectedAt: new Date(conn.connectedAt).toISOString(),
+      lastHeartbeatAt: new Date(conn.lastHeartbeat).toISOString(),
+      pendingRequests,
+      ...!conn.connector ? { legacy: true } : {}
+    };
+  }
+  getConnectorConnections() {
+    const connectors = [];
     for (const [ws, conn] of this.connections) {
-      if (!conn.fromLocal && !conn.isAgent && ws.readyState === WebSocket.OPEN) {
-        return ws;
+      if (conn.role === "pending" && Date.now() - conn.connectedAt >= LEGACY_CONNECTOR_HELLO_GRACE_MS) {
+        conn.role = "connector";
       }
+      if (conn.role !== "connector" || ws.readyState !== WebSocket.OPEN) continue;
+      connectors.push({ ws, conn, info: this.connectorInfo(ws, conn) });
     }
-    return null;
+    return connectors.sort((a, b) => a.info.name.localeCompare(b.info.name));
+  }
+  getConnectorList() {
+    const connectors = this.getConnectorConnections().map(({ info }) => info);
+    return { count: connectors.length, connectors };
+  }
+  resolveConnector(selector) {
+    const connectors = this.getConnectorConnections();
+    if (connectors.length === 0) return { error: "No local connector available" };
+    if (!selector) {
+      if (connectors.length === 1) {
+        return { ws: connectors[0].ws, info: connectors[0].info };
+      }
+      return {
+        error: `Multiple cloud connectors are connected (${connectors.length}). Run \`mearl connector_list\` and pass --connector <id|name>.`
+      };
+    }
+    const selection = resolveCloudConnectorSelector(
+      connectors.map(({ info }) => info),
+      selector
+    );
+    if (selection.status === "matched") {
+      const matched = connectors.find(({ info }) => info === selection.connector);
+      return { ws: matched.ws, info: matched.info };
+    }
+    const available = connectors.map(({ info }) => `${info.name} [${info.connectorId}]`).join(", ");
+    if (selection.status === "ambiguous") {
+      return {
+        error: `Cloud connector selector "${selector}" is ambiguous. Available: ${available}`
+      };
+    }
+    return {
+      error: `No cloud connector matches "${selector}". Available: ${available}`
+    };
   }
   rejectPendingForWs(ws) {
     this.pendingRequests.forEach((pending, id) => {
@@ -349,7 +460,11 @@ var CloudServer = class {
       this.pendingRequests.delete(id);
       if (pending.connectorWs === ws && pending.agentWs !== ws && pending.agentWs.readyState === WebSocket.OPEN) {
         pending.agentWs.send(
-          JSON.stringify({ id, success: false, error: "Connector connection closed" }) + "\n"
+          JSON.stringify({
+            id: pending.agentRequestId,
+            success: false,
+            error: "Connector connection closed"
+          }) + "\n"
         );
       }
     });
@@ -424,15 +539,13 @@ var CloudServer = class {
   }
   getStats() {
     let agents = 0;
-    let connectors = 0;
     for (const conn of this.connections.values()) {
-      if (conn.isAgent) agents++;
-      else connectors++;
+      if (conn.role === "agent") agents++;
     }
     return {
       connections: this.connections.size,
       agents,
-      connectors,
+      connectors: this.getConnectorConnections().length,
       pendingRequests: this.pendingRequests.size
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/cloud-server",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Cloud WebSocket server for Mearl — bridges cloud agents to local connectors",
   "type": "module",
   "main": "dist/index.js",
@@ -29,9 +29,9 @@
   "dependencies": {
     "node-fetch": "^3.3.2",
     "ws": "^8.18.0",
-    "@mearl/client": "2.1.0",
-    "@mearl/cloud-types": "2.1.0",
-    "@mearl/daemon-core": "2.1.0"
+    "@mearl/cloud-types": "2.2.0",
+    "@mearl/client": "2.2.0",
+    "@mearl/daemon-core": "2.2.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",