@coclaw/openclaw-coclaw 0.18.0 → 0.19.2

package/src/utils/memory-queue.js

@@ -0,0 +1,310 @@
+/**
+ * 纯内存版 FBQ-API 兼容容器
+ *
+ * 阶段 1 用作 RpcDcSender 的前置缓冲，替换原 `RpcSendQueue` 中的"容器层"职责（admission +
+ * overflow 边沿状态机 + close 汇总）。阶段 2 再把本模块替换为 `FileBackedQueue`，因接口对齐，
+ * 替换近乎一行 import 改动。
+ *
+ * 与 FBQ 的差异：
+ * - 不引入 fs；`diskBytes / writtenBytes` 永为 0，`spilled / fsBroken` 永为 false
+ * - admission 仅基于 `memBudget`；命中 `bypassAdmission(jsonStr)` 时即使队列满也接收（保留
+ *   `RpcSendQueue` 的 agent run 白名单豁免行为）
+ * - 内部携带 overflow-start/-end 边沿状态机和 close 汇总日志（搬自原 `RpcSendQueue`）
+ *
+ * 契约：`enqueue / __nextIter / destroy / clear` 内部任何分支都不得因 logger / remoteLog / onDrop /
+ * bypassAdmission 自身抛而传染调用方——所有外部调用均经过 safe wrapper（try/catch）。
+ *
+ * 使用方式（消费侧）：
+ * ```js
+ * for await (const str of queue) { await sender.send(str); }
+ * ```
+ * 调用 `queue.destroy()` 后 iterator 在下一轮返回 `{ done: true }`。
+ */
+
+import { remoteLog } from '../remote-log.js';
+import { createMutex } from './mutex.js';
+
+/** 默认内存预算：与原 RpcSendQueue 的 MAX_QUEUE_BYTES 对齐 */
+export const DEFAULT_MEM_BUDGET = 10 * 1024 * 1024;
+
+const ID_RE = /^[A-Za-z0-9._-]+$/;
+
+// 惰性压缩阈值（与 FBQ 一致）：head 越过 64 且占数组一半以上时切片回收
+const COMPACT_HEAD_THRESHOLD = 64;
+
+class MemoryQueue {
+	/**
+	 * @param {object} opts
+	 * @param {string} opts.id - 队列标识（仅用于日志 tag/路径校验对齐 FBQ）
+	 * @param {number} [opts.memBudget=10MB] - 内存软上限；queueBytes >= memBudget 且非 bypass 时新消息 drop
+	 * @param {number} [opts.maxMessageBytes=Infinity] - 单条硬上限；超过即 drop（bypass 也不豁免）
+	 * @param {(reason: string, size: number) => void} [opts.onDrop] - 拒入队回调
+	 * @param {{ warn?: Function, info?: Function, error?: Function }} [opts.logger=console]
+	 * @param {(jsonStr: string) => boolean} [opts.bypassAdmission] - 白名单谓词，命中则 admission 豁免
+	 * @param {string} [opts.tag] - 日志前缀（如 connId），缺省不带
+	 */
+	constructor(opts) {
+		const {
+			id,
+			memBudget = DEFAULT_MEM_BUDGET,
+			maxMessageBytes = Infinity,
+			onDrop,
+			logger,
+			bypassAdmission,
+			tag,
+		} = opts ?? {};
+
+		if (!id || typeof id !== 'string') throw new TypeError('id is required');
+		if (id === '.' || id === '..' || !ID_RE.test(id)) {
+			throw new TypeError('id contains invalid characters');
+		}
+		if (!Number.isFinite(memBudget) || memBudget <= 0) {
+			throw new TypeError('memBudget must be a finite positive number');
+		}
+		// Infinity 也合法；只挡 NaN / 非数字 / 非正数
+		if (maxMessageBytes !== Infinity && (!Number.isFinite(maxMessageBytes) || maxMessageBytes <= 0)) {
+			throw new TypeError('maxMessageBytes must be Infinity or a finite positive number');
+		}
+
+		this.id = id;
+		this.memBudget = memBudget;
+		this.maxMessageBytes = maxMessageBytes;
+		this.onDrop = onDrop;
+		this.logger = logger ?? console;
+		this.bypassAdmission = typeof bypassAdmission === 'function' ? bypassAdmission : null;
+		this.tag = tag ?? '';
+
+		// 单文件 ring-ish 结构：head 指针 + 数组；shift 为 O(1) 摊销
+		this.memQueue = [];
+		this.head = 0;
+		this.memBytes = 0;
+
+		// 构造即可用：MemoryQueue 不碰 fs。`init()` 仍保留为 no-op-but-callable，便于
+		// 阶段 2 替换为 FileBackedQueue 时调用方仅需在创建处加一行 `await queue.init()`。
+		this.initialized = true;
+		this.destroyed = false;
+		this.waiters = [];
+		this.mutex = createMutex();
+
+		// drop 统计 + overflow 边沿状态机
+		this.droppedCount = 0;
+		this.droppedBytes = 0;
+		this.queueOverflowActive = false;
+	}
+
+	/**
+	 * 异步初始化（接口对齐 FBQ）。MemoryQueue 不碰 fs，构造时 initialized 已置 true，本函数为 no-op。
+	 * 阶段 2 切到 FBQ 时此函数承担实际的残留清理。幂等。
+	 */
+	async init() {
+		// 不持锁也无副作用；保留 await 与 mutex 交互结构是为了让阶段 2 切换 FBQ 时无需改外部时序
+		return await this.mutex.withLock(async () => { /* no-op */ });
+	}
+
+	async [Symbol.asyncDispose]() {
+		await this.destroy();
+	}
+
+	/**
+	 * 入队一条字符串。
+	 * - 队列满（memBytes >= memBudget）且未命中 bypassAdmission → onDrop + 返回 false
+	 *   首次进入溢出态打 overflow-start（warn + remoteLog），持续期间静默累加
+	 * - 否则入队 + 返回 true（包括"单条 overshoot"：当前 memBytes < memBudget，但本条很大）
+	 *
+	 * @param {string} jsonStr
+	 * @returns {Promise<boolean>}
+	 */
+	async enqueue(jsonStr) {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return false;
+			if (typeof jsonStr !== 'string') throw new TypeError('jsonStr must be a string');
+
+			const size = Buffer.byteLength(jsonStr, 'utf8');
+
+			// per-message 硬上限：bypass 也不豁免。对齐 sender 端 MAX_SINGLE_MSG_BYTES 检查，
+			// 避免大帧先入队再被 sender 拒，导致 memBytes 异常膨胀（特别是 sender 阻塞期间）。
+			if (size > this.maxMessageBytes) {
+				this.droppedCount += 1;
+				this.droppedBytes += size;
+				this.__dispatchDrop('oversize', size);
+				this.__safeWarn(`drop reason=oversize size=${size} cap=${this.maxMessageBytes}`);
+				return false;
+			}
+
+			// admission：与原 RpcSendQueue 行为对齐——按当前已积压字节判断（不含本条 size），
+			// 允许"单条 overshoot"：上一条消息把 queueBytes 顶到 < MAX 但 >= MAX 之间任一值时
+			// 仍能入队；下一次再有非白名单消息才会被 drop。
+			if (this.memBytes >= this.memBudget && !this.__isBypass(jsonStr)) {
+				this.droppedCount += 1;
+				this.droppedBytes += size;
+				this.__dispatchDrop('queue-full', size);
+				// 仅状态翻转点打 log，避免 DC 卡死时刷屏
+				if (!this.queueOverflowActive) {
+					this.queueOverflowActive = true;
+					this.__safeWarn(`overflow-start queueBytes=${this.memBytes}`);
+					this.__safeRemoteLog(`rpc-queue.overflow-start${this.__tagSuffix()} queueBytes=${this.memBytes}`);
+				}
+				return false;
+			}
+
+			this.memQueue.push(jsonStr);
+			this.memBytes += size;
+			this.__wakeOne();
+			return true;
+		});
+	}
+
+	/**
+	 * 当前快照，用于诊断 dump。形态与 FBQ 对齐 + 阶段 1 私有诊断字段。
+	 * @returns {{
+	 *   memCount: number, memBytes: number, diskBytes: number, writtenBytes: number,
+	 *   spilled: boolean, fsBroken: boolean,
+	 *   droppedCount: number, droppedBytes: number, queueOverflowActive: boolean
+	 * }}
+	 */
+	stats() {
+		return {
+			memCount: this.memQueue.length - this.head,
+			memBytes: this.memBytes,
+			diskBytes: 0,
+			writtenBytes: 0,
+			spilled: false,
+			fsBroken: false,
+			droppedCount: this.droppedCount,
+			droppedBytes: this.droppedBytes,
+			queueOverflowActive: this.queueOverflowActive,
+		};
+	}
+
+	/**
+	 * 清空数据但保留实例可用，重置 drop 统计与 overflow 状态。
+	 */
+	async clear() {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return;
+			this.memQueue = [];
+			this.head = 0;
+			this.memBytes = 0;
+			this.droppedCount = 0;
+			this.droppedBytes = 0;
+			this.queueOverflowActive = false;
+		});
+	}
+
+	/**
+	 * 关闭队列：唤醒所有 waiter（让 iterator 返回 done）、汇总 drop/residual log。幂等。
+	 */
+	async destroy() {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return;
+			this.destroyed = true;
+
+			const residual = this.memQueue.length - this.head;
+			const residualBytes = this.memBytes;
+
+			// 唤醒所有等待者，让它们在下一轮循环看到 destroyed 并返回 done
+			const toWake = this.waiters.splice(0);
+			for (const w of toWake) w.resolve();
+
+			this.memQueue = [];
+			this.head = 0;
+			this.memBytes = 0;
+
+			if (this.droppedCount > 0 || residual > 0) {
+				this.__safeRemoteLog(
+					`rpc-queue.close${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes} residualChunks=${residual} residualBytes=${residualBytes}`,
+				);
+			}
+		});
+	}
+
+	[Symbol.asyncIterator]() {
+		const self = this;
+		return {
+			next() { return self.__nextIter(); },
+			return() { return Promise.resolve({ done: true, value: undefined }); },
+			[Symbol.asyncIterator]() { return this; },
+		};
+	}
+
+	async __nextIter() {
+		while (true) {
+			let waitPromise = null;
+			const result = await this.mutex.withLock(async () => {
+				if (this.memQueue.length - this.head > 0) {
+					const item = this.memQueue[this.head];
+					this.memQueue[this.head] = undefined;
+					this.head += 1;
+					this.memBytes -= Buffer.byteLength(item, 'utf8');
+
+					// 惰性压缩：避免 head 一直向前、数组永不回收
+					if (this.head > COMPACT_HEAD_THRESHOLD && this.head * 2 >= this.memQueue.length) {
+						this.memQueue = this.memQueue.slice(this.head);
+						this.head = 0;
+					}
+
+					// 满 → 未满 状态翻转：与 overflow-start 对称，含累计 dropped
+					if (this.queueOverflowActive && this.memBytes < this.memBudget) {
+						this.queueOverflowActive = false;
+						this.__safeInfo(`overflow-end dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`);
+						this.__safeRemoteLog(
+							`rpc-queue.overflow-end${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`,
+						);
+					}
+					return { value: item, done: false };
+				}
+				if (this.destroyed) return { done: true, value: undefined };
+				waitPromise = new Promise((resolve, reject) => {
+					this.waiters.push({ resolve, reject });
+				});
+				return null;
+			});
+			if (result !== null) return result;
+			await waitPromise;
+		}
+	}
+
+	__wakeOne() {
+		if (this.waiters.length > 0) {
+			const w = this.waiters.shift();
+			w.resolve();
+		}
+	}
+
+	__isBypass(jsonStr) {
+		if (!this.bypassAdmission) return false;
+		try {
+			return Boolean(this.bypassAdmission(jsonStr));
+		} catch {
+			// bypass 谓词自身抛 → 视为非白名单（最安全的回退；保守 drop 而非误入队）
+			return false;
+		}
+	}
+
+	__dispatchDrop(reason, size) {
+		try {
+			this.onDrop?.(reason, size);
+		} catch (err) {
+			// onDrop 自身抛是调用方的 bug；不能传染给 enqueue 契约
+			this.__safeWarn(`onDrop threw: ${err?.message}`);
+		}
+	}
+
+	__tagSuffix() {
+		return this.tag ? ` ${this.tag}` : '';
+	}
+
+	__safeWarn(msg) {
+		try { this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了也不能让 enqueue 抛 */ }
+	}
+
+	__safeInfo(msg) {
+		try { this.logger.info?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了也不能让 enqueue/__nextIter 抛 */ }
+	}
+
+	__safeRemoteLog(text) {
+		try { remoteLog(text); } catch { /* 防御性：remoteLog 当前同步路径不抛，未来若变化此 wrapper 兜底 */ }
+	}
+}
+
+export { MemoryQueue };

