@coclaw/openclaw-coclaw 0.21.2 → 0.21.4

package/index.js

@@ -5,6 +5,7 @@ import { notBound, bindOk, unbindOk, claimCodeCreated } from './src/common/messa
 import { coclawChannelPlugin } from './src/channel-plugin.js';
 import { ensureAgentSession, gatewayAgentRpc, restartRealtimeBridge, stopRealtimeBridge, waitForSessionsReady, broadcastPluginEvent } from './src/realtime-bridge.js';
 import { getHostName, readSettings, writeName, MAX_NAME_LENGTH } from './src/settings.js';
+import { readConfig } from './src/config.js';
 import { setRuntime } from './src/runtime.js';
 import { createSessionManager } from './src/session-manager/manager.js';
 import { TopicManager } from './src/topic-manager/manager.js';
@@ -157,6 +158,13 @@ const plugin = {
 		setRuntime(api.runtime);
 		const logger = api?.logger ?? console;
 		installAbortRegistryDiag(logger);
+
+		// 未 bind 时打条提示，便于 hub 装机用户看到下一步动作
+		readConfig().then((cfg) => {
+			if (!cfg?.token) {
+				logger.info?.('[coclaw] not bound — run `openclaw coclaw enroll` to connect to CoClaw');
+			}
+		}).catch(() => {});
 		const manager = createSessionManager({ logger });
 		const topicManager = new TopicManager({ logger });
 		const chatHistoryManager = new ChatHistoryManager({ logger });

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-coclaw",
   "name": "CoClaw",
-  "description": "OpenClaw CoClaw channel plugin for remote chat",
+  "description": "OpenClaw CoClaw channel plugin for remote chat. Run `openclaw coclaw enroll` after install to connect to CoClaw.",
   "activation": {
     "onStartup": true
   },
@@ -11,9 +11,6 @@
     "properties": {
       "serverUrl": {
         "type": "string"
-      },
-      "gatewayWsUrl": {
-        "type": "string"
       }
     }
   }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.21.2",
+  "version": "0.21.4",
   "type": "module",
   "license": "Apache-2.0",
