@coclaw/openclaw-coclaw 0.13.2 → 0.14.1

package/index.js

@@ -13,10 +13,78 @@ import { generateTitle } from './src/topic-manager/title-gen.js';
 import { AutoUpgradeScheduler } from './src/auto-upgrade/updater.js';
 import { getPackageInfo } from './src/auto-upgrade/updater-check.js';
 import { createFileHandler } from './src/file-manager/handler.js';
+import { abortAgentRun } from './src/agent-abort.js';
+import { remoteLog } from './src/remote-log.js';
 
 import { getPluginVersion, __resetPluginVersion } from './src/plugin-version.js';
 export { getPluginVersion, __resetPluginVersion };
 
+// 侧门注册表观测：patch OpenClaw embeddedRunState.activeRuns 的 set/delete，
+// 用于跟踪 sessionId 何时注册/注销（agent 取消流程实际读取的就是这张表）。
+// OpenClaw 侧门形状变化时（缺失 / 抛异常），通过 remoteLog 上报为升级契约变更的早期信号。
+const PATCH_LABELS = [
+	['embedded.activeRuns', () => globalThis[Symbol.for('openclaw.embeddedRunState')]?.activeRuns],
+];
+
+function installAbortRegistryDiag(logger) {
+	const installed = [];
+	const missing = [];
+	try {
+		for (const [label, resolve] of PATCH_LABELS) {
+			if (patchMapLogging(resolve(), label, logger)) installed.push(label);
+			else missing.push(label);
+		}
+	}
+	catch (err) {
+		logger?.warn?.(`[coclaw.diag] installAbortRegistryDiag failed: ${String(err?.message ?? err)}`);
+		remoteLog(`abort.patch-failed reason=${String(err?.message ?? err)}`);
+		return;
+	}
+	remoteLog(`abort.patch installed=${installed.join(',') || 'none'} missing=${missing.join(',') || 'none'}`);
+}
+
+function patchMapLogging(map, label, logger) {
+	if (!map || typeof map.set !== 'function' || typeof map.delete !== 'function') return false;
+	if (map.__coclawDiagPatched) return true;
+	// 先打 idempotent 标记：若 map 是 frozen/sealed/Proxy 致 defineProperty 抛，
+	// 立即返回 false 让上层归入 missing；不留下半装好的 wrapper 状态
+	try {
+		Object.defineProperty(map, '__coclawDiagPatched', { value: true, enumerable: false });
+	}
+	catch (err) {
+		logger?.warn?.(`[coclaw.diag] cannot mark ${label} patched: ${String(err?.message ?? err)}`);
+		return false;
+	}
+	const origSet = map.set.bind(map);
+	const origDel = map.delete.bind(map);
+	// log 行包 try/catch 兜底：上游若把 Map 换成有 throwing getter（如 Proxy）的对象，
+	// 不能让本插件的诊断 log 把 OpenClaw 内部 set/delete 流程带崩
+	const safeLog = (msg) => {
+		try { logger?.info?.(msg); } catch { /* swallow — diag log 不得影响主流程 */ }
+	};
+	const safeSize = () => {
+		try { return map.size; } catch { return '?'; }
+	};
+	map.set = (key, value) => {
+		const res = origSet(key, value);
+		safeLog(`[coclaw.diag] ${label}.set key=${stringifyKey(key)} size=${safeSize()}`);
+		return res;
+	};
+	map.delete = (key) => {
+		let had;
+		try { had = map.has(key); } catch { had = '?'; }
+		const res = origDel(key);
+		safeLog(`[coclaw.diag] ${label}.delete key=${stringifyKey(key)} had=${had} size=${safeSize()}`);
+		return res;
+	};
+	return true;
+}
+
+function stringifyKey(k) {
+	if (typeof k === 'string') return k;
+	try { return JSON.stringify(k); } catch { return String(k); }
+}
+
 /* c8 ignore start */
 function parseCommandArgs(args) {
 	const tokens = (args ?? '').split(/\s+/).filter(Boolean);
@@ -64,6 +132,7 @@ const plugin = {
 	register(api) {
 		setRuntime(api.runtime);
 		const logger = api?.logger ?? console;
+		installAbortRegistryDiag(logger);
 		const manager = createSessionManager({ logger });
 		const topicManager = new TopicManager({ logger });
 		const chatHistoryManager = new ChatHistoryManager({ logger });
@@ -457,6 +526,37 @@ const plugin = {
 			}
 		});
 
+		// 取消正在执行的 embedded agent run（通过 OpenClaw 全局 symbol 侧门）
+		// 侧门不存在 / sessionId 未注册 / handle.abort 抛异常时返回 { ok:false, reason } —— UI 静默降级
+		// UI 可能在 OpenClaw 注册 sessionId 前点 STOP（注册空窗期），此时返回 not-found；UI 会按 500ms 间隔重试。
+		api.registerGatewayMethod('coclaw.agent.abort', ({ params, respond }) => {
+			try {
+				const sessionId = params?.sessionId;
+				if (typeof sessionId !== 'string' || !sessionId) {
+					logger.warn?.(`[coclaw.agent.abort] invalid sessionId: ${JSON.stringify(sessionId)}`);
+					respondInvalid(respond, 'sessionId is required');
+					return;
+				}
+				const result = abortAgentRun(sessionId);
+				// not-found 是 UI 重试期常态（注册空窗），不打日志避免噪音；其余分支保留 info
+				if (result.reason !== 'not-found') {
+					logger.info?.(`[coclaw.agent.abort] result sessionId=${sessionId} ok=${result.ok}${result.reason ? ` reason=${result.reason}` : ''}${result.error ? ` error=${result.error}` : ''}`);
+				}
+				if (result.ok) {
+					remoteLog(`abort.success sid=${sessionId}`);
+				}
+				else if (result.reason === 'not-supported') {
+					// 侧门缺失或 handle shape 变化：OpenClaw 升级契约变更的早期信号
+					remoteLog(`abort.not-supported sid=${sessionId}`);
+				}
+				respond(true, result);
+			}
+			catch (err) {
+				logger.error?.(`[coclaw.agent.abort] handler threw: ${String(err?.message ?? err)}`);
+				respondError(respond, err);
+			}
+		});
+
 		api.registerGatewayMethod('coclaw.upgradeHealth', async ({ respond }) => {
 			try {
 				const { version } = await getPackageInfo();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -60,7 +60,7 @@
   },
   "dependencies": {
     "node-datachannel": "0.32.2",
-    "@coclaw/pion-node": "^0.1.1",
+    "@coclaw/pion-node": "^0.1.2",
     "werift": "^0.19.0",
     "ws": "^8.19.0"
   },

package/src/agent-abort.js

@@ -0,0 +1,35 @@
+/**
+ * agent-abort：封装 OpenClaw embedded agent run 的侧门取消入口
+ *
+ * OpenClaw 自 v2026.3.12 起通过全局 symbol 注册表暴露 activeRuns 映射，
+ * 允许外部根据 sessionId 调 handle.abort() 真正终止正在执行的 agent run
+ *（LLM + 工具 + compaction 均受影响）。
+ *
+ * 本模块是 CoClaw 插件访问该侧门的唯一入口，未来上游提供正式 API 时集中替换。
+ */
+
+const EMBEDDED_RUN_STATE_KEY = Symbol.for('openclaw.embeddedRunState');
+
+/**
+ * 尝试取消 sessionId 对应的 embedded agent run
+ * @param {string} sessionId
+ * @returns {{ ok: true } | { ok: false, reason: 'not-supported' | 'not-found' | 'abort-threw', error?: string }}
+ */
+export function abortAgentRun(sessionId) {
+	const state = globalThis[EMBEDDED_RUN_STATE_KEY];
+	if (!state || !state.activeRuns || typeof state.activeRuns.get !== 'function') {
+		return { ok: false, reason: 'not-supported' };
+	}
+	try {
+		const handle = state.activeRuns.get(sessionId);
+		if (!handle) return { ok: false, reason: 'not-found' };
+		// shape 守卫：abort 字段应为函数；若不是说明 OpenClaw handle 契约变化（归入 not-supported 让 UI 提示升级）
+		if (typeof handle.abort !== 'function') return { ok: false, reason: 'not-supported' };
+		handle.abort();
+		return { ok: true };
+	}
+	catch (err) {
+		// activeRuns.get() 或 handle.abort() 抛（非 Map 实现 / OpenClaw 内部错误）
+		return { ok: false, reason: 'abort-threw', error: String(err?.message ?? err) };
+	}
+}

package/src/platform-info.js

@@ -0,0 +1,60 @@
+import os from 'node:os';
+import process from 'node:process';
+
+// 模块级缓存：所有字段在进程生命周期内不变，缓存后 ws 重连补发零开销。
+let __cachedLine = null;
+
+/**
+ * 以 "key=value" 形式收集运行环境信息，用于诊断平台相关二进制依赖（如 pion-ipc）问题。
+ *
+ * 尽力而为：每项独立 try/catch，单项失败不影响其它项；无法获取时该字段省略。
+ * 结果在进程生命周期内缓存，重复调用零额外开销。
+ *
+ * 字段：platform / arch / node / osrel / cpu / cores / mem
+ *
+ * @returns {string} - 形如 `platform=linux arch=x64 node=v20.11.0 osrel=6.6.87 cpu="Intel Xeon" cores=8 mem=16.0GB`
+ */
+export function getPlatformInfoLine() {
+	if (__cachedLine !== null) return __cachedLine;
+	const parts = [];
+
+	tryPush(parts, 'platform', () => process.platform);
+	tryPush(parts, 'arch', () => process.arch);
+	tryPush(parts, 'node', () => process.version);
+	tryPush(parts, 'osrel', () => os.release());
+	tryPush(parts, 'cpu', () => {
+		const model = os.cpus()?.[0]?.model;
+		if (!model) return undefined;
+		// 外层包双引号以保留含空格的 model；内部双引号 / C0 控制字符 / DEL 替换为空格后折叠空白
+		const cleaned = String(model).replace(/["\x00-\x1F\x7F]/g, ' ').replace(/\s+/g, ' ').trim();
+		if (!cleaned) return undefined;
+		return `"${cleaned}"`;
+	});
+	tryPush(parts, 'cores', () => {
+		const n = os.cpus()?.length;
+		return n > 0 ? n : undefined;
+	});
+	tryPush(parts, 'mem', () => {
+		const bytes = os.totalmem();
+		if (!bytes || !Number.isFinite(bytes)) return undefined;
+		return `${(bytes / 1024 ** 3).toFixed(1)}GB`;
+	});
+
+	__cachedLine = parts.join(' ');
+	return __cachedLine;
+}
+
+/** 测试用：清缓存以便覆盖不同 monkey-patch 场景 */
+export function __resetPlatformInfoCache() {
+	__cachedLine = null;
+}
+
+function tryPush(parts, key, resolver) {
+	try {
+		const value = resolver();
+		if (value === undefined || value === null || value === '') return;
+		parts.push(`${key}=${value}`);
+	} catch {
+		// 单项失败静默跳过，不影响其它字段
+	}
+}

package/src/realtime-bridge.js

@@ -14,6 +14,7 @@ import {
 import { getRuntime } from './runtime.js';
 import { setSender as setRemoteLogSender, remoteLog } from './remote-log.js';
 import { getPluginVersion } from './plugin-version.js';
+import { getPlatformInfoLine } from './platform-info.js';
 
 const DEFAULT_GATEWAY_WS_URL = `ws://127.0.0.1:${process.env.OPENCLAW_GATEWAY_PORT || '18789'}`;
 const RECONNECT_MS = 10_000;
@@ -811,9 +812,14 @@ export class RealtimeBridge {
 			this.__clearConnectTimer();
 			this.logger.info?.(`[coclaw] realtime bridge connected: ${maskedTarget}`);
 			remoteLog('ws.connected peer=server');
+			// 顺序很重要：先注入 sender 再 remoteLog 环境信息——这样环境信息能随当前 sock
+			// 立即 flush；同时 sender 内部仅做 sock.send（不回调 remoteLog），无循环依赖。
 			setRemoteLogSender((msg) => {
 				if (sock.readyState === 1) sock.send(JSON.stringify(msg));
 			});
+			// ws 重连后补发环境信息：server 重启重连后能立即看到当前 claw 的运行环境与 webrtc 选型。
+			// __buildEnvLine 内部所有读取均为缓存值，无 native syscall。
+			remoteLog(this.__buildEnvLine());
 			this.__startServerHeartbeat(sock);
 			this.__ensureGatewayConnection();
 		});
@@ -967,12 +973,28 @@ export class RealtimeBridge {
 		this.__ndcPreloadResult = preloadResult;
 		this.__ndcCleanup = preloadResult.cleanup;
 		const implLabel = preloadResult.impl === 'ndc' ? 'node-datachannel(ndc)' : preloadResult.impl;
+		this.__implLabel = implLabel; // 缓存供 ws.open 时发送
+		// 启动信息只本地 log；远程发送统一由 ws.open 触发，避免重复
 		this.logger.info?.(`[coclaw] WebRTC impl: ${implLabel}`);
-		remoteLog(`bridge.webrtc-impl impl=${implLabel}`);
-		remoteLog(`bridge.started version=${this.__pluginVersion}`);
+		this.logger.info?.(`[coclaw] ${this.__buildEnvLine()}`);
+		remoteLog('bridge.started');
 		await this.__connectIfNeeded();
 	}
 
+	/**
+	 * 组装一条覆盖最基础环境信息的 log 行：
+	 *   coclaw.env impl=<...> plugin=<ver> openclaw=<ver> platform=<...> ... mem=<...>
+	 *
+	 * 字段值均为已缓存的轻量同步读取，无 native syscall；不调用 remoteLog，无循环依赖。
+	 */
+	__buildEnvLine() {
+		const rt = getRuntime();
+		const openclawVer = (rt?.version && rt.version !== 'unknown') ? rt.version : 'unknown';
+		const impl = this.__implLabel ?? 'pending';
+		const plugin = this.__pluginVersion ?? 'unknown';
+		return `coclaw.env impl=${impl} plugin=${plugin} openclaw=${openclawVer} ${getPlatformInfoLine()}`;
+	}
+
 	async refresh() {
 		await this.stop();
 		await this.start({

package/src/topic-manager/title-gen.js

@@ -114,7 +114,8 @@ export async function generateTitle({ topicId, topicManager, agentRpc, logger })
 			message: '请为这段对话生成标题',
 			idempotencyKey: randomUUID(),
 		}, {
-			timeoutMs: 60_000,
+			// 题目生成需等待 LLM 完整响应；60s 在复杂对话/慢模型下易超时
+			timeoutMs: 300_000,
 			acceptTimeoutMs: 10_000,
 		});
 

package/src/webrtc/dc-chunking.js

@@ -22,20 +22,15 @@ const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
 /**
- * 按需分片并发送消息
- * 小于 maxMessageSize 直接发 string；否则切成 binary chunk 逐个发送
- * @param {object} dc - DataChannel（werift 或浏览器）
+ * 按需分片：小于等于 maxMessageSize 返回 null（调用方直发 string），否则返回 chunk 数组
  * @param {string} jsonStr - 已序列化的 JSON 字符串
  * @param {number} maxMessageSize - 对端声明的 maxMessageSize
  * @param {() => number} getNextMsgId - 获取下一个 msgId
+ * @returns {Buffer[]|null} null 表示不需要分片；否则为 chunk Buffer 数组
  */
-export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger) {
+export function buildChunks(jsonStr, maxMessageSize, getNextMsgId) {
 	const fullBytes = encoder.encode(jsonStr);
-	// 快路径：不需要分片
-	if (fullBytes.byteLength <= maxMessageSize) {
-		dc.send(jsonStr);
-		return;
-	}
+	if (fullBytes.byteLength <= maxMessageSize) return null;
 
 	const chunkPayloadSize = maxMessageSize - HEADER_SIZE;
 	if (chunkPayloadSize <= 0) {
@@ -44,7 +39,7 @@ export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger)
 
 	const msgId = getNextMsgId();
 	const totalChunks = Math.ceil(fullBytes.byteLength / chunkPayloadSize);
-	logger?.info?.(`[dc-chunking] chunking msgId=${msgId}: ${fullBytes.byteLength} bytes → ${totalChunks} chunks (maxMsgSize=${maxMessageSize})`);
+	const chunks = new Array(totalChunks);
 
 	for (let i = 0; i < totalChunks; i++) {
 		const start = i * chunkPayloadSize;
@@ -55,7 +50,30 @@ export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger)
 		chunk[0] = flag;
 		chunk.writeUInt32BE(msgId, 1);
 		chunk.set(fullBytes.subarray(start, end), HEADER_SIZE);
+		chunks[i] = chunk;
+	}
+	return chunks;
+}
 
+/**
+ * 按需分片并发送消息（薄包装：buildChunks + dc.send）
+ * 注意：无应用层流控；生产路径请使用 RpcSendQueue
+ * @param {object} dc - DataChannel
+ * @param {string} jsonStr - 已序列化的 JSON 字符串
+ * @param {number} maxMessageSize - 对端声明的 maxMessageSize
+ * @param {() => number} getNextMsgId - 获取下一个 msgId
+ * @param {object} [logger] - 可选 logger
+ */
+export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger) {
+	const chunks = buildChunks(jsonStr, maxMessageSize, getNextMsgId);
+	if (!chunks) {
+		dc.send(jsonStr);
+		return;
+	}
+	const msgId = chunks[0].readUInt32BE(1);
+	const totalBytes = chunks.reduce((n, c) => n + (c.length - HEADER_SIZE), 0);
+	logger?.info?.(`[dc-chunking] chunking msgId=${msgId}: ${totalBytes} bytes → ${chunks.length} chunks (maxMsgSize=${maxMessageSize})`);
+	for (const chunk of chunks) {
 		dc.send(chunk);
 	}
 }

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

@@ -0,0 +1,182 @@
+/**
+ * rpc DataChannel 发送流控队列
+ *
+ * 针对 plugin 侧 rpc DC 的应用层流控：与 UI 侧 `webrtc-connection.js` 语义对齐，
+ * 但因插件运行在 gateway 进程内，必须对队列大小设硬/软上限，避免 OOM。
+ *
+ * 使用方式：每条 rpc DC 一个实例，绑定到 session.rpcSendQueue。
+ * - send(jsonStr)：同步入口，fire-and-forget；返回 accepted/dropped
+ * - onBufferedAmountLow()：由 DC `bufferedamountlow` 事件转调，触发 drain
+ * - close()：DC 关闭时调用，清空队列并汇总 drop 统计
+ *
+ * 不做：Promise 送达保证；单条消息硬上限内的背压；自动重试。
+ */
+
+import { buildChunks } from './dc-chunking.js';
+import { remoteLog } from '../remote-log.js';
+
+/** 高水位：`dc.bufferedAmount >= HIGH` 时暂停 fast-path / drain */
+export const DC_HIGH_WATER_MARK = 1024 * 1024;       // 1 MB
+/** 低水位：设置 `dc.bufferedAmountLowThreshold`，触发 `bufferedamountlow` 事件 */
+export const DC_LOW_WATER_MARK = 256 * 1024;         // 256 KB
+/** 应用层队列软上限：`queueBytes >= MAX_QUEUE_BYTES` 时新消息被 drop */
+export const MAX_QUEUE_BYTES = 10 * 1024 * 1024;     // 10 MB
+/** 单条消息硬上限（对齐 dc-chunking.js MAX_REASSEMBLY_BYTES，接收端重组不了也无意义） */
+export const MAX_SINGLE_MSG_BYTES = 50 * 1024 * 1024; // 50 MB
+
+export class RpcSendQueue {
+	/**
+	 * @param {object} opts
+	 * @param {object} opts.dc - DataChannel 实例（需支持 send / bufferedAmount / readyState）
+	 * @param {number} opts.maxMessageSize - 对端 SDP 声明的 a=max-message-size
+	 * @param {() => number} opts.getNextMsgId - 分片 msgId 生成器
+	 * @param {object} [opts.logger] - pino 风格 logger
+	 * @param {string} [opts.tag] - 诊断 tag（通常是 connId）
+	 */
+	constructor({ dc, maxMessageSize, getNextMsgId, logger, tag }) {
+		if (!dc) throw new Error('RpcSendQueue: dc is required');
+		this.dc = dc;
+		this.maxMessageSize = maxMessageSize;
+		this.getNextMsgId = getNextMsgId;
+		this.logger = logger ?? console;
+		this.tag = tag ?? '';
+
+		/** @type {Buffer[]} chunks 或 Buffer 化的 string 消息 */
+		this.queue = [];
+		this.queueBytes = 0;
+		this.closed = false;
+
+		// drop 统计（累计到 close 时汇总）
+		this.droppedCount = 0;
+		this.droppedBytes = 0;
+		// 队列"满"状态：仅 queue-full drop 触发 true；drain 下降到 < MAX 翻回 false
+		// single-msg-oversize drop 不影响此状态（它是应用 bug 性质，不代表队列压力）
+		this.queueOverflowActive = false;
+	}
+
+	/**
+	 * 同步发送一条 JSON 字符串。
+	 * @param {string} jsonStr
+	 * @returns {boolean} true=accepted（至少已入队或已直发），false=dropped
+	 */
+	send(jsonStr) {
+		if (this.closed || this.dc.readyState !== 'open') return false;
+
+		const chunks = buildChunks(jsonStr, this.maxMessageSize, this.getNextMsgId);
+		const totalBytes = chunks
+			? chunks.reduce((n, c) => n + c.length, 0)
+			: Buffer.byteLength(jsonStr, 'utf8');
+
+		// 硬上限：单条超限
+		if (totalBytes > 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}`);
+			return false;
+		}
+
+		// 软上限：队列已积压到 MAX（允许之前单条溢出，但新消息从此开始拒绝）
+		if (this.queueBytes >= MAX_QUEUE_BYTES) {
+			this.droppedCount += 1;
+			this.droppedBytes += totalBytes;
+			this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] drop reason=queue-full size=${totalBytes} queueBytes=${this.queueBytes}`);
+			if (!this.queueOverflowActive) {
+				this.queueOverflowActive = true;
+				remoteLog(`rpc-queue.overflow-start${this.__tagSuffix()} queueBytes=${this.queueBytes}`);
+			}
+			return false;
+		}
+
+		// 不分片：单条 string 或 Buffer 直接处理
+		if (!chunks) {
+			if (this.queue.length === 0
+				&& this.dc.readyState === 'open'
+				&& this.dc.bufferedAmount < DC_HIGH_WATER_MARK) {
+				try {
+					this.dc.send(jsonStr);
+					return true;
+				} catch (err) {
+					this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] fast-path send failed: ${err?.message}`);
+					return false;
+				}
+			}
+			const buf = Buffer.from(jsonStr, 'utf8');
+			this.queue.push(buf);
+			this.queueBytes += buf.length;
+			return true;
+		}
+
+		// 分片：fast-path 尝试同步直发尽可能多的 chunk
+		// 循环条件与 __drain 一致：DC 仍 open 且 bufferedAmount 未顶到 HIGH
+		let i = 0;
+		if (this.queue.length === 0) {
+			while (i < chunks.length
+				&& this.dc.readyState === 'open'
+				&& this.dc.bufferedAmount < DC_HIGH_WATER_MARK) {
+				try {
+					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}`);
+					return false;
+				}
+			}
+		}
+		// 剩余 chunk 原子性入队（保证同一消息分片连续，不被其他消息插入）
+		for (; i < chunks.length; i += 1) {
+			this.queue.push(chunks[i]);
+			this.queueBytes += chunks[i].length;
+		}
+		return true;
+	}
+
+	/** 由外部 `dc.onbufferedamountlow` 事件触发 */
+	onBufferedAmountLow() {
+		this.__drain();
+	}
+
+	/**
+	 * 关闭队列：清空待发送 chunks，汇总并 remoteLog drop 统计。幂等。
+	 */
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		const residual = this.queue.length;
+		const residualBytes = this.queueBytes;
+		this.queue.length = 0;
+		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}`);
+		}
+	}
+
+	/** @private 排队持续发送直至 HIGH 水位或队列空 */
+	__drain() {
+		if (this.closed) return;
+		const dc = this.dc;
+		while (this.queue.length > 0
+			&& dc.readyState === 'open'
+			&& dc.bufferedAmount < DC_HIGH_WATER_MARK) {
+			const chunk = this.queue[0];
+			try {
+				dc.send(chunk);
+			} catch (err) {
+				this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] drain send failed: ${err?.message}`);
+				return; // 保留队列，等 onclose 统一清理
+			}
+			this.queue.shift();
+			this.queueBytes -= chunk.length;
+			// 满 → 未满 状态转换
+			if (this.queueOverflowActive && this.queueBytes < MAX_QUEUE_BYTES) {
+				this.queueOverflowActive = false;
+				remoteLog(`rpc-queue.overflow-end${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`);
+			}
+		}
+	}
+
+	/** @private */
+	__tagSuffix() {
+		return this.tag ? ` ${this.tag}` : '';
+	}
+}