package/src/webrtc/agent-run-response.js

@@ -0,0 +1,20 @@
+/**
+ * 判断一条 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
+ */
+export function isAgentRunResponse(jsonStr) {
+	try {
+		const parsed = JSON.parse(jsonStr);
+		return parsed?.type === 'res' && Boolean(parsed?.payload?.runId);
+	} catch {
+		return false;
+	}
+}

package/src/webrtc/dc-chunking.js

@@ -39,6 +39,11 @@ export function buildChunks(jsonStr, maxMessageSize, getNextMsgId) {
 
 	const msgId = getNextMsgId();
 	const totalChunks = Math.ceil(fullBytes.byteLength / chunkPayloadSize);
+	// 边界保护：极小 maxMessageSize 下数学上可能产生 > MAX_CHUNKS_PER_MSG 的 chunk 数量；
+	// 接收端会在第 MAX_CHUNKS_PER_MSG+1 块拒绝，整条消息将无法重组。早拒避免无效发送。
+	if (totalChunks > MAX_CHUNKS_PER_MSG) {
+		throw new Error(`message of ${fullBytes.byteLength} bytes with maxMessageSize=${maxMessageSize} would produce ${totalChunks} chunks, exceeds ${MAX_CHUNKS_PER_MSG}`);
+	}
 	const chunks = new Array(totalChunks);
 
 	for (let i = 0; i < totalChunks; i++) {
@@ -57,7 +62,7 @@ export function buildChunks(jsonStr, maxMessageSize, getNextMsgId) {
 
 /**
  * 按需分片并发送消息（薄包装：buildChunks + dc.send）
- * 注意：无应用层流控；生产路径请使用 RpcSendQueue
+ * 注意：无应用层流控；生产路径请使用 MemoryQueue + RpcDcSender
  * @param {object} dc - DataChannel
  * @param {string} jsonStr - 已序列化的 JSON 字符串
  * @param {number} maxMessageSize - 对端声明的 maxMessageSize
@@ -93,6 +98,14 @@ export function createReassembler(onComplete, opts = {}) {
 	function feed(data) {
 		// string = 普通消息，直接交付
 		if (typeof data === 'string') {
+			// 边界保护：peer 可能发送超过单条消息硬上限的字符串（绕过 sender 端 50MB 检查）。
+			// 注意必须用 byteLength 而非 .length —— 后者是 UTF-16 code unit 数，CJK 字符
+			// 1 char = 1 unit 但 UTF-8 占 3 byte，按 .length 比较会让多字节内容绕过上限近 3 倍。
+			const byteLen = Buffer.byteLength(data, 'utf8');
+			if (byteLen > MAX_REASSEMBLY_BYTES) {
+				logger?.warn?.(`[dc-chunking] string frame exceeded ${MAX_REASSEMBLY_BYTES} bytes (got ${byteLen}), discarding`);
+				return;
+			}
 			onComplete(data);
 			return;
 		}
@@ -108,6 +121,12 @@ export function createReassembler(onComplete, opts = {}) {
 		const msgId = buf.readUInt32BE(1);
 		const payload = buf.subarray(HEADER_SIZE);
 
+		// 未知 flag 直接拒绝，避免污染同 msgId 的 pending entry
+		if (flag !== FLAG_BEGIN && flag !== FLAG_MIDDLE && flag !== FLAG_END) {
+			logger?.warn?.(`[dc-chunking] unknown flag 0x${flag.toString(16)} for msgId=${msgId}, discarding`);
+			return;
+		}
+
 		if (flag === FLAG_BEGIN) {
 			// 若已有同 msgId 的未完成重组，丢弃旧的
 			if (pending.has(msgId)) {

package/src/webrtc/rpc-dc-sender.js

@@ -0,0 +1,178 @@
+/**
+ * rpc DataChannel 紧贴发送器（async 阻塞式）
+ *
+ * 阶段 1 从原 `RpcSendQueue` 中拆出：仅保留 DC 紧贴部分——分片（buildChunks）、bufferedAmount
+ * 背压、错误协议。不再持有任何缓冲队列；容器层（admission / overflow / drop 统计）由
+ * `MemoryQueue` 承担。
+ *
+ * 调用形态：典型与 MemoryQueue + for-await 联用。
+ * ```js
+ * for await (const str of queue) {
+ *   try { await sender.send(str); }
+ *   catch (err) {
+ *     if (err.code === 'SENDER_CLOSED') break;
+ *     logger.warn?.(`rpc-dc.send-failed code=${err.code} size=${str.length}`);
+ *   }
+ * }
+ * ```
+ *
+ * 错误协议（统一抛错，no silent return）：
+ * - `SENDER_CLOSED` —— sender 关闭 / DC 非 open / dc.send 抛
+ * - `MESSAGE_OVERSIZED` —— 单条 payload > 50 MB
+ * - `BUILD_CHUNKS_FAILED` —— buildChunks 抛（如 maxMessageSize 太小）
+ *
+ * 背压：bufferedAmount >= HIGH 时 await `bufferedamountlow` 事件再继续；close 期间内部 waiter
+ * 全部 reject(SENDER_CLOSED)。
+ *
+ * `maxMessageSize` 公开字段：ICE restart 后由调用方热更新（PC 重建会重置实例，无需此字段；
+ * 同 connId 的 ICE restart 不重建 sender，仅热更）。
+ */
+
+import { buildChunks } from './dc-chunking.js';
+import { remoteLog } from '../remote-log.js';
+
+/** 高水位：`dc.bufferedAmount >= HIGH` 时 send 阻塞等 BAL */
+export const DC_HIGH_WATER_MARK = 1024 * 1024;       // 1 MB
+/** 低水位：用于 `dc.bufferedAmountLowThreshold`，触发 `bufferedamountlow` 事件 */
+export const DC_LOW_WATER_MARK = 256 * 1024;         // 256 KB
+/** 单条 payload 硬上限：对齐 dc-chunking.js MAX_REASSEMBLY_BYTES */
+export const MAX_SINGLE_MSG_BYTES = 50 * 1024 * 1024; // 50 MB
+
+class RpcDcSender {
+	/**
+	 * @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 {{ warn?: Function, info?: Function, error?: Function }} [opts.logger=console]
+	 * @param {string} [opts.tag] - 日志前缀（如 connId）
+	 */
+	constructor({ dc, maxMessageSize, getNextMsgId, logger, tag } = {}) {
+		if (!dc) throw new Error('RpcDcSender: dc is required');
+		this.dc = dc;
+		this.maxMessageSize = maxMessageSize;
+		this.getNextMsgId = getNextMsgId;
+		this.logger = logger ?? console;
+		this.tag = tag ?? '';
+		this.closed = false;
+		/** @type {{ resolve: () => void, reject: (err: Error) => void }[]} */
+		this.balWaiters = [];
+	}
+
+	/**
+	 * 发送一条 JSON 字符串。Async 阻塞式：bufferedAmount 顶到 HIGH 时 await BAL 再继续。
+	 * 失败均抛出带 `code` 的 Error；调用方按 code 处理。
+	 *
+	 * @param {string} jsonStr
+	 * @returns {Promise<void>}
+	 * @throws {Error & { code: 'SENDER_CLOSED' | 'MESSAGE_OVERSIZED' | 'BUILD_CHUNKS_FAILED' }}
+	 */
+	async send(jsonStr) {
+		this.__assertOpen();
+
+		const payloadBytes = Buffer.byteLength(jsonStr, 'utf8');
+
+		if (payloadBytes > MAX_SINGLE_MSG_BYTES) {
+			this.__safeWarn(`drop reason=single-msg-oversize size=${payloadBytes} cap=${MAX_SINGLE_MSG_BYTES}`);
+			throw makeErr('MESSAGE_OVERSIZED', `payload exceeds ${MAX_SINGLE_MSG_BYTES} bytes (size=${payloadBytes})`);
+		}
+
+		let chunks;
+		try {
+			chunks = buildChunks(jsonStr, this.maxMessageSize, this.getNextMsgId);
+		} catch (err) {
+			const errMsg = err?.message ?? String(err);
+			this.__safeWarn(`drop reason=build-chunks-failed size=${payloadBytes} maxMessageSize=${this.maxMessageSize} err=${errMsg}`);
+			this.__safeRemoteLog(`rpc-dc-sender.build-chunks-failed${this.__tagSuffix()} size=${payloadBytes} maxMessageSize=${this.maxMessageSize} err=${errMsg}`);
+			const wrap = makeErr('BUILD_CHUNKS_FAILED', `buildChunks failed: ${errMsg}`);
+			wrap.cause = err;
+			throw wrap;
+		}
+
+		if (!chunks) {
+			// 不分片：单条 string 整体发送
+			await this.__sendOne(jsonStr);
+			return;
+		}
+		// 分片路径：逐 chunk 阻塞发送，保证同消息的 chunk 连续
+		for (const chunk of chunks) {
+			await this.__sendOne(chunk);
+		}
+	}
+
+	/** 由外部 `dc.onbufferedamountlow` 事件触发，唤醒所有等 BAL 的 waiter */
+	onBufferedAmountLow() {
+		const toWake = this.balWaiters.splice(0);
+		for (const w of toWake) w.resolve();
+	}
+
+	/**
+	 * 关闭发送器：reject 所有 pending waiter（带 SENDER_CLOSED）。幂等。
+	 * 阻塞中的 send 会在下一刻抛 SENDER_CLOSED；后续 send 调用立即抛。
+	 */
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		const toReject = this.balWaiters.splice(0);
+		for (const w of toReject) {
+			w.reject(makeErr('SENDER_CLOSED', 'sender closed'));
+		}
+	}
+
+	async __sendOne(payload) {
+		await this.__waitForRoom();
+		// BAL 与 close 的窄缝：BAL 触发时 onBufferedAmountLow 已 splice 走 waiter 并 resolve；
+		// 若紧接着 close() 介入，splice 看到空数组、无 waiter 可 reject，唤醒后的 continuation
+		// 仍会跑到这里。重检 closed 以保 "closed 后不再写 dc" 的不变量；readyState 变化交由
+		// dc.send 抛 InvalidStateError 时下面 catch 捕获兜底。
+		if (this.closed) {
+			throw makeErr('SENDER_CLOSED', 'sender closed during BAL wait');
+		}
+		try {
+			this.dc.send(payload);
+		} catch (err) {
+			this.__safeWarn(`dc.send failed: ${err?.message}`);
+			const wrap = makeErr('SENDER_CLOSED', `dc.send failed: ${err?.message}`);
+			wrap.cause = err;
+			throw wrap;
+		}
+	}
+
+	async __waitForRoom() {
+		// 立刻检查 closed/readyState
+		if (this.closed || this.dc.readyState !== 'open') {
+			throw makeErr('SENDER_CLOSED', 'sender closed or dc not open');
+		}
+		if (this.dc.bufferedAmount < DC_HIGH_WATER_MARK) return;
+		// 阻塞等 onBufferedAmountLow 唤醒（或 close reject）
+		return await new Promise((resolve, reject) => {
+			this.balWaiters.push({ resolve, reject });
+		});
+	}
+
+	__assertOpen() {
+		if (this.closed || this.dc.readyState !== 'open') {
+			throw makeErr('SENDER_CLOSED', 'sender closed or dc not open');
+		}
+	}
+
+	__tagSuffix() {
+		return this.tag ? ` ${this.tag}` : '';
+	}
+
+	__safeWarn(msg) {
+		try { this.logger.warn?.(`[rpc-dc-sender${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了不能让 send 抛非协议错 */ }
+	}
+
+	__safeRemoteLog(text) {
+		try { remoteLog(text); } catch { /* 防御性兜底 */ }
+	}
+}
+
+function makeErr(code, message) {
+	const err = new Error(message);
+	err.code = code;
+	return err;
+}
+
+export { RpcDcSender };