-  "description": "OpenClaw CoClaw channel plugin for remote chat",
+  "description": "OpenClaw CoClaw channel plugin for remote chat. Run `openclaw coclaw enroll` after install to connect to CoClaw.",
   "repository": {
     "type": "git",
     "url": "https://github.com/coclaw/coclaw.git",

package/src/realtime-bridge.js

@@ -25,8 +25,17 @@ const SERVER_HB_PING_MS = 25_000;
 const SERVER_HB_TIMEOUT_MS = 45_000;
 const SERVER_HB_MAX_MISS = 3; // 连续 3 次无响应才断连（~135s）。上游主线程 spike 实测最坏 ~89.5s（issue #75069），余量 ~1.5x
 // gateway 握手失败的指数退避表：每个元素是"上一次失败"之后、"下一次尝试"之前的等待时间。
-// 最多 5 次重试（加上首次尝试共 6 次），全部失败后进入 gave-up 终态，不再自动尝试。
-const GATEWAY_RETRY_DELAYS_MS = [5_000, 10_000, 20_000, 20_000, 20_000];
+// 最多 N 次重试（N=length；加上首次尝试共 N+1 次），全部失败后进入 gave-up 终态，
+// 终态后必须 stop+start 才能恢复（无运行期自动复活）——所以预算要够覆盖慢启动场景。
+// 表前置 4 档（1s + 3×1.5s）专门压低"server 启动期 sidecars 还没就绪"窗口（推荐
+// retryAfterMs=500）；尾段 9 × 20s 把总预算拉到 ~200s（>3 分钟），覆盖 profile 初始化、
+// 笔记本刚开机磁盘忙、pion 子进程首次 spawn 等慢启动场景，避免误判"放弃"。
+// export 是为了让测试 helper 通过同一份常量识别 retry timer，避免硬编码副本与生产代码漂移。
+export const GATEWAY_RETRY_DELAYS_MS = [
+	1_000, 1_500, 1_500, 1_500,
+	5_000, 10_000,
+	20_000, 20_000, 20_000, 20_000, 20_000, 20_000, 20_000, 20_000, 20_000,
+];
 // v3 握手失败时，只有错误消息匹配此正则才回退到不带 device 的 legacy 握手。
 // 严格限定在"签名/设备/scope/协议"相关错误，避免对网络/内部错误做无意义的降级尝试。
 const GATEWAY_HANDSHAKE_FALLBACK_PATTERN = /signature|device|scope|protocol/i;
@@ -90,20 +99,26 @@ function maskUrlToken(url) {
 }
 
 // 仅在未注入 resolveGatewayAuthToken 时使用，依赖 runtime / 环境变量
+// 优先级：config.gateway.auth.token > env OPENCLAW_GATEWAY_TOKEN
+// 与上游 server 的 auth-surface-resolution 同方向：config 主、env 兜底。
+// env 路径保留是为 ensureGatewayStartupAuth 的 env-only 边角（token 由 env 提供时
+// 上游不会写回 cfg），cfg 读不到时仍能拿到正确 token。
 export function defaultResolveGatewayAuthToken() {
-	const envToken = process.env.OPENCLAW_GATEWAY_TOKEN?.trim();
-	if (envToken) {
-		return envToken;
-	}
 	try {
 		const cfg = getClawConfig();
 		const token = cfg?.gateway?.auth?.token;
-		return typeof token === 'string' && token.trim() ? token.trim() : '';
+		if (typeof token === 'string' && token.trim()) {
+			return token.trim();
+		}
 	}
 	catch (err) {
 		console.warn?.(`[coclaw] resolve gateway auth token failed: ${String(err?.message ?? err)}`);
-		return '';
 	}
+	const envToken = process.env.OPENCLAW_GATEWAY_TOKEN?.trim();
+	if (envToken) {
+		return envToken;
+	}
+	return '';
 }
 
 /**
@@ -247,9 +262,7 @@ export class RealtimeBridge {
 	}
 
 	__resolveGatewayWsUrl() {
-		return this.pluginConfig?.gatewayWsUrl
-			?? process.env.COCLAW_GATEWAY_WS_URL
-			?? DEFAULT_GATEWAY_WS_URL;
+		return process.env.COCLAW_GATEWAY_WS_URL ?? DEFAULT_GATEWAY_WS_URL;
 	}
 
 	async __clearTokenLocal(unboundClawId) {

package/src/webrtc/webrtc-peer.js

@@ -7,6 +7,7 @@ import { RpcDcSender, DC_LOW_WATER_MARK, MAX_SINGLE_MSG_BYTES } from './rpc-dc-s
 import { createRpcDropMonitor } from './rpc-drop-monitor.js';
 import { isAgentRunResponse } from './agent-run-response.js';
 import { remoteLog } from '../remote-log.js';
+import { createMutex } from '../utils/mutex.js';
 
 // rpc DC 发送队列实现选择（B-stage2 B9b）。
 // - 'fbq'：FileBackedQueue（当前生产默认）—— 长时间后台 / ICE 恢复等慢消化场景溢出到磁盘
@@ -71,6 +72,11 @@ export class WebRtcPeer {
 		this.__rtcTag = impl ? `[coclaw/rtc:${impl}]` : '[coclaw/rtc]';
 		/** @type {Map<string, { pc: object, rpcChannel: object|null, rpcQueue: MemoryQueue|null, rpcDcSender: RpcDcSender|null, rpcConsumeLoop: Promise<void>|null, rpcDropMonitor: object|null, fileChannels: Set, remoteMaxMessageSize: number, nextMsgId: number }>} */
 		this.__sessions = new Map();
+		// per-connId offer mutex：串行化同 connId 的 __handleOffer 调用，防止两条 ICE restart
+		// offer 几乎同时到达时三连 await 中间被并发 offer 重入触发 pion 状态机
+		// InvalidModificationError。lazy 创建，closeByConnId 末尾 delete 释放。
+		/** @type {Map<string, ReturnType<typeof createMutex>>} */
+		this.__offerMutexes = new Map();
 	}
 
 	/** 处理来自 Server 转发的信令消息 */
