@coclaw/openclaw-coclaw 0.17.8 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.17.8",
+  "version": "0.18.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",

package/src/realtime-bridge.js

@@ -35,6 +35,13 @@ const LAG_PROBE_PERIOD_MS = 200;
 const LAG_PROBE_THRESHOLD_MS = 100;
 const LAG_PROBE_MAX_DURATION_MS = 60_000;
 
+// UI 转发 RPC 路由表条目的最大存活时间（24h）。
+// 选 24h 的理由：agent run 极端可达数小时甚至更久；正常 RPC 在终态触达前已自然清除；
+// 24h 足够覆盖几乎所有真实场景，且条目内存压力可忽略（百量级 × 几十字节）。
+const DC_REQ_TTL_MS = 24 * 60 * 60 * 1000;
+// 整表周期扫描间隔（1h）。条目存留误差 0~1h，对内存压力毫无影响。
+const DC_REQ_SCAN_MS = 60 * 60 * 1000;
+
 /**
  * 判断一个出方向 res payload 是否表示 agent RPC 进入 phase-2 终态。
  * 终态 = res 帧 + status !== 'accepted'。覆盖三种情形：
@@ -52,6 +59,19 @@ export function classifyAgentLagStop(payload) {
 	return status ?? (payload.ok === false ? 'error' : 'ok');
 }
 
+/**
+ * 判断一个 res 帧是否为终态（不会再有后续同 id 帧跟随）。
+ * 与 OpenClaw 上游 gateway/client.ts 的 `expectFinal && status === "accepted"` 判据严格镜像：
+ * 仅当 payload.status==='accepted' 时为中间态，其他一切（含无 status 字段）均为终态。
+ * 见 docs/designs/dc-rpc-response-unicast.md §2.8。
+ *
+ * @param {object} frame - 待判断的 gateway res 帧
+ * @returns {boolean}
+ */
+export function isFinalResMsg(frame) {
+	return frame?.type === 'res' && frame?.payload?.status !== 'accepted';
+}
+
 function toServerWsUrl(baseUrl, token) {
 	const url = new URL(baseUrl);
 	url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
@@ -108,6 +128,8 @@ export class RealtimeBridge {
 	 * @param {Function} [deps.resolveGatewayAuthToken] - 获取 gateway 认证 token
 	 * @param {Function} [deps.loadDeviceIdentity] - 加载设备身份
 	 * @param {number} [deps.gatewayReadyTimeoutMs] - __waitGatewayReady 默认超时（测试可注入短值）
+	 * @param {number} [deps.dcReqTtlMs] - UI 转发 RPC 路由表条目 TTL（测试可注入短值）
+	 * @param {number} [deps.dcReqScanMs] - UI 转发 RPC 路由表周期扫描间隔（测试可注入短值）
 	 */
 	constructor(deps = {}) {
 		this.__readConfig = deps.readConfig ?? readConfig;
@@ -119,6 +141,8 @@ export class RealtimeBridge {
 		this.__preloadNdc = deps.preloadNdc ?? null;
 		this.__WebSocket = deps.WebSocket; // undefined=使用 ws 包, null=禁用（测试用）, 其他=自定义实现
 		this.__gatewayReadyTimeoutMs = deps.gatewayReadyTimeoutMs ?? 1500;
+		this.__dcReqTtlMs = deps.dcReqTtlMs ?? DC_REQ_TTL_MS;
+		this.__dcReqScanMs = deps.dcReqScanMs ?? DC_REQ_SCAN_MS;
 
 		this.serverWs = null;
 		this.gatewayWs = null;
@@ -149,6 +173,10 @@ export class RealtimeBridge {
 		this.__gatewayLastReason = null;     // 最近一次失败原因（用于 gave-up 上报）
 		// agent RPC 进 in-flight 时建探针、phase-2 终态时移除：id -> { interval, timeout, stats }
 		this.__agentLagProbes = new Map();
+		// UI 转发 RPC 路由表：reqId -> { connId, expireAt }
+		// 用于 res 帧按发起方单播；查不到时回退广播兜底（兼容旧 UI / 撞号 / 上游新增中间态字符串等）
+		this.__dcPendingRequests = new Map();
+		this.__dcPendingScanTimer = null;
 	}
 
 	__resolveWebSocket() {
@@ -253,6 +281,8 @@ export class RealtimeBridge {
 			settle({ ok: false, error: 'gateway_closed' });
 		}
 		this.gatewayPendingRequests.clear();
+		// 清空 UI 转发 RPC 路由表：gateway 已断，不会再有响应回来；不主动通知 UI，由 UI 30/60s 超时兜底
+		this.__dcPendingRequests.clear();
 	}
 
 	/** 懒加载 WebRtcPeer（promise 锁防并发重复创建） */
@@ -273,8 +303,8 @@ export class RealtimeBridge {
 		this.__fileHandler.scheduleTmpCleanup(() => this.__listAgentWorkspaces());
 		this.webrtcPeer = new WebRtcPeer({
 			onSend: (msg) => this.__forwardToServer(msg),
-			onRequest: (dcPayload) => {
-				this.__handleGatewayRequestFromDc(dcPayload)
+			onRequest: (dcPayload, connId) => {
+				this.__handleGatewayRequestFromDc(dcPayload, connId)
 					.catch((err) => this.logger.warn?.(`[coclaw] dc request handler error: ${err?.message}`));
 			},
 			onFileRpc: (payload, sendFn) => {
@@ -778,7 +808,7 @@ export class RealtimeBridge {
 				return;
 			}
 			if (payload.type === 'res' || payload.type === 'event') {
-				// 过滤 gateway 的管理层广播事件，这些对 WebChat / plugin 客户端无意义：
+				// (a) 过滤 gateway 的管理层广播事件，这些对 WebChat / plugin 客户端无意义：
 				// - health: 全量状态快照（~3KB, ~60s 一次 + RPC 触发），给 Admin UI 的监控仪表盘用
 				// - tick: gateway WS 保活心跳（30s 一次），UI 隔着 DC 不需要，DC 自己有 probe 机制
 				// 不转发可避免后台时 rpc DC 队列被灌满。上游支持按需订阅前先在插件侧拦截。
@@ -786,11 +816,31 @@ export class RealtimeBridge {
 					&& (payload.event === 'health' || payload.event === 'tick')) {
 					return;
 				}
-				// agent RPC 进入 phase-2 终态时停 lag 探针（详见 classifyAgentLagStop）
+				// (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) {
+							// PC 已断 / DC 未 open / 队列拒收：本地 log 丢弃，不退回广播
+							this.__logDebug(
+								`dc res undeliverable: id=${payload.id} connId=${info.connId}`
+							);
+						}
+						return;
+					}
+				}
+				// (d) 兜底广播：覆盖 event 类型 / 映射未命中场景
 				this.webrtcPeer?.broadcast(payload);
 			}
 		});
@@ -818,6 +868,8 @@ export class RealtimeBridge {
 				settle({ ok: false, error: 'gateway_closed' });
 			}
 			this.gatewayPendingRequests.clear();
+			// 同步清空 UI 转发 RPC 路由表（同 __closeGatewayWs 语义）
+			this.__dcPendingRequests.clear();
 			// 调度下一次尝试：仅在 bridge 仍活着、未 gave-up、server WS 健康时；
 			// 其他场景（如 bridge stop、server WS 已断）由上游流程兜底，不参与 gateway 重试。
 			if (this.started && !this.__gatewayGaveUp
@@ -890,9 +942,10 @@ export class RealtimeBridge {
 		});
 	}
 
-	async __handleGatewayRequestFromDc(payload) {
+	async __handleGatewayRequestFromDc(payload, connId) {
 		const ready = await this.__waitGatewayReady();
 		if (!ready || !this.gatewayWs || this.gatewayWs.readyState !== 1) {
+			// OFFLINE 路径在写映射前触发，无脏映射；保留广播语义（属系统状态公告）
 			this.__logDebug(`gateway req drop (offline): id=${payload.id} method=${payload.method}`);
 			this.webrtcPeer?.broadcast({
 				type: 'res',
@@ -905,23 +958,41 @@ export class RealtimeBridge {
 			});
 			return;
 		}
+		// 撞号检测：UUID 全唯一时极小概率，但旧 UI 跨 tab 或 UI bug 可能触发。
+		// 删旧条目让旧响应未来走广播兜底，不主动回错给旧发起方（可能已断）
+		const id = payload.id;
+		if (typeof id === 'string' && this.__dcPendingRequests.has(id)) {
+			this.logger.warn?.(`[coclaw] duplicate dc reqId, dropping previous mapping: id=${id}`);
+			this.__dcPendingRequests.delete(id);
+		}
+		// 写映射：必须在 ready 通过后、send 之前；缺 connId 时退化为旧广播行为
+		if (typeof id === 'string' && connId) {
+			this.__dcPendingRequests.set(id, {
+				connId,
+				expireAt: Date.now() + this.__dcReqTtlMs,
+			});
+		}
 		try {
-			this.__logDebug(`gateway req -> id=${payload.id} method=${payload.method}`);
+			this.__logDebug(`gateway req -> id=${id} method=${payload.method}`);
 			this.gatewayWs.send(JSON.stringify({
 				type: 'req',
-				id: payload.id,
+				id,
 				method: payload.method,
 				params: payload.params ?? {},
 			}));
 			// 仅 agent RPC 启动 lag 探针（覆盖发送 → phase-2 终态全程）。
 			if (payload.method === 'agent') {
-				this.__startLagProbe(payload.id);
+				this.__startLagProbe(id);
 			}
 		}
 		catch {
+			// SEND_FAILED：撤回映射后广播错误响应
+			if (typeof id === 'string') {
+				this.__dcPendingRequests.delete(id);
+			}
 			this.webrtcPeer?.broadcast({
 				type: 'res',
-				id: payload.id,
+				id,
 				ok: false,
 				error: {
 					code: 'GATEWAY_SEND_FAILED',
@@ -1231,6 +1302,29 @@ export class RealtimeBridge {
 		this.logger.info?.(`[coclaw] WebRTC impl: ${implLabel}`);
 		this.logger.info?.(`[coclaw] ${this.__buildEnvLine()}`);
 		remoteLog('bridge.started');
+		// 启动 UI 转发 RPC 路由表周期扫描：1h 间隔扫描 24h 过期条目，避免长程 RPC 残留。
+		// try/catch 兜底：插件运行在 gateway 进程内，timer 回调任何同步抛出都会让进程崩溃
+		// （CLAUDE.md 禁止全局异常兜底），与 __startLagProbe 的实现保持一致。
+		this.__dcPendingScanTimer = setInterval(() => {
+			try {
+				const now = Date.now();
+				let cleaned = 0;
+				for (const [id, info] of this.__dcPendingRequests) {
+					if (info.expireAt <= now) {
+						this.__dcPendingRequests.delete(id);
+						cleaned++;
+					}
+				}
+				if (cleaned > 0) {
+					this.logger.warn?.(`[coclaw] dc pending entries expired: count=${cleaned}`);
+				}
+			}
+			/* c8 ignore next 3 -- 防御性兜底，正常路径下 Map ops + logger.warn 不抛 */
+			catch {
+				// 扫描器自身异常静默吞掉，避免拖垮 gateway。
+			}
+		}, this.__dcReqScanMs);
+		this.__dcPendingScanTimer.unref?.();
 		await this.__connectIfNeeded();
 	}
 
@@ -1276,6 +1370,11 @@ export class RealtimeBridge {
 		this.__gatewayGaveUp = false;
 		this.__gatewayLegacyMode = false;
 		this.__gatewayLastReason = null;
+		// 停止 UI 转发 RPC 路由表的周期扫描
+		if (this.__dcPendingScanTimer) {
+			clearInterval(this.__dcPendingScanTimer);
+			this.__dcPendingScanTimer = null;
+		}
 		this.__closeGatewayWs();
 		if (this.webrtcPeer) {
 			await this.webrtcPeer.closeAll().catch(() => {});

package/src/webrtc/pion-preloader.js

@@ -49,13 +49,14 @@ export async function preloadPion(deps = {}) {
 		// 启动 IPC 进程（内部会 ping 验证就绪，binary 由 pion-node 自动解析）
 		// logger 回调双打：始终走 remoteLog；同时送本地 logger，严重事件（IPC 超时、orphan 响应）
 		// 升级到 error 级别，便于本地调试时一眼可见；其他运维类消息走 info。
+		// pion-node SDK 已在 msg 中加 [pion-ipc] 前缀，此处不再重复
 		ipc = new PionIpc({
 			logger: (msg) => {
 				log(`pion.ipc ${msg}`);
 				if (SEVERE_LOG_PATTERN.test(msg)) {
-					localLogger?.error?.(`[pion-ipc] ${msg}`);
+					localLogger?.error?.(msg);
 				} else {
-					localLogger?.info?.(`[pion-ipc] ${msg}`);
+					localLogger?.info?.(msg);
 				}
 			},
 			timeout: ipcRequestTimeout,

package/src/webrtc/rpc-send-queue.js

@@ -10,6 +10,15 @@
  * - close()：DC 关闭时调用，清空队列并汇总 drop 统计
  *
  * 不做：Promise 送达保证；单条消息硬上限内的背压；自动重试。
+ *
+ * 契约（重要，修改 send/__drain/onBufferedAmountLow 时务必维持）：
+ * send/__drain/onBufferedAmountLow 必须是「总函数」——任何分支都不得抛异常给调用方。
+ * 这是上游（webrtc-peer 的 broadcast/sendTo/files sendFn）能去掉 try/catch 的前提。
+ * 队列内部所有外部调用（buildChunks、dc.send、logger.*、remoteLog 等）都必须就地保护，
+ * 失败转化为 dropped 计数 / 静默吞掉，返回 false。日志输出统一走 __safeWarn / __safeInfo /
+ * __safeRemoteLog，避免外部传入的 logger 实现自身抛异常时破坏契约。
+ * 入参防御：jsonStr 必须是 string；非 string 直接 drop，避免 Buffer.byteLength 抛 TypeError。
+ * 仅构造器允许抛（参数校验，初始化期），运行期入口都不允许。
  */
 
 import { buildChunks } from './dc-chunking.js';
@@ -64,33 +73,60 @@ export class RpcSendQueue {
 	send(jsonStr) {
 		if (this.closed || this.dc.readyState !== 'open') return false;
 
+		// 入参防御：契约要求 jsonStr 是 string；非 string 直接 drop（避免 Buffer.byteLength 抛 TypeError）
+		if (typeof jsonStr !== 'string') {
+			this.droppedCount += 1;
+			this.__safeWarn(`drop reason=non-string-input type=${typeof jsonStr}`);
+			return false;
+		}
+
 		// 诊断日志：打印每次入队的事件，跟踪 gateway 还会推哪些事件
 		// 需要时临时打开，平时保持注释避免日志噪音
-		// this.logger.info?.(`[rpc-queue${this.__tagSuffix()}] send-payload ${jsonStr}`);
+		// this.__safeInfo(`send-payload ${jsonStr}`);
+
+		// payload 字节：UTF-8 实际字节数，与对端 reassembly 上限同口径
+		const payloadBytes = Buffer.byteLength(jsonStr, 'utf8');
+
+		// 分片：异常需在 send 内吃掉，避免抛回 gateway 主循环（plugin 硬约束）
+		let chunks;
+		try {
+			chunks = buildChunks(jsonStr, this.maxMessageSize, this.getNextMsgId);
+		} catch (err) {
+			this.droppedCount += 1;
+			this.droppedBytes += payloadBytes;
+			const errMsg = err?.message ?? String(err);
+			this.__safeWarn(`drop reason=build-chunks-failed size=${payloadBytes} maxMessageSize=${this.maxMessageSize} err=${errMsg}`);
+			this.__safeRemoteLog(`rpc-queue.build-chunks-failed${this.__tagSuffix()} size=${payloadBytes} maxMessageSize=${this.maxMessageSize} err=${errMsg}`);
+			return false;
+		}
 
-		const chunks = buildChunks(jsonStr, this.maxMessageSize, this.getNextMsgId);
-		const totalBytes = chunks
+		// 帧字节：含 5 字节 header 的实际网络字节，用于队列核算
+		const frameBytes = chunks
 			? chunks.reduce((n, c) => n + c.length, 0)
-			: Buffer.byteLength(jsonStr, 'utf8');
+			: payloadBytes;
 
-		// 硬上限：单条超限
-		if (totalBytes > MAX_SINGLE_MSG_BYTES) {
+		// 硬上限：单条超限——按 payload 字节判断，对齐对端 reassembly payload 上限
+		// （帧字节因 header 累计可能在 payload 恰好不超时被误判 drop）
+		if (payloadBytes > MAX_SINGLE_MSG_BYTES) {
 			this.droppedCount += 1;
-			this.droppedBytes += totalBytes;
-			this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] drop reason=single-msg-oversize size=${totalBytes} cap=${MAX_SINGLE_MSG_BYTES}`);
+			this.droppedBytes += frameBytes;
+			this.__safeWarn(`drop reason=single-msg-oversize size=${payloadBytes} cap=${MAX_SINGLE_MSG_BYTES}`);
 			return false;
 		}
 
 		// 软上限：队列已积压到 MAX（允许之前单条溢出，但新消息从此开始拒绝）
-		if (this.queueBytes >= MAX_QUEUE_BYTES) {
+		// 白名单豁免：agent run 类 RPC 响应（顶层 type=res + payload.runId 顶层存在）
+		// 即使队列已满也强行入队，避免 UI 端因 phase-2 res 被 drop 而无法收到 run 终态。
+		// 仍受 50MB 单条硬上限约束（接收端重组上限，超过也无意义）。
+		if (this.queueBytes >= MAX_QUEUE_BYTES && !isAgentRunResponse(jsonStr)) {
 			this.droppedCount += 1;
-			this.droppedBytes += totalBytes;
+			this.droppedBytes += frameBytes;
 			// 仅状态翻转点打 log（warn + remoteLog 各一次）；overflow 持续期间所有 drop 静默累加，
 			// 避免 UI 离线 + ICE 失败导致 DC 永远不 drain 时的日志刷屏
 			if (!this.queueOverflowActive) {
 				this.queueOverflowActive = true;
-				this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] overflow-start queueBytes=${this.queueBytes}`);
-				remoteLog(`rpc-queue.overflow-start${this.__tagSuffix()} queueBytes=${this.queueBytes}`);
+				this.__safeWarn(`overflow-start queueBytes=${this.queueBytes}`);
+				this.__safeRemoteLog(`rpc-queue.overflow-start${this.__tagSuffix()} queueBytes=${this.queueBytes}`);
 			}
 			return false;
 		}
@@ -104,7 +140,7 @@ export class RpcSendQueue {
 					this.dc.send(jsonStr);
 					return true;
 				} catch (err) {
-					this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] fast-path send failed: ${err?.message}`);
+					this.__safeWarn(`fast-path send failed: ${err?.message}`);
 					return false;
 				}
 			}
@@ -125,7 +161,7 @@ export class RpcSendQueue {
 					this.dc.send(chunks[i]);
 					i += 1;
 				} catch (err) {
-					this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] fast-path send failed at chunk ${i}/${chunks.length}: ${err?.message}`);
+					this.__safeWarn(`fast-path send failed at chunk ${i}/${chunks.length}: ${err?.message}`);
 					return false;
 				}
 			}
@@ -155,7 +191,7 @@ export class RpcSendQueue {
 		this.queueBytes = 0;
 		this.queueOverflowActive = false;
 		if (this.droppedCount > 0 || residual > 0) {
-			remoteLog(`rpc-queue.close${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes} residualChunks=${residual} residualBytes=${residualBytes}`);
+			this.__safeRemoteLog(`rpc-queue.close${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes} residualChunks=${residual} residualBytes=${residualBytes}`);
 		}
 	}
 
@@ -170,7 +206,7 @@ export class RpcSendQueue {
 			try {
 				dc.send(item.data);
 			} catch (err) {
-				this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] drain send failed: ${err?.message}`);
+				this.__safeWarn(`drain send failed: ${err?.message}`);
 				return; // 保留队列，等 onclose 统一清理
 			}
 			this.queue.shift();
@@ -178,8 +214,8 @@ export class RpcSendQueue {
 			// 满 → 未满 状态转换：打一条带累计数的 log，与 overflow-start 对称
 			if (this.queueOverflowActive && this.queueBytes < MAX_QUEUE_BYTES) {
 				this.queueOverflowActive = false;
-				this.logger.info?.(`[rpc-queue${this.__tagSuffix()}] overflow-end dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`);
-				remoteLog(`rpc-queue.overflow-end${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`);
+				this.__safeInfo(`overflow-end dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`);
+				this.__safeRemoteLog(`rpc-queue.overflow-end${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`);
 			}
 		}
 	}
@@ -188,4 +224,48 @@ export class RpcSendQueue {
 	__tagSuffix() {
 		return this.tag ? ` ${this.tag}` : '';
 	}
+
+	/**
+	 * @private logger.warn 安全包装：吃掉 logger 自身抛的异常，保护 send/__drain 的 no-throw 契约
+	 * @param {string} msg
+	 */
+	__safeWarn(msg) {
+		try { this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了也不能让 send 抛 */ }
+	}
+
+	/** @private 同 __safeWarn，info 级别 */
+	__safeInfo(msg) {
+		try { this.logger.info?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了也不能让 send 抛 */ }
+	}
+
+	/**
+	 * @private remoteLog 安全包装。
+	 * 当前 `remoteLog` 实现同步路径仅做数组操作 + flush().catch()，不抛异常，本 catch 块覆盖率因此为 0。
+	 * 保留 try/catch 是为了让"send 不抛"契约不依赖 remoteLog 模块的具体实现——如果未来 remoteLog
+	 * 内部加入可能抛的同步路径（如序列化、外部 sink 注入），此 wrapper 仍能兜底。
+	 */
+	__safeRemoteLog(text) {
+		try { remoteLog(text); } catch { /* 未来防御：见上方注释 */ }
+	}
+}
+
+/**
+ * 判断一条 JSON 字符串是否为带 runId 的 RPC 响应（用于队列满时白名单豁免）。
+ *
+ * 命中条件（仅看顶层）：`type === 'res'` 且 `payload.runId` 为 truthy。
+ * 设计取舍：硬编码识别、不维护方法白名单表。该条件主要为覆盖 OpenClaw `agent` 二阶段 res
+ * 与 `agent.wait` 全部分支（accepted/ok/error/timeout/race/dedupe）；同时也会顺带豁免
+ * `chat.send` 等其他顶层带 `runId` 的响应——这类 rsp 极小，加白无副作用。
+ * 解析失败或不命中按非白名单处理。
+ *
+ * @param {string} jsonStr - 待发送的 RPC 帧 JSON 字符串
+ * @returns {boolean} 命中白名单返回 true；解析失败或不命中返回 false
+ */
+function isAgentRunResponse(jsonStr) {
+	try {
+		const parsed = JSON.parse(jsonStr);
+		return parsed?.type === 'res' && Boolean(parsed?.payload?.runId);
+	} catch {
+		return false;
+	}
 }

package/src/webrtc/webrtc-peer.js

@@ -110,39 +110,44 @@ export class WebRtcPeer {
 
 	/** 向所有已打开的 rpcChannel 广播（大消息自动分片，经由 RpcSendQueue 流控） */
 	broadcast(payload) {
-		const jsonStr = JSON.stringify(payload);
-		for (const [connId, session] of this.__sessions) {
+		let jsonStr;
+		try {
+			jsonStr = JSON.stringify(payload);
+		} catch (err) {
+			// 循环引用 / BigInt 等导致 stringify 抛——记日志后整条丢弃，不冒到 gateway
+			this.__logDebug(`broadcast stringify failed: ${err?.message}`);
+			return;
+		}
+		if (typeof jsonStr !== 'string') return; // payload 是 undefined/symbol 时 stringify 返回 undefined
+		for (const session of this.__sessions.values()) {
 			const q = session.rpcSendQueue;
 			if (q && session.rpcChannel?.readyState === 'open') {
-				try {
-					q.send(jsonStr);
-				} catch (err) {
-					// buildChunks 抛（maxMessageSize 配置错）等罕见情况
-					this.__logDebug(`[${connId}] broadcast send failed: ${err.message}`);
-				}
+				q.send(jsonStr);
 			}
 		}
 	}
 
 	/**
 	 * 向指定 connId 的 rpc DC 单播一个 JSON 帧（不走 server 中转）。
-	 * 若 session/DC 未就绪返回 false，由调用方决定是否重试。
+	 * 若 session/DC 未就绪或被发送队列拒收（队列满等）返回 false，由调用方决定是否重试。
 	 * @param {string} connId
 	 * @param {object} payload - 完整的 JSON 帧（通常是 { type: 'event', event, payload }）
-	 * @returns {boolean} true=已入队发送，false=未能发送（session 不存在 / DC 未 open）
+	 * @returns {boolean} true=已入队发送；false=session 不存在 / DC 未 open / payload 不可序列化 / 发送队列拒收
 	 */
 	sendTo(connId, payload) {
 		const session = this.__sessions.get(connId);
 		if (!session) return false;
 		const q = session.rpcSendQueue;
 		if (!q || session.rpcChannel?.readyState !== 'open') return false;
+		let jsonStr;
 		try {
-			q.send(JSON.stringify(payload));
-			return true;
+			jsonStr = JSON.stringify(payload);
 		} catch (err) {
-			this.__logDebug(`[${connId}] sendTo failed: ${err.message}`);
+			this.__logDebug(`[${connId}] sendTo stringify failed: ${err?.message}`);
 			return false;
 		}
+		if (typeof jsonStr !== 'string') return false;
+		return q.send(jsonStr);
 	}
 
 	async __handleOffer(msg) {
@@ -520,11 +525,15 @@ export class WebRtcPeer {
 				if (payload.method?.startsWith('coclaw.files.') && this.__onFileRpc) {
 					const sess = this.__sessions.get(connId);
 					const sendFn = (response) => {
+						let jsonStr;
 						try {
-							sess?.rpcSendQueue?.send(JSON.stringify(response));
+							jsonStr = JSON.stringify(response);
 						} catch (err) {
-							this.__logDebug(`[${connId}] sendFn failed: ${err.message}`);
+							this.__logDebug(`[${connId}] file sendFn stringify failed: ${err?.message}`);
+							return;
 						}
+						if (typeof jsonStr !== 'string') return;
+						sess?.rpcSendQueue?.send(jsonStr);
 					};
 					this.__onFileRpc(payload, sendFn, connId);
 				} else {
@@ -769,9 +778,9 @@ export class WebRtcPeer {
 	}
 
 	__logDebug(message) {
-		if (typeof this.logger?.debug === 'function') {
-			this.logger.debug(`${this.__rtcTag} ${message}`);
-		}
+		if (typeof this.logger?.debug !== 'function') return;
+		try { this.logger.debug(`${this.__rtcTag} ${message}`); }
+		catch { /* 上层（broadcast / sendTo / sendFn 等的 stringify catch）依赖 __logDebug 不抛 */ }
 	}
 }