@coclaw/openclaw-coclaw 0.18.0 → 0.19.2

package/src/realtime-bridge.js

@@ -44,10 +44,12 @@ const DC_REQ_SCAN_MS = 60 * 60 * 1000;
 
 /**
  * 判断一个出方向 res payload 是否表示 agent RPC 进入 phase-2 终态。
- * 终态 = res 帧 + status !== 'accepted'。覆盖三种情形：
+ * 终态 = res 帧 + status !== 'accepted'。OpenClaw 上游可能下发的终态 status：
  * - status='ok'：成功
  * - status='error'：执行失败
+ * - status='timeout'：上游 agent.wait 等待 runId 终态超时（含 dedupe 命中的 timeout 快照）
  * - 参数校验失败：ok=false 且无 status（协议文档"特殊情况"）
+ * 仅做兜底分类，不再追求枚举完备——上游若新增其他 non-accepted status，原样作为 reason 返回。
  *
  * @param {object} payload - 待判断的消息
  * @returns {string | null} 终态时返回 lag.summary 的 reason 字符串，否则 null
@@ -265,6 +267,8 @@ export class RealtimeBridge {
 			this.__gatewayRetryTimer = null;
 		}
 		this.__gatewayAttempts = 0;
+		// 主动关闭时立即清 lag probe，不依赖 close 事件回调时序，避免 close 事件延迟期间 probe 误报
+		this.__clearAllLagProbes();
 		if (!this.gatewayWs) {
 			return;
 		}
@@ -381,7 +385,8 @@ export class RealtimeBridge {
 	 * 两阶段 agent RPC：发送请求后等待 accepted 再等待最终响应。
 	 * agent() RPC 返回两次响应（同一 id）：
 	 *   1. { status: "accepted", runId }
-	 *   2. { status: "ok", result: { payloads: [{ text }] } }
+	 *   2. 终态帧，status 取值见 classifyAgentLagStop 注释（ok/error/timeout/参数校验失败）；
+	 *      其中 status='ok' 时附带 result.payloads，其余分支可能没有 result。
 	 *
 	 * @param {string} method - RPC 方法名（通常为 'agent'）
 	 * @param {object} params - RPC 参数
@@ -727,122 +732,137 @@ export class RealtimeBridge {
 		let wasReady = false;               // 本 WS 曾经握手成功（区分"握手失败"与"成功后断开"）
 		let lastChallengeNonce = '';        // 最近一次 challenge 的 nonce，legacy 回退时复用
 
+		// 注意：listener 用 sync wrapper + IIFE.catch 形式，避免 async listener 抛出的
+		// promise 变 unhandledRejection 击穿 gateway 进程。await sendTo / settle / broadcast
+		// 等路径若抛错必须在此兜底。
 		ws.addEventListener('message', (event) => {
-			let payload = null;
-			try {
-				payload = JSON.parse(String(event.data ?? '{}'));
-			}
-			catch {
-				return;
-			}
-			if (!payload || typeof payload !== 'object') {
-				return;
-			}
-			if (payload.type === 'event' && payload.event === 'connect.challenge') {
-				const nonce = payload?.payload?.nonce ?? '';
-				lastChallengeNonce = nonce;
-				this.__logDebug(`gateway event <- connect.challenge legacyMode=${this.__gatewayLegacyMode}`);
-				// 已经学到此 gateway 是 legacy（上一条 WS 回退过）→ 直接发 legacy 握手
-				if (this.__gatewayLegacyMode) {
-					pendingLegacyAttempted = true;
-					this.__sendGatewayConnectRequest(ws, nonce, { legacy: true });
+			(async () => {
+				// stale guard：与 server sock open/message 已加的 guard 对称。
+				// 旧 gateway ws 关闭后若仍有迟到的 message（connect.challenge / res / event），
+				// 处理路径会写 this.gatewayConnectReqId / this.gatewayReady / 转发 res 等共享状态，
+				// 污染当前 ws 的握手或路由
+				if (this.gatewayWs !== ws) {
+					return;
 				}
-				else {
-					this.__sendGatewayConnectRequest(ws, nonce);
+				let payload = null;
+				try {
+					payload = JSON.parse(String(event.data ?? '{}'));
 				}
-				return;
-			}
-			if (payload.type === 'res' && this.gatewayConnectReqId && payload.id === this.gatewayConnectReqId) {
-				if (payload.ok === true) {
-					this.gatewayReady = true;
-					wasReady = true;
-					this.__gatewayAttempts = 0; // 成功握手 → 重置失败计数，让后续瞬态断开有完整重试预算
-					remoteLog('ws.connected peer=gateway');
-					this.__logDebug(`gateway connect ok <- id=${payload.id}`);
-					this.gatewayConnectReqId = null;
-					this.__ensureSessionsPromise = this.__ensureAllAgentSessions();
-					this.__pushInstanceInfo();
+				catch {
+					return;
+				}
+				if (!payload || typeof payload !== 'object') {
+					return;
 				}
-				else {
-					const reason = payload?.error?.message ?? 'unknown';
-					// v3 → legacy 同 WS 回退：仅在签名/协议相关错误、且本 WS 尚未尝试 legacy 时触发
-					const shouldFallback =
+				if (payload.type === 'event' && payload.event === 'connect.challenge') {
+					const nonce = payload?.payload?.nonce ?? '';
+					lastChallengeNonce = nonce;
+					this.__logDebug(`gateway event <- connect.challenge legacyMode=${this.__gatewayLegacyMode}`);
+					// 已经学到此 gateway 是 legacy（上一条 WS 回退过）→ 直接发 legacy 握手
+					if (this.__gatewayLegacyMode) {
+						pendingLegacyAttempted = true;
+						this.__sendGatewayConnectRequest(ws, nonce, { legacy: true });
+					}
+					else {
+						this.__sendGatewayConnectRequest(ws, nonce);
+					}
+					return;
+				}
+				if (payload.type === 'res' && this.gatewayConnectReqId && payload.id === this.gatewayConnectReqId) {
+					if (payload.ok === true) {
+						this.gatewayReady = true;
+						wasReady = true;
+						this.__gatewayAttempts = 0; // 成功握手 → 重置失败计数，让后续瞬态断开有完整重试预算
+						remoteLog('ws.connected peer=gateway');
+						this.__logDebug(`gateway connect ok <- id=${payload.id}`);
+						this.gatewayConnectReqId = null;
+						this.__ensureSessionsPromise = this.__ensureAllAgentSessions();
+						this.__pushInstanceInfo();
+					}
+					else {
+						const reason = payload?.error?.message ?? 'unknown';
+						// v3 → legacy 同 WS 回退：仅在签名/协议相关错误、且本 WS 尚未尝试 legacy 时触发
+						const shouldFallback =
 						!pendingLegacyAttempted
 						&& !this.__gatewayLegacyMode
 						&& GATEWAY_HANDSHAKE_FALLBACK_PATTERN.test(reason);
-					if (shouldFallback) {
-						pendingLegacyAttempted = true;
-						this.__gatewayLegacyMode = true;
-						// v3 的失败原因已由这条 remoteLog 单独上报，不写入 __gatewayLastReason；
-						// 后者保持"最后一次真正失败的原因"语义，供 gave-up 时使用。
-						remoteLog(`gateway.handshake.fallback v3→legacy reason=${reason}`);
-						this.logger.info?.(`[coclaw] gateway v3 handshake failed (${reason}), falling back to legacy`);
-						this.__sendGatewayConnectRequest(ws, lastChallengeNonce, { legacy: true });
+						if (shouldFallback) {
+							pendingLegacyAttempted = true;
+							this.__gatewayLegacyMode = true;
+							// v3 的失败原因已由这条 remoteLog 单独上报，不写入 __gatewayLastReason；
+							// 后者保持"最后一次真正失败的原因"语义，供 gave-up 时使用。
+							remoteLog(`gateway.handshake.fallback v3→legacy reason=${reason}`);
+							this.logger.info?.(`[coclaw] gateway v3 handshake failed (${reason}), falling back to legacy`);
+							this.__sendGatewayConnectRequest(ws, lastChallengeNonce, { legacy: true });
+							return;
+						}
+						this.gatewayReady = false;
+						this.gatewayConnectReqId = null;
+						connectFailReported = true;
+						this.__gatewayLastReason = reason;
+						remoteLog(`ws.connect-failed peer=gateway msg=${reason}`);
+						this.logger.warn?.(`[coclaw] gateway connect failed: ${reason}`);
+						try { ws.close(1008, 'gateway_connect_failed'); }
+						/* c8 ignore next */
+						catch {}
+					}
+					return;
+				}
+				if (payload.type === 'res' && typeof payload.id === 'string') {
+					const settle = this.gatewayPendingRequests.get(payload.id);
+					if (settle) {
+						settle({
+							ok: payload.ok === true,
+							response: payload,
+							error: payload?.error?.message ?? payload?.error?.code,
+						});
 						return;
 					}
-					this.gatewayReady = false;
-					this.gatewayConnectReqId = null;
-					connectFailReported = true;
-					this.__gatewayLastReason = reason;
-					remoteLog(`ws.connect-failed peer=gateway msg=${reason}`);
-					this.logger.warn?.(`[coclaw] gateway connect failed: ${reason}`);
-					try { ws.close(1008, 'gateway_connect_failed'); }
-					/* c8 ignore next */
-					catch {}
 				}