package/src/webrtc/webrtc-peer.js

@@ -1,4 +1,5 @@
-import { chunkAndSend, createReassembler } from './dc-chunking.js';
+import { createReassembler } from './dc-chunking.js';
+import { RpcSendQueue, DC_LOW_WATER_MARK } from './rpc-send-queue.js';
 import { remoteLog } from '../remote-log.js';
 
 // 单个 session 内 file DC 历史快照的容量上限（满后按 FIFO 淘汰最老条目）。
@@ -40,7 +41,7 @@ export class WebRtcPeer {
 		this.__PeerConnection = PeerConnection;
 		this.__impl = impl ?? null;
 		this.__rtcTag = impl ? `[coclaw/rtc:${impl}]` : '[coclaw/rtc]';
-		/** @type {Map<string, { pc: object, rpcChannel: object|null, remoteMaxMessageSize: number, nextMsgId: number }>} */
+		/** @type {Map<string, { pc: object, rpcChannel: object|null, rpcSendQueue: RpcSendQueue|null, fileChannels: Set, remoteMaxMessageSize: number, nextMsgId: number }>} */
 		this.__sessions = new Map();
 	}
 
@@ -69,6 +70,13 @@ export class WebRtcPeer {
 			session.__failedTimer = null;
 		}
 		this.__sessions.delete(connId);