@@ -142,6 +148,15 @@ export class WebRtcPeer {
 			session.rpcChannel = null;
 		}
 		await session.pc.close();
+		// 清理 per-connId offer mutex 键：mutex 生命期与 session 生命期一一对应，
+		// session 销毁时 mutex 同步销毁（详见 __handleOffer 注释）。
+		// 注意：__handleOffer 内部 mutex 引用是闭包已在 mu.withLock 内拿到；
+		// 此处 delete 只影响 Map 键，不影响排队中的 fn 执行；后续同 connId 新 offer
+		// 走 lazy create 路径建新 mutex（旧 mutex 队列若仍有 fn 也能跑完）。
+		// 已知边界：当 closeByConnId 是从 __handleOfferLocked 内部触发时（restart-failed catch
+		// 或首次 offer 替换旧 session），fn 仍持有 mutex；此期间新 offer 进来会创建 M2
+		// 与 M1 并发——split race 在 TODO.md 追踪，不在本修法范围闭合。
+		this.__offerMutexes.delete(connId);
 		this.__remoteLog(`rtc.closed conn=${connId}`);
 		this.logger.info?.(`${this.__rtcTag} [${connId}] closed`);
 	}
@@ -212,6 +227,46 @@ export class WebRtcPeer {
 	async __handleOffer(msg) {
 		const connId = msg.fromConnId;
 		const isIceRestart = !!msg.payload?.iceRestart;
+
+		// no-session ICE restart 不需要串行化：直接 reject，不进 mutex。
+		// 设计意图：mutex 生命期严格对齐 session（仅在有 session 时存在），
+		// 短命路径不为它建/拆 mutex。同时该路径本身就是"无 session 立即 reject"的语义，
+		// 没有任何可序列化的状态。
+		if (isIceRestart && !this.__sessions.has(connId)) {
+			const credRemain = this.__credRemainSec(msg.turnCreds);
+			const credRemainStr = credRemain ?? 'none';
+			this.__remoteLog(`rtc.ice-restart-no-session conn=${connId} credRemain=${credRemainStr}`);
+			this.logger.warn?.(`${this.__rtcTag} ICE restart from ${connId} but no session, rejecting`);
+			this.__onSend({
+				type: 'rtc:restart-rejected',
+				toConnId: connId,
+				payload: { reason: 'no_session' },
+			});
+			return;
+		}
+
+		// per-connId mutex 串行化：同 connId 几乎同时到达多条 offer（典型场景：UI 多入口
+		// nudgeRestart 在数百毫秒内连发两条 ICE restart）时，把整段三连 await + sendSignaling
+		// 串成 N 轮，最后一条胜出（plugin PC 凭据 = 最后一条 offer 凭据 = UI 当前凭据）。
+		// 不串行化时三连 await 中间被并发 offer 重入会触发 pion InvalidModificationError。
+		// 包**整个** __handleOfferLocked：既覆盖 ICE restart 路径（复用现有 PC）也覆盖首次
+		// offer 路径（创建新 PC + 触发 closeByConnId 清场），后者若不在锁内会与紧随的 ICE
+		// restart 踩。
+		// mutex 生命期 = session 生命期：与 session 一一成对管理。删除点在两处（且仅两处）：
+		// 1) closeByConnId（覆盖所有正常 close 路径：rtc:closed / state-change / TTL / closeAll）
+		// 2) __handleOfferLocked 首次 offer 的 catch（catch 手工删 session 时同步删 mutex）
+		// 任何新增 session 删除点必须配套删除 mutex 键，否则会泄漏。
+		let mu = this.__offerMutexes.get(connId);
+		if (!mu) {
+			mu = createMutex();
+			this.__offerMutexes.set(connId, mu);
+		}
+		return mu.withLock(() => this.__handleOfferLocked(msg));
+	}
+
+	async __handleOfferLocked(msg) {
+		const connId = msg.fromConnId;
+		const isIceRestart = !!msg.payload?.iceRestart;
 		const credRemain = this.__credRemainSec(msg.turnCreds);
 		const credRemainStr = credRemain ?? 'none';
 
@@ -239,6 +294,14 @@ export class WebRtcPeer {
 				this.logger.info?.(`${this.__rtcTag} ICE restart offer from ${connId}, renegotiating`);
 				try {
 					await existing.pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
+					// 身份重核：close-during-lock 路径（rtc:closed / connectionState=closed|failed-TTL /
+					// closeAll）不走 offer mutex，可能在三连 await 中间删掉 session。命中即丢弃后续动作，
+					// 不发 stale rtc:answer。logger.info 仅本地诊断，不上 remoteLog（closeByConnId 触发方
+					// 自带 rtc.closed / rtc.state 等远程日志，server 端能从那侧还原"PC 哪一刻死了"）。
+					if (this.__sessions.get(connId) !== existing) {
+						this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart aborted: session changed after setRemoteDescription`);
+						return;
+					}
 					// 重协商 SDP 可能变更 a=max-message-size，同步刷新 sender 分片阈值；
 					// queue 存的是完整字符串（buildChunks 在 sender.send 内同步完成），
 					// 已开始分片的当前消息用旧 size，下一条消息用新 size
@@ -248,7 +311,15 @@ export class WebRtcPeer {
 						if (existing.rpcDcSender) existing.rpcDcSender.maxMessageSize = newMMS;
 					}
 					const answer = await existing.pc.createAnswer();
+					if (this.__sessions.get(connId) !== existing) {
+						this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart aborted: session changed after createAnswer`);
+						return;
+					}
 					await existing.pc.setLocalDescription(answer);
+					if (this.__sessions.get(connId) !== existing) {
+						this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart aborted: session changed after setLocalDescription`);
+						return;
+					}
 					this.__onSend({
 						type: 'rtc:answer',
 						toConnId: connId,
@@ -258,6 +329,13 @@ export class WebRtcPeer {
 					this.logger.info?.(`${this.__rtcTag} ICE restart answer sent to ${connId}`);
 					return;
 				} catch (err) {
+					// 身份重核：session 已被中途关掉时 catch 收到的 err 是"PC 已 close"残响，
+					// 不应再发 stale restart-rejected（用户会看到误报失败），也不重复调 closeByConnId
+					// （session 已删，再调是 no-op 但徒增 rtc.closed 日志噪声）。
+					if (this.__sessions.get(connId) !== existing) {
+						this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart error after session change (suppressed): ${err?.message}`);
+						return;
+					}
 					// ICE restart 协商失败 → reject，不 fall through
 					this.__remoteLog(`rtc.ice-restart-failed conn=${connId} credRemain=${credRemainStr}`);
 					this.logger.warn?.(`${this.__rtcTag} ICE restart failed for ${connId}: ${err?.message}`);
@@ -546,7 +624,7 @@ export class WebRtcPeer {
 			this.__remoteLog(`rtc.answer conn=${connId}`);
 			this.logger.info?.(`${this.__rtcTag} answer sent to ${connId}`);
 		} catch (err) {
-			// SDP 协商失败 → 清理已入 Map 的 session，避免泄漏
+			// SDP 协商失败 → 清理已入 Map 的 session + mutex，避免泄漏
 			const cur = this.__sessions.get(connId);
 			if (cur && cur.pc === pc) {
 				if (cur.__failedTimer) {
@@ -555,6 +633,10 @@ export class WebRtcPeer {
 				}
 				this.__sessions.delete(connId);
 			}
+			// 同步清 mutex 键，保持 mutex 与 session 生命期一致。本 fn 即将 throw 退出，
+			// fn 仍持有的 mutex 实例引用会自然 GC；删 map 键防后续 offer 误用残留键
+			// （split race 边界仍在 TODO 中追踪，不在此修法范围）。
+			this.__offerMutexes.delete(connId);
 			await pc.close().catch(() => {});
 			throw err;
 		}