@coclaw/openclaw-coclaw 0.17.6 → 0.17.9

package/index.js

@@ -125,11 +125,34 @@ function respondError(respond, err) {
 function respondInvalid(respond, message) {
 	respond(false, undefined, { code: 'INVALID_INPUT', message });
 }
+/* c8 ignore stop */
+
 const plugin = {
 	id: 'openclaw-coclaw',
 	name: 'CoClaw',
 	description: 'OpenClaw CoClaw channel plugin for remote chat',
 	register(api) {
+		// 按 OpenClaw SDK 入口模式分叉（参照 defineChannelPluginEntry，见上游 plugin-sdk/core.ts 的
+		// defineChannelPluginEntry 实现 与 docs/plugins/sdk-entrypoints.md）：
+		// - cli-metadata 模式：仅声明根命令名供根 CLI 解析使用
+		// - 其他模式：注册 channel + CLI 元信息（discovery 下两者由 captured-registration 采集）
+		// - 仅 full 模式跑完整副作用（service / RPC / hook / command / managers / 磁盘 IO）
+		//
+		// 与上游 helper 的刻意偏差：上游 helper 在所有非 cli-metadata 模式下都调
+		// setRuntime?.(api.runtime)，但 discovery 传入的 api.runtime 是空对象 {}，每 14s
+		// 一次会把全局 runtime 单例擦掉。本实现把 setRuntime 严格限定在 full 模式，避免擦除。
+		const mode = api.registrationMode;
+		if (mode === 'cli-metadata') {
+			api.registerCli(registerCoclawCli, { commands: ['coclaw'] });
+			return;
+		}
+		api.registerChannel({ plugin: coclawChannelPlugin });
+		api.registerCli(registerCoclawCli, { commands: ['coclaw'] });
+		// 本插件 package.json 无 setupEntry，setup-only/setup-runtime 实际不会到达主 register；
+		// 保留兜底防御上游模型变化。`mode !== 'full'` 也覆盖 discovery（每 14s 一次）
+		if (mode !== 'full') return;
+
+		/* c8 ignore start */
 		setRuntime(api.runtime);
 		const logger = api?.logger ?? console;
 		installAbortRegistryDiag(logger);
@@ -145,8 +168,6 @@ const plugin = {
 			logger.warn?.(`[coclaw] chat history manager load failed: ${String(err?.message ?? err)}`);
 		});
 
-		api.registerChannel({ plugin: coclawChannelPlugin });
-
 		// 追踪 chat 因 reset 产生的孤儿 session
 		if (typeof api.on === 'function') {
 			api.on('session_start', async (event, ctx) => {
@@ -622,8 +643,6 @@ const plugin = {
 			stop() { scheduler.stop(); },
 		});
 
-		api.registerCli(registerCoclawCli, { commands: ['coclaw'] });
-
 		api.registerCommand({
 			name: 'coclaw',
 			description: 'CoClaw bind/unbind command',

package/package.json

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

package/src/realtime-bridge.js

@@ -29,6 +29,29 @@ const GATEWAY_RETRY_DELAYS_MS = [5_000, 10_000, 20_000, 20_000, 20_000];
 // 严格限定在"签名/设备/scope/协议"相关错误，避免对网络/内部错误做无意义的降级尝试。
 const GATEWAY_HANDSHAKE_FALLBACK_PATTERN = /signature|device|scope|protocol/i;
 
+// agent run 期间用的 event loop lag 探针参数：每 200ms 测一次主线程漂移，>100ms 视为 spike。
+// 上限 60s 兜底，正常会在 phase-2 终态时主动停。用于持续观测 OpenClaw gateway 主线程被同步代码阻塞。
+const LAG_PROBE_PERIOD_MS = 200;
+const LAG_PROBE_THRESHOLD_MS = 100;
+const LAG_PROBE_MAX_DURATION_MS = 60_000;
+
+/**
+ * 判断一个出方向 res payload 是否表示 agent RPC 进入 phase-2 终态。
+ * 终态 = res 帧 + status !== 'accepted'。覆盖三种情形：
+ * - status='ok'：成功
+ * - status='error'：执行失败
+ * - 参数校验失败：ok=false 且无 status（协议文档"特殊情况"）
+ *
+ * @param {object} payload - 待判断的消息
+ * @returns {string | null} 终态时返回 lag.summary 的 reason 字符串，否则 null
+ */
+export function classifyAgentLagStop(payload) {
+	if (payload?.type !== 'res' || typeof payload?.id !== 'string') return null;
+	const status = payload?.payload?.status;
+	if (status === 'accepted') return null;
+	return status ?? (payload.ok === false ? 'error' : 'ok');
+}
+
 function toServerWsUrl(baseUrl, token) {
 	const url = new URL(baseUrl);
 	url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
@@ -124,6 +147,8 @@ export class RealtimeBridge {
 		this.__gatewayGaveUp = false;        // 重试次数耗尽 → 终态，不再自动尝试
 		this.__gatewayLegacyMode = false;    // 学到"本 gateway 不接受带 device 的 v3"
 		this.__gatewayLastReason = null;     // 最近一次失败原因（用于 gave-up 上报）
+		// agent RPC 进 in-flight 时建探针、phase-2 终态时移除：id -> { interval, timeout, stats }
+		this.__agentLagProbes = new Map();
 	}
 
 	__resolveWebSocket() {
@@ -761,6 +786,11 @@ export class RealtimeBridge {
 					&& (payload.event === 'health' || payload.event === 'tick')) {
 					return;
 				}
+				// agent RPC 进入 phase-2 终态时停 lag 探针（详见 classifyAgentLagStop）
+				const lagReason = classifyAgentLagStop(payload);
+				if (lagReason !== null) {
+					this.__stopLagProbe(payload.id, lagReason);
+				}
 				this.webrtcPeer?.broadcast(payload);
 			}
 		});
@@ -775,6 +805,9 @@ export class RealtimeBridge {
 				remoteLog(`ws.disconnected peer=gateway code=${ev?.code ?? '?'}`);
 			}
 			this.logger.info?.(`[coclaw] gateway ws closed (code=${ev?.code ?? '?'} reason=${ev?.reason ?? 'n/a'})`);
+			// gateway WS 一断，正在跑的 agent RPC 不会再有 phase-2 res，主动结算所有 lag 探针，
+			// 避免它们空跑到 60s 兜底，期间还会持续打 spike 噪声。
+			this.__clearAllLagProbes();
 			if (this.gatewayWs === ws) {
 				this.gatewayWs = null;
 				this.gatewayReady = false;
@@ -880,6 +913,10 @@ export class RealtimeBridge {
 				method: payload.method,
 				params: payload.params ?? {},
 			}));
+			// 仅 agent RPC 启动 lag 探针（覆盖发送 → phase-2 终态全程）。
+			if (payload.method === 'agent') {
+				this.__startLagProbe(payload.id);
+			}
 		}
 		catch {
 			this.webrtcPeer?.broadcast({
@@ -902,6 +939,66 @@ export class RealtimeBridge {
 		this.connectTimer = null;
 	}
 
+	// agent run 期间监测 gateway 主线程是否被同步代码阻塞。
+	// 设计动机：上游 OpenClaw 同步路径上有重活（详见 docs/openclaw-upstream-issues.md），
+	// 修复前作为持续诊断信号保留——主线程一旦被同步阻塞，agent send 路径会出现几十秒的卡顿。
+	//
+	// 异常隔离：插件运行在 gateway 进程内，timer 回调任何同步抛出都会让进程崩溃
+	// （CLAUDE.md 第 123 行明确禁止全局异常兜底），因此 interval/timeout 回调都用 try/catch 局部包裹。
+	__startLagProbe(id) {
+		if (this.__agentLagProbes.has(id)) return;
+		let lastTick = Date.now();
+		const stats = { ticks: 0, max: 0, sumOver: 0, over: 0, startedAt: lastTick };
+		const interval = setInterval(() => {
+			try {
+				const now = Date.now();
+				const lag = now - lastTick - LAG_PROBE_PERIOD_MS;
+				lastTick = now;
+				stats.ticks += 1;
+				if (lag > stats.max) stats.max = lag;
+				if (lag > LAG_PROBE_THRESHOLD_MS) {
+					stats.over += 1;
+					stats.sumOver += lag;
+					this.logger.warn?.(`[coclaw] lag.spike id=${id} +${lag}ms`);
+				}
+			}
+			catch {
+				// 探针自身异常静默吞掉，避免拖垮 gateway。
+			}
+		}, LAG_PROBE_PERIOD_MS);
+		interval.unref?.();
+		const timeout = setTimeout(() => this.__stopLagProbe(id, 'timeout'), LAG_PROBE_MAX_DURATION_MS);
+		timeout.unref?.();
+		this.__agentLagProbes.set(id, { interval, timeout, stats });
+		// lag.start 日志即便抛异常也不能影响调用方（在 __handleGatewayRequestFromDc 的 try/catch 内，
+		// 抛出会被误判为 send 失败 → 错发 GATEWAY_SEND_FAILED）。
+		try { this.logger.info?.(`[coclaw] lag.start id=${id}`); }
+		catch { /* 诊断日志失败不影响主流程 */ }
+	}
+
+	__stopLagProbe(id, reason) {
+		const probe = this.__agentLagProbes.get(id);
+		if (!probe) return;
+		clearInterval(probe.interval);
+		clearTimeout(probe.timeout);
+		this.__agentLagProbes.delete(id);
+		try {
+			const stats = probe.stats;
+			const dur = Date.now() - stats.startedAt;
+			this.logger.info?.(`[coclaw] lag.summary id=${id} reason=${reason} dur=${dur}ms ticks=${stats.ticks} max=${stats.max}ms over100=${stats.over} sumOver=${stats.sumOver}ms`);
+		}
+		catch {
+			// summary 输出失败不应阻断后续 RPC 广播——清理已完成，吞掉异常即可。
+		}
+	}
+
+	__clearAllLagProbes() {
+		const ids = Array.from(this.__agentLagProbes.keys());
+		for (const id of ids) {
+			this.__stopLagProbe(id, 'cleanup');
+		}
+	}
+
 	__scheduleReconnect() {
 		if (!this.started || this.reconnectTimer) {
 			return;
@@ -1164,6 +1261,8 @@ export class RealtimeBridge {
 		setRemoteLogSender(null);
 		this.__clearServerHeartbeat();
 		this.__clearConnectTimer();
+		// stop() / refresh() 兜底回收 lag 探针的 timer，防 unref 仍残留。
+		this.__clearAllLagProbes();
 		if (this.reconnectTimer) {
 			clearTimeout(this.reconnectTimer);
 			this.reconnectTimer = null;

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

@@ -41,7 +41,9 @@ export class RpcSendQueue {
 		this.logger = logger ?? console;
 		this.tag = tag ?? '';
 
-		/** @type {Buffer[]} chunks 或 Buffer 化的 string 消息 */
+		// 队列元素显式记录原始类型：drain 出口按 isString=true → string 帧，false → binary 帧。
+		// 早期实现统一存 Buffer，导致 string 帧被对端当分片残片静默丢弃
+		/** @type {{data: string|Buffer, isString: boolean, bytes: number}[]} */
 		this.queue = [];
 		this.queueBytes = 0;
 		this.closed = false;
@@ -80,7 +82,10 @@ export class RpcSendQueue {
 		}
 
 		// 软上限：队列已积压到 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;
 			// 仅状态翻转点打 log（warn + remoteLog 各一次）；overflow 持续期间所有 drop 静默累加，
@@ -106,9 +111,9 @@ export class RpcSendQueue {
 					return false;
 				}
 			}
-			const buf = Buffer.from(jsonStr, 'utf8');
-			this.queue.push(buf);
-			this.queueBytes += buf.length;
+			const bytes = Buffer.byteLength(jsonStr, 'utf8');
+			this.queue.push({ data: jsonStr, isString: true, bytes });
+			this.queueBytes += bytes;
 			return true;
 		}
 
@@ -130,7 +135,7 @@ export class RpcSendQueue {
 		}
 		// 剩余 chunk 原子性入队（保证同一消息分片连续，不被其他消息插入）
 		for (; i < chunks.length; i += 1) {
-			this.queue.push(chunks[i]);
+			this.queue.push({ data: chunks[i], isString: false, bytes: chunks[i].length });
 			this.queueBytes += chunks[i].length;
 		}
 		return true;
@@ -164,15 +169,15 @@ export class RpcSendQueue {
 		while (this.queue.length > 0
 			&& dc.readyState === 'open'
 			&& dc.bufferedAmount < DC_HIGH_WATER_MARK) {
-			const chunk = this.queue[0];
+			const item = this.queue[0];
 			try {
-				dc.send(chunk);
+				dc.send(item.data);
 			} catch (err) {
 				this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] drain send failed: ${err?.message}`);
 				return; // 保留队列，等 onclose 统一清理
 			}
 			this.queue.shift();
-			this.queueBytes -= chunk.length;
+			this.queueBytes -= item.bytes;
 			// 满 → 未满 状态转换：打一条带累计数的 log，与 overflow-start 对称
 			if (this.queueOverflowActive && this.queueBytes < MAX_QUEUE_BYTES) {
 				this.queueOverflowActive = false;
@@ -187,3 +192,24 @@ export class RpcSendQueue {
 		return this.tag ? ` ${this.tag}` : '';
 	}
 }
+
+/**
+ * 判断一条 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;
+	}
+}