+		// 显式关闭 rpc 发送队列：dc.onclose 路径中 `sessions.get(connId)` 已返回 undefined 而短路，
+		// 此处不主动 close 会丢失 drop 汇总 remoteLog 诊断
+		if (session.rpcSendQueue) {
+			session.rpcSendQueue.close();
+			session.rpcSendQueue = null;
+			session.rpcChannel = null;
+		}
 		// 先 detach 事件，防止 pc.close() 异步触发 onconnectionstatechange 删除新 session
 		session.pc.onconnectionstatechange = null;
 		session.pc.onicecandidate = null;
@@ -86,15 +94,16 @@ export class WebRtcPeer {
 		await Promise.all(closing);
 	}
 
-	/** 向所有已打开的 rpcChannel 广播（大消息自动分片） */
+	/** 向所有已打开的 rpcChannel 广播（大消息自动分片，经由 RpcSendQueue 流控） */
 	broadcast(payload) {
 		const jsonStr = JSON.stringify(payload);
 		for (const [connId, session] of this.__sessions) {
-			const dc = session.rpcChannel;
-			if (dc?.readyState === 'open') {
+			const q = session.rpcSendQueue;
+			if (q && session.rpcChannel?.readyState === 'open') {
 				try {
-					chunkAndSend(dc, jsonStr, session.remoteMaxMessageSize, () => session.nextMsgId++, this.logger);
+					q.send(jsonStr);
 				} catch (err) {
+					// buildChunks 抛（maxMessageSize 配置错）等罕见情况
 					this.__logDebug(`[${connId}] broadcast send failed: ${err.message}`);
 				}
 			}
@@ -129,6 +138,13 @@ 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 });
+					// 重协商 SDP 可能变更 a=max-message-size，同步刷新 queue 分片阈值；
+					// queue 中已入队的 chunks 按旧值分片保留，新消息用新值
+					const newMMS = this.__resolveMaxMessageSize(existing.pc, msg.payload.sdp);
+					if (newMMS !== existing.remoteMaxMessageSize) {
+						existing.remoteMaxMessageSize = newMMS;
+						if (existing.rpcSendQueue) existing.rpcSendQueue.maxMessageSize = newMMS;
+					}
 					const answer = await existing.pc.createAnswer();
 					await existing.pc.setLocalDescription(answer);
 					this.__onSend({
@@ -200,15 +216,9 @@ export class WebRtcPeer {
 
 		const pc = new this.__PeerConnection({ iceServers });
 
-		// 分片阈值 = min(远端能接收, 本地能发送)
-		// 远端：从 offer SDP 的 a=max-message-size 解析（缺失则 RFC 8841 默认 65536）
-		// 本地：pc.maxMessageSize（pion 为 65536，ndc/werift 无此属性则不限制）
-		const mmsMatch = msg.payload.sdp?.match(/a=max-message-size:(\d+)/);
-		const remoteMMS = mmsMatch ? parseInt(mmsMatch[1], 10) : 65536;
-		const localMMS = pc.maxMessageSize ?? remoteMMS;
-		const remoteMaxMessageSize = Math.min(remoteMMS, localMMS);
+		const remoteMaxMessageSize = this.__resolveMaxMessageSize(pc, msg.payload.sdp);
 
-		const session = { pc, rpcChannel: null, fileChannels: new Set(), remoteMaxMessageSize, nextMsgId: 1 };
+		const session = { pc, rpcChannel: null, rpcSendQueue: null, fileChannels: new Set(), remoteMaxMessageSize, nextMsgId: 1 };
 		this.__sessions.set(connId, session);
 
 		// ICE candidate → 发给 UI，并统计各类型 candidate 数量
@@ -363,9 +373,29 @@ export class WebRtcPeer {
 	}
 
 	__setupDataChannel(connId, dc) {
+		// rpc DC 发送流控：每条 rpc DC 绑定一个 RpcSendQueue，广播与 files RPC 响应均经此出口
+		const session = this.__sessions.get(connId);
+		if (session && dc.label === 'rpc') {
+			if ('bufferedAmountLowThreshold' in dc) {
+				dc.bufferedAmountLowThreshold = DC_LOW_WATER_MARK;
+			}
+			session.rpcSendQueue = new RpcSendQueue({
+				dc,
+				maxMessageSize: session.remoteMaxMessageSize,
+				getNextMsgId: () => session.nextMsgId++,
+				logger: this.logger,
+				tag: `conn=${connId}`,
+			});
+			dc.onbufferedamountlow = () => {
+				session.rpcSendQueue?.onBufferedAmountLow();
+			};
+		}
+
 		const reassembler = createReassembler((jsonStr) => {
 			const payload = JSON.parse(jsonStr);
 			// DC 探测：立即回复，不走 gateway
+			// 故意绕过 RpcSendQueue：probe-ack 仅用于测量传输层（SCTP/DTLS）健康，
+			// 走 queue 会把应用层积压压力错误地映射到"DC 不通"上。
 			if (payload.type === 'probe') {
 				try { dc.send(JSON.stringify({ type: 'probe-ack' })); }
 				catch { /* DC 已关闭，忽略 */ }
@@ -374,15 +404,10 @@ export class WebRtcPeer {
 			if (payload.type === 'req') {
 				// coclaw.files.* 方法本地处理，不转发 gateway
 				if (payload.method?.startsWith('coclaw.files.') && this.__onFileRpc) {
-					const session = this.__sessions.get(connId);
+					const sess = this.__sessions.get(connId);
 					const sendFn = (response) => {
 						try {
-							chunkAndSend(
-								dc, JSON.stringify(response),
-								session?.remoteMaxMessageSize ?? 65536,
-								() => session.nextMsgId++,
-								this.logger,
-							);
+							sess?.rpcSendQueue?.send(JSON.stringify(response));
 						} catch (err) {
 							this.__logDebug(`[${connId}] sendFn failed: ${err.message}`);
 						}
@@ -404,8 +429,12 @@ export class WebRtcPeer {
 			this.__remoteLog(`dc.closed conn=${connId} label=${dc.label}`);
 			this.logger.info?.(`${this.__rtcTag} [${connId}] DataChannel "${dc.label}" closed`);
 			reassembler.reset();
-			const session = this.__sessions.get(connId);
-			if (session && dc.label === 'rpc') session.rpcChannel = null;
+			const sess = this.__sessions.get(connId);
+			if (sess && dc.label === 'rpc') {
+				sess.rpcSendQueue?.close();
+				sess.rpcSendQueue = null;
+				sess.rpcChannel = null;
+			}
 		};
 		dc.onerror = (err) => {
 			this.__remoteLog(`dc.error conn=${connId} label=${dc.label}`);
@@ -431,8 +460,24 @@ export class WebRtcPeer {
 			? 'none'
 			/* c8 ignore next -- ?? fallback for missing readyState */
 			: [...session.fileChannels].map((dc) => `${dc.label}=${dc.readyState ?? '?'}`).join(',');
-		this.__remoteLog(`rtc.dump conn=${connId} state=${state} sessions=${this.__sessions.size} rpc=${rpcState} fileCount=${session.fileChannels.size} files=[${fileSummary}]`);
-		this.logger.info?.(`${this.__rtcTag} [${connId}] dump state=${state} rpc=${rpcState} fileCount=${session.fileChannels.size} files=${fileSummary}`);
+		const q = session.rpcSendQueue;
+		const queueInfo = q
+			? `queueLen=${q.queue.length} queueBytes=${q.queueBytes} dropped=${q.droppedCount}`
+			: 'queue=none';
+		this.__remoteLog(`rtc.dump conn=${connId} state=${state} sessions=${this.__sessions.size} rpc=${rpcState} ${queueInfo} fileCount=${session.fileChannels.size} files=[${fileSummary}]`);
+		this.logger.info?.(`${this.__rtcTag} [${connId}] dump state=${state} rpc=${rpcState} ${queueInfo} fileCount=${session.fileChannels.size} files=${fileSummary}`);
+	}
+
+	/**
+	 * 分片阈值 = min(远端能接收, 本地能发送)
+	 * 远端：从 SDP 的 a=max-message-size 解析（缺失则 RFC 8841 默认 65536）
+	 * 本地：pc.maxMessageSize（pion 为 65536，ndc/werift 无此属性则不限制）
+	 */
+	__resolveMaxMessageSize(pc, sdp) {
+		const mmsMatch = sdp?.match(/a=max-message-size:(\d+)/);
+		const remoteMMS = mmsMatch ? parseInt(mmsMatch[1], 10) : 65536;
+		const localMMS = pc.maxMessageSize ?? remoteMMS;
+		return Math.min(remoteMMS, localMMS);
 	}
 
 	__logNominatedPair(connId, pair) {