-				return;
-			}
-			if (payload.type === 'res' && typeof payload.id === 'string') {
-				const settle = this.gatewayPendingRequests.get(payload.id);
-				if (settle) {
-					settle({
-						ok: payload.ok === true,
-						response: payload,
-						error: payload?.error?.message ?? payload?.error?.code,
-					});
+				/* c8 ignore next 3 -- connect 完成前的消息过滤 */
+				if (!this.gatewayReady) {
 					return;
 				}
-			}
-			/* c8 ignore next 3 -- connect 完成前的消息过滤 */
-			if (!this.gatewayReady) {
-				return;
-			}
-			if (payload.type === 'res' || payload.type === 'event') {
+				if (payload.type === 'res' || payload.type === 'event') {
 				// (a) 过滤 gateway 的管理层广播事件，这些对 WebChat / plugin 客户端无意义：
 				// - health: 全量状态快照（~3KB, ~60s 一次 + RPC 触发），给 Admin UI 的监控仪表盘用
 				// - tick: gateway WS 保活心跳（30s 一次），UI 隔着 DC 不需要，DC 自己有 probe 机制
 				// 不转发可避免后台时 rpc DC 队列被灌满。上游支持按需订阅前先在插件侧拦截。
-				if (payload.type === 'event'
+					if (payload.type === 'event'
 					&& (payload.event === 'health' || payload.event === 'tick')) {
-					return;
-				}
-				// (b) agent RPC 进入 phase-2 终态时停 lag 探针（必须放在 (c) 单播分支之前，
-				// 避免命中后探针不停导致 60s 兜底 + 噪声日志）
-				const lagReason = classifyAgentLagStop(payload);
-				if (lagReason !== null) {
-					this.__stopLagProbe(payload.id, lagReason);
-				}
-				// (c) UI 转发 RPC 的 res 单播：按 reqId 查路由表，命中则定向 sendTo
-				if (payload.type === 'res' && typeof payload.id === 'string') {
-					const info = this.__dcPendingRequests.get(payload.id);
-					if (info) {
+						return;
+					}
+					// (b) agent RPC 进入 phase-2 终态时停 lag 探针（必须放在 (c) 单播分支之前，
+					// 避免命中后探针不停导致 60s 兜底 + 噪声日志）
+					const lagReason = classifyAgentLagStop(payload);
+					if (lagReason !== null) {
+						this.__stopLagProbe(payload.id, lagReason);
+					}
+					// (c) UI 转发 RPC 的 res 单播：按 reqId 查路由表，命中则定向 sendTo
+					if (payload.type === 'res' && typeof payload.id === 'string') {
+						const info = this.__dcPendingRequests.get(payload.id);
+						if (info) {
 						// 终态才清条目；accepted 类中间态保留等下一帧
-						if (isFinalResMsg(payload)) {
-							this.__dcPendingRequests.delete(payload.id);
-						}
-						const delivered = this.webrtcPeer?.sendTo(info.connId, payload);
-						if (!delivered) {
+							if (isFinalResMsg(payload)) {
+								this.__dcPendingRequests.delete(payload.id);
+							}
+							// sendTo 阶段 1 改为 async（admission 决策 await）；外层 listener 已是 async
+							const delivered = await this.webrtcPeer?.sendTo(info.connId, payload);
+							if (!delivered) {
 							// PC 已断 / DC 未 open / 队列拒收：本地 log 丢弃，不退回广播
-							this.__logDebug(
-								`dc res undeliverable: id=${payload.id} connId=${info.connId}`
-							);
+								this.__logDebug(
+									`dc res undeliverable: id=${payload.id} connId=${info.connId}`
+								);
+							}
+							return;
 						}
-						return;
 					}
+					// (d) 兜底广播：覆盖 event 类型 / 映射未命中场景
+					this.webrtcPeer?.broadcast(payload);
 				}
-				// (d) 兜底广播：覆盖 event 类型 / 映射未命中场景
-				this.webrtcPeer?.broadcast(payload);
-			}
+			})().catch((err) => {
+				this.logger.warn?.(`[coclaw] gateway ws message handler error: ${err?.message ?? err}`);
+			});
 		});
 
 		ws.addEventListener('open', () => {
@@ -850,19 +870,23 @@ export class RealtimeBridge {
 		});
 		ws.addEventListener('close', (ev) => {
 			// 握手失败路径已经打过 ws.connect-failed，这里抑制重复的 disconnected 日志；
-			// 成功后的意外断开、握手途中的异常断开仍按原样上报。
+			// 成功后的意外断开、握手途中的异常断开仍按原样上报。per-WS log 用闭包局部
+			// connectFailReported，无需身份校验
 			if (!connectFailReported) {
 				remoteLog(`ws.disconnected peer=gateway code=${ev?.code ?? '?'}`);
 			}
 			this.logger.info?.(`[coclaw] gateway ws closed (code=${ev?.code ?? '?'} reason=${ev?.reason ?? 'n/a'})`);
+			// stale guard：旧 ws 的迟到 close 不应清新 ws 的 lag probes / pending requests / DC 路由 /
+			// 也不应触发新一轮重试调度。非当前 ws → 直接早返，仅留 per-WS 日志。
+			if (this.gatewayWs !== ws) {
+				return;
+			}
 			// gateway WS 一断，正在跑的 agent RPC 不会再有 phase-2 res，主动结算所有 lag 探针，
 			// 避免它们空跑到 60s 兜底，期间还会持续打 spike 噪声。
 			this.__clearAllLagProbes();
-			if (this.gatewayWs === ws) {
-				this.gatewayWs = null;
-				this.gatewayReady = false;
-				this.gatewayConnectReqId = null;
-			}
+			this.gatewayWs = null;
+			this.gatewayReady = false;
+			this.gatewayConnectReqId = null;
 			/* c8 ignore next 3 -- gateway 意外断开时结算未完成 RPC，避免等超时 */
 			for (const [, settle] of this.gatewayPendingRequests) {
 				settle({ ok: false, error: 'gateway_closed' });
@@ -943,6 +967,24 @@ export class RealtimeBridge {
 	}
 
 	async __handleGatewayRequestFromDc(payload, connId) {
+		// 入口校验：peer 可能发出残缺 / 类型错误的帧；不应向 gateway 转发 id/method 缺失的请求
+		const hasValidId = typeof payload?.id === 'string' && payload.id.length > 0;
+		const hasValidMethod = typeof payload?.method === 'string' && payload.method.length > 0;
+		if (!hasValidId || !hasValidMethod) {
+			this.logger.warn?.(
+				`[coclaw] dc gateway req invalid: id=${typeof payload?.id} method=${typeof payload?.method}`,
+			);
+			// 有合法 id 时回 INVALID_REQUEST 让发起方尽快放弃等待；id 不合法时只能 drop
+			if (hasValidId) {
+				this.webrtcPeer?.broadcast({
+					type: 'res',
+					id: payload.id,
+					ok: false,
+					error: { code: 'INVALID_REQUEST', message: 'missing or invalid id/method' },
+				});
+			}
+			return;
+		}
 		const ready = await this.__waitGatewayReady();
 		if (!ready || !this.gatewayWs || this.gatewayWs.readyState !== 1) {
 			// OFFLINE 路径在写映射前触发，无脏映射；保留广播语义（属系统状态公告）
@@ -1133,6 +1175,11 @@ export class RealtimeBridge {
 		this.connectTimer.unref?.();
 
 		sock.addEventListener('open', () => {
+			// 旧 sock 迟到的 open 不应接管当前会话：避免在 reconnect 后旧 sock 再注入 sender / 重置心跳，
+			// 对称于 close handler 的 sock !== this.serverWs guard
+			if (this.serverWs !== sock || this.intentionallyClosed) {
+				return;
+			}
 			this.__clearConnectTimer();
 			this.logger.info?.(`[coclaw] realtime bridge connected: ${maskedTarget}`);
 			remoteLog('ws.connected peer=server');
@@ -1149,6 +1196,10 @@ export class RealtimeBridge {
 		});
 
 		sock.addEventListener('message', async (event) => {
+			// 旧 sock 迟到的 message 不应重置当前 sock 的心跳节奏；同 open 路径处理
+			if (this.serverWs !== sock || this.intentionallyClosed) {
+				return;
+			}
 			this.__resetServerHbTimeout(sock);
 			try {
 				const payload = JSON.parse(String(event.data ?? '{}'));
@@ -1183,12 +1234,14 @@ export class RealtimeBridge {
 		});
 
 		sock.addEventListener('close', async (event) => {
-			this.__clearServerHeartbeat();
-			this.__clearConnectTimer();
-			// 若 serverWs 已指向新实例（如 refresh 后），跳过旧 sock 的清理
+			// 若 serverWs 已指向新实例（如 refresh 后），跳过旧 sock 的清理。
+			// __clearServerHeartbeat / __clearConnectTimer 都是 per-bridge 全局单槽，
+			// 旧 sock close 若跑在 guard 前会清掉新 sock 的 heartbeat
 			if (this.serverWs !== null && this.serverWs !== sock) {
 				return;
 			}
+			this.__clearServerHeartbeat();
+			this.__clearConnectTimer();
 			setRemoteLogSender(null);
 			const wasIntentional = this.intentionallyClosed;
 			this.serverWs = null;

package/src/utils/atomic-write.js

@@ -7,6 +7,7 @@
 
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
+import nodeFs from 'node:fs';
 import nodePath from 'node:path';
 
 /**
@@ -60,4 +61,39 @@ async function atomicWriteJsonFile(filePath, value, opts) {
 	await atomicWriteFile(filePath, text, opts);
 }
 
-export { atomicWriteFile, atomicWriteJsonFile };
+/**
+ * 同步版 atomicWriteFile：仅供 device-identity 等启动期同步路径使用，
+ * 行为与 atomicWriteFile 等价（write-to-tmp + rename + finally cleanup）。
+ *
+ * @param {string} filePath - 目标文件路径
+ * @param {string | Buffer} content - 文件内容
+ * @param {object} [opts]
+ * @param {number} [opts.mode=0o600] - 文件权限
+ * @param {number} [opts.dirMode] - 父目录权限
+ * @param {string} [opts.encoding='utf8'] - 写入编码
+ */
+function atomicWriteFileSync(filePath, content, opts) {
+	const mode = opts?.mode ?? 0o600;
+	const encoding = opts?.encoding ?? 'utf8';
+	const mkdirOpts = { recursive: true };
+	if (opts?.dirMode != null) {
+		mkdirOpts.mode = opts.dirMode;
+	}
+
+	nodeFs.mkdirSync(nodePath.dirname(filePath), mkdirOpts);
+
+	const tmp = `${filePath}.${randomUUID()}.tmp`;
+	try {
+		nodeFs.writeFileSync(tmp, content, { encoding, mode });
+		/* c8 ignore next -- chmod 在正常文件系统上不会失败 */
+		try { nodeFs.chmodSync(tmp, mode); } catch { /* ignore */ }
+		nodeFs.renameSync(tmp, filePath);
+		/* c8 ignore next -- chmod 在正常文件系统上不会失败 */
+		try { nodeFs.chmodSync(filePath, mode); } catch { /* ignore */ }
+	} finally {
+		// 确保临时文件不残留（rename 成功后 tmp 已不存在，rmSync force=true 会无声忽略）
+		try { nodeFs.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+	}
+}
+
+export { atomicWriteFile, atomicWriteJsonFile, atomicWriteFileSync };