@coclaw/openclaw-coclaw 0.26.4 → 0.26.5

package/index.js

@@ -16,6 +16,7 @@ import { createFileHandler } from './src/file-manager/handler.js';
 import { abortAgentRun } from './src/agent-abort.js';
 import { decideCancelResponse } from './src/agent-cancel-heuristic.js';
 import { remoteLog } from './src/remote-log.js';
+import { normalizeAgentId } from './src/utils/agent-id.js';
 import { registerProviderAuthHandlers } from './src/provider-auth/index.js';
 import { reconcilePortalModels } from './src/provider-auth/reconcile.js';
 import { registerModelDefaultHandlers } from './src/model-default/index.js';
@@ -417,6 +418,9 @@ const plugin = {
 				// 取消前一个 enroll（与 doBind/doUnbind 共享 helper）
 				cancelActiveEnroll();
 				const abortController = new AbortController();
+				// 故意提前 set：enrollClaw 抛错（如 ALREADY_BOUND）时此 controller 会残留，不在 catch 重置——
+				// signal 无 live waiter，abort 死 controller 是 no-op，唯一后果是下次多一行 cancel 日志；
+				// defer/catch-reset 两轮补丁均不可靠已 revert，故保持原样。
 				activeEnrollAbort = abortController;
 
 				const serverUrl = params?.serverUrl ?? api.pluginConfig?.serverUrl;
@@ -461,10 +465,13 @@ const plugin = {
 
 		api.registerGatewayMethod('nativeui.sessions.listAll', async ({ params, respond }) => {
 			try {
-				const agentId = params?.agentId?.trim?.() || 'main';
+				const agentId = normalizeAgentId(params);
 				// best-effort ensure：失败不阻断 listAll
 				try { await ensureAgentSession(agentId); }
 				catch {}
+				// listAll 刻意传原始 params：manager.listAll 内部用与 normalizeAgentId 同一套 trim 逻辑
+				// 自行解析 agentId（见 manager.js）——非字符串已被上面 normalizeAgentId 先抛 INVALID_INPUT
+				// 拦死，带空白的两侧都归一到同一 agent、返回同一列表，无分叉，故此处不另归一、无需守卫。
 				respond(true, await manager.listAll(params ?? {}));
 			}
 			catch (err) {
@@ -536,7 +543,7 @@ const plugin = {
 
 		api.registerGatewayMethod('coclaw.topics.create', async ({ params, respond }) => {
 			try {
-				const agentId = params?.agentId?.trim?.() || 'main';
+				const agentId = normalizeAgentId(params);
 				// 确保该 agent 的 topics 已加载
 				if (!topicManager.__cache.has(agentId)) {
 					await topicManager.load(agentId);
@@ -551,7 +558,7 @@ const plugin = {
 
 		api.registerGatewayMethod('coclaw.topics.list', async ({ params, respond }) => {
 			try {
-				const agentId = params?.agentId?.trim?.() || 'main';
+				const agentId = normalizeAgentId(params);
 				if (!topicManager.__cache.has(agentId)) {
 					await topicManager.load(agentId);
 				}
@@ -583,7 +590,7 @@ const plugin = {
 					respondInvalid(respond, 'topicId required');
 					return;
 				}
-				const agentId = params?.agentId?.trim?.() || 'main';
+				const agentId = normalizeAgentId(params);
 				// 直接复用 session-manager 的 get()，topicId 即 sessionId
 				respond(true, await manager.get({ agentId, sessionId: topicId }));
 			}
@@ -661,7 +668,7 @@ const plugin = {
 
 		api.registerGatewayMethod('coclaw.chatHistory.list', async ({ params, respond }) => {
 			try {
-				const agentId = params?.agentId?.trim?.() || 'main';
+				const agentId = normalizeAgentId(params);
 				const sessionKey = params?.sessionKey?.trim?.();
 				if (!sessionKey) {
 					respondInvalid(respond, 'sessionKey required');
@@ -686,7 +693,7 @@ const plugin = {
 					respondInvalid(respond, 'sessionId required');
 					return;
 				}
-				const agentId = params?.agentId?.trim?.() || 'main';
+				const agentId = normalizeAgentId(params);
 				const limit = params?.limit;
 				respond(true, await manager.getById({ agentId, sessionId, limit }));
 			}
@@ -865,6 +872,7 @@ const plugin = {
 						// 并发控制：取消前一个 enroll（与 RPC 路径共享 helper）
 						cancelActiveEnroll();
 						const abortController = new AbortController();
+						// 同上：故意提前 set，残留仅日志噪音、abort 为 no-op（理由见 RPC handler 处）。
 						activeEnrollAbort = abortController;
 
 						const serverUrl = options.server ?? api.pluginConfig?.serverUrl;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.26.4",
+  "version": "0.26.5",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw plugin for remote chat over WebRTC. Run `openclaw coclaw enroll` after install.",

package/src/chat-history-manager/manager.js

@@ -326,8 +326,10 @@ export class ChatHistoryManager {
 	 * RPC 契约：`coclaw.chatHistory.list` 直接透传本返回值，不做服务端过滤；调用方
 	 * （UI / 其它消费者）按 `archivedAt != null` 自行过滤未归档头与孤儿历史段。
 	 *
-	 * **返回值是 cache 引用，调用方禁止 mutate**（不要 splice / sort / 改 item 字段）；
-	 * RPC handler 立刻 JSON 序列化所以无副作用，进程内消费者若需要修改请先 deep copy。
+	 * 输出按「活跃头（archivedAt 为空）保序居首 + 已归档段按 archivedAt 降序（新→旧）」重排。
+	 * **返回的是新数组（filter 产生的副本），不是 cache 引用**，故重排不污染 cache；但数组内
+	 * 的 item 仍是 cache 共享对象，**调用方禁止改 item 字段**。RPC handler 立刻 JSON 序列化
+	 * 所以无副作用，进程内消费者若需要修改 item 请先 deep copy。
 	 *
 	 * @param {{ agentId: string, sessionKey: string }} params
 	 * @returns {Promise<{ history: { sessionId: string, archivedAt?: number }[] }>}
@@ -336,7 +338,21 @@ export class ChatHistoryManager {
 		await this.__reloadFromDisk(agentId);
 		const store = this.__getStore(agentId);
 		const history = Array.isArray(store[sessionKey]) ? store[sessionKey] : [];
-		return { history };
+		// 分区：宽松判空 == null 把活跃头（archivedAt 实测是 undefined）与已归档段分开。
+		// filter 保序且产生新数组——绝不原地 sort 污染 cache（list 是无锁读路径，被污染的
+		// cache 可能被后续写盘误持久化）。
+		// 先剔除 null/非对象脏元素（仅外部篡改磁盘 JSON 才会出现；正常写盘只 unshift 对象）。
+		// 与写盘侧 __sanitizeAllSessionKeys（!item || typeof item !== 'object' 跳过）姿态一致。
+		// 丢弃而非保留：保留 null 没有任何消费者受益，反而会被 UI loadNextHistorySession
+		// 的无守卫 candidate.sessionId 解引用抛未捕获异常、打断历史加载。
+		const valid = history.filter((it) => it && typeof it === 'object');
+		const heads = valid.filter((it) => it.archivedAt == null);
+		const archived = valid.filter((it) => it.archivedAt != null);
+		// 全序安全比较器：任意值规整成有限数，坏值（NaN/非数字串/对象/Infinity）一律沉到 0、
+		// 落最旧端。哨兵必须用 0 不能用 -Infinity（两个 -Infinity 相减 = NaN 会复活乱序 bug）。
+		const ms = (x) => { const n = Number(x); return Number.isFinite(n) ? n : 0; };
+		archived.sort((a, b) => ms(b.archivedAt) - ms(a.archivedAt));
+		return { history: [...heads, ...archived] };
 	}
 
 	/**

package/src/common/claw-binding.js

@@ -73,6 +73,8 @@ export async function bindClaw({ code, serverUrl }, deps = {}) {
 	}
 	catch (writeErr) {
 		// 本地 writeCfg 失败 → 回滚 server 端，避免产生孤儿 claw（与 unbind 强制不容错的红线对称）
+		// unbindServer 是 async，调用恒返回 promise（连同步异常也转 rejected），.catch 必挂上；
+		// 故意不防"同步 throw"——只有非 async mock 才造得出、生产不可达，真发生也被外层 catch 兜住。
 		await unbindServer({ baseUrl, token: data.token }).catch(() => {
 			// 回滚失败不掩盖原因；用户根据原始 writeErr.message 排查，
 			// server 端孤儿可通过下次 enroll/bind 时 401/404/410 再清理

package/src/file-manager/handler.js

@@ -3,6 +3,7 @@ import fsp from 'node:fs/promises';
 import nodePath from 'node:path';
 import { randomUUID, randomBytes } from 'node:crypto';
 import { remoteLog } from '../remote-log.js';
+import { normalizeAgentId } from '../utils/agent-id.js';
 
 // --- 常量 ---
 
@@ -142,7 +143,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	}
 
 	async function listFiles(params) {
-		const agentId = params?.agentId?.trim?.() || 'main';
+		const agentId = normalizeAgentId(params);
 		const userPath = params?.path ?? ''; /* c8 ignore next -- ?? fallback */
 		const workspaceDir = await resolveWorkspace(agentId);
 		const resolved = await validatePath(workspaceDir, userPath || '.', pathDeps);
@@ -194,7 +195,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	}
 
 	async function deleteFile(params) {
-		const agentId = params?.agentId?.trim?.() || 'main';
+		const agentId = normalizeAgentId(params);
 		const userPath = params?.path;
 		if (!userPath) {
 			const err = new Error('path is required');
@@ -237,7 +238,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	}
 
 	async function mkdirOp(params) {
-		const agentId = params?.agentId?.trim?.() || 'main';
+		const agentId = normalizeAgentId(params);
 		const userPath = params?.path;
 		if (!userPath) {
 			const err = new Error('path is required');
@@ -251,7 +252,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	}
 
 	async function createFile(params) {
-		const agentId = params?.agentId?.trim?.() || 'main';
+		const agentId = normalizeAgentId(params);
 		const userPath = params?.path;
 		if (!userPath) {
 			const err = new Error('path is required');
@@ -276,6 +277,10 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 
 		// 确保父目录存在
 		await _mkdir(nodePath.dirname(resolved), { recursive: true });
+		// 并发同名创建走 last-writer-wins（后写胜出）：故意用普通 writeFile，不用排他创建 'wx'。
+		// 两个并发 create 都建空文件、都成功，结果一个空文件、无数据丢失（对"创建"语义更友好）。
+		// 已评估并弃用 'wx'+ALREADY_EXISTS（2026-06-22 用户裁定）。极窄残留：create 与同名上传
+		// 并发时 lstat→write 窗口内可能截断刚到的上传内容，同用户秒级交错才触发，低危、接受。
 		await (deps.writeFile ?? fsp.writeFile)(resolved, '');
 		return {};
 	}
@@ -389,7 +394,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 
 		let workspaceDir, resolved;
 		try {
-			const agentId = req.agentId?.trim?.() || 'main'; /* c8 ignore next -- ?./?? fallback */
+			const agentId = normalizeAgentId(req);
 			workspaceDir = await resolveWorkspace(agentId);
 			resolved = await validatePath(workspaceDir, req.path, pathDeps);
 		} catch (err) {
@@ -528,7 +533,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	async function handlePut(dc, req, connId) {
 		let workspaceDir, resolved;
 		try {
-			const agentId = req.agentId?.trim?.() || 'main';
+			const agentId = normalizeAgentId(req);
 			workspaceDir = await resolveWorkspace(agentId);
 			resolved = await validatePath(workspaceDir, req.path, pathDeps);
 		} catch (err) {
@@ -541,7 +546,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	async function handlePost(dc, req, connId) {
 		let workspaceDir, dirResolved;
 		try {
-			const agentId = req.agentId?.trim?.() || 'main';
+			const agentId = normalizeAgentId(req);
 			workspaceDir = await resolveWorkspace(agentId);
 			dirResolved = await validatePath(workspaceDir, req.path || '.', pathDeps);
 		} catch (err) {
@@ -774,6 +779,9 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 					if (pendingQueue.length === 0 && !draining) finishUpload();
 				}
 			} else {
+				// done 已收到后到达的迟到 binary 分片必须拒收：否则越界字节会被累加进
+				// receivedBytes 并落盘，让本应 size-mismatch 的传输蒙混过 size 校验、生成错误文件。
+				if (doneReceived) return;
 				// binary 数据帧 — 入队，由 drainLoop 按节奏写入
 				const chunk = event.data;
 				const len = chunk.byteLength ?? chunk.length ?? 0;

package/src/realtime-bridge.js

@@ -959,6 +959,10 @@ export class RealtimeBridge {
 								}
 							}
 							// 终态才清条目；accepted 类中间态保留等下一帧
+							// 故意不把 delete 移到 await sendTo 之后：上游对每个 reqId 只发一帧终态 res、不重发，
+							// await 期间不会有第二帧同 id；万一到来则 miss 路由走 (d) 兜底广播，而 claw 与 userId
+							// 一一绑定（server validateClawOwnership），只会达同一用户自有 tab、原发起 tab 已 resolve
+							// 会忽略——无跨用户泄漏、无副作用，故不防。
 							if (isFinalResMsg(payload)) {
 								this.__dcPendingRequests.delete(payload.id);
 								this.logger.debug?.(`[coclaw/rpc-res-route] remove reqId=${payload.id} reason=final-res`);
@@ -1161,6 +1165,9 @@ export class RealtimeBridge {
 		}
 		// 撞号检测：UUID 全唯一时极小概率，但旧 UI 跨 tab 或 UI bug 可能触发。
 		// 删旧条目让旧响应未来走广播兜底，不主动回错给旧发起方（可能已断）
+		// 故意不再回 DUPLICATE_REQUEST_ID 通知旧发起方：reqId 带 crypto.randomUUID 每连接前缀，跨连接
+		// 撞号密码学不可达；且 claw↔userId 一一绑定，所有 DC peer 同属一用户，撞号即便由未来 UI bug 引入
+		// 也只在该用户自有 tab 间串响应（可重试恢复）、无跨用户泄漏，故不加守卫。
 		const id = payload.id;
 		if (typeof id === 'string' && this.__dcPendingRequests.has(id)) {
 			this.logger.warn?.(`[coclaw] duplicate dc reqId, dropping previous mapping: id=${id}`);
@@ -1429,12 +1436,16 @@ export class RealtimeBridge {
 			// 保留 webrtcPeer / fileHandler 实例供重连后复用，避免雪崩式 PC 重建。
 			const isAuthClose = event?.code === 4001 || event?.code === 4003;
 			if (isAuthClose) {
+				// 先等在飞的 lazy init 落地：close 撞上 __initWebrtcPeer 在飞时 webrtcPeer 仍是 null，
+				// 不等就会漏掉对那个即将诞生的 peer/fileHandler 的清理，留下无主 PC。
+				await this.__webrtcPeerReady?.catch(() => {});
+				// 无条件清空：覆盖 init 已完成但 peer 仍可能为 null 的所有分支（init 失败、无 impl 等）。
+				this.__webrtcPeerReady = null;
 				if (this.webrtcPeer) {
 					try { await this.webrtcPeer.closeAll(); }
 					/* c8 ignore next 3 -- 防御性兜底，werift close 异常时不可崩溃 gateway */
 					catch (e) { this.logger.warn?.(`[coclaw/rtc] closeAll failed: ${e?.message}`); }
 					this.webrtcPeer = null;
-					this.__webrtcPeerReady = null;
 				}
 				if (this.__fileHandler) {
 					this.__fileHandler.cancelCleanup();
@@ -1680,10 +1691,13 @@ export class RealtimeBridge {
 		// 但显式销毁时必须清干净，避免 refresh 后留下指向旧 connId 的孤儿条目。
 		this.__dcPendingRequests.clear();
 		this.__closeGatewayWs();
+		// 镜像 auth-close 守卫：stop()（refresh/restart 会走）撞 __initWebrtcPeer 在飞时
+		// webrtcPeer 仍 null，不等就漏清理那个即将诞生的 peer/fileHandler，refresh/restart 后留无主实例。
+		await this.__webrtcPeerReady?.catch(() => {});
+		this.__webrtcPeerReady = null;
 		if (this.webrtcPeer) {
 			await this.webrtcPeer.closeAll().catch(() => {});
 			this.webrtcPeer = null;
-			this.__webrtcPeerReady = null;
 		}
 		// pion: 关闭 Go 进程（异步，快速）
 		// ndc: 不调用 cleanup()——同步 join native threads 耗时 10s+，进程退出时 OS 回收

package/src/utils/agent-id.js

@@ -0,0 +1,24 @@
+/**
+ * 归一化 RPC / DC 请求里的 agentId。
+ *
+ * 缺省（undefined / null）回落到默认 agent 'main'；空串 / 纯空白同样回落到 'main'（保持
+ * 既有 `X?.agentId?.trim?.() || 'main'` 契约）。但**非字符串**（number / object / bool /
+ * array 等）视为非法输入并响亮抛错——静默落 'main' 会让读站点跨 workspace 泄露文件列表/内容、
+ * 写站点误改默认 agent 的数据。
+ *
+ * 抛出的 Error 带 `.code = 'INVALID_INPUT'`，由各 handler 的外层 catch（index.js 的
+ * respondError / file-manager 的 sendError）浮现为结构化错误码。
+ *
+ * @param {{ agentId?: unknown }} [params] - 请求参数容器（index.js 的 params / handler.js 的 req）
+ * @returns {string} 归一化后的 agentId
+ */
+export function normalizeAgentId(params) {
+	const raw = params?.agentId;
+	if (raw === undefined || raw === null) return 'main';
+	if (typeof raw !== 'string') {
+		const err = new Error('agentId must be a string');
+		err.code = 'INVALID_INPUT';
+		throw err;
+	}
+	return raw.trim() || 'main'; // 空串 / 纯空白 → 'main'
+}

package/src/webrtc/ndc-preloader.js

@@ -213,8 +213,13 @@ export async function preloadNdc(deps = {}) {
 		log(`ndc.loaded platform=${platformKey}`);
 		return { PeerConnection: wrapNdcCredentials(RTCPeerConnection), cleanup, impl: 'ndc' };
 	} catch (err) {
-		// resolvePaths 或其他未预期异常的兜底
-		log(`ndc.fallback reason=unexpected error=${err.message}`);
+		// node-datachannel 依赖已摘除：require.resolve 抛 MODULE_NOT_FOUND 是过渡期
+		// 预期路径，记为 skip 而非误导性的 unexpected。其余才是真正未预期异常。
+		if (err?.code === 'MODULE_NOT_FOUND') {
+			log('ndc.skip reason=ndc-not-installed');
+		} else {
+			log(`ndc.fallback reason=unexpected error=${err.message}`);
+		}
 		return weriftFallback(dynamicImport, log, importTimeout);
 	}
 }

package/src/webrtc/webrtc-peer.js

@@ -208,13 +208,17 @@ export class WebRtcPeer {
 		if (!expectedSession) return;
 		if (this.__sessions.get(connId) !== expectedSession) return;
 		const session = expectedSession;
-		// 同步先 detach handler + clear timer，再 delete map，最后才进入 fire-and-forget 兼容的
-		// 异步收尾（sender/queue/pc.close）。这个顺序保证：(1) pc.close 期间的滞后回调不会
-		// 误改新 session；(2) sessions.get(connId) 在删表后立即返回 undefined，并发 offer 走
-		// 同步段五件事路径而非误以为"close 还在跑"。
+		// 同步段顺序：先 delete map，再 detach handler + clear timer，最后进入 fire-and-forget
+		// 兼容的异步收尾（sender/queue/pc.close）。三步同步、彼此间无 await，外部异步观察者
+		// （并发 offer / pc.close 滞后回调）看到的是整段原子切换，故 delete 提前不改变原有两条
+		// 保证：(1) pc.close 期间的滞后回调不会误改新 session（detach 仍在 pc.close 之前）；
+		// (2) sessions.get(connId) 删表后立即返回 undefined，并发 offer 走替换路径而非误以为
+		// "close 还在跑"。delete 必须排在任何可能抛错的同步步骤之前：closeAll drain 用
+		// per-session catch 吞掉单个 reject，若 detach/clear 在 delete 前抛错，session 会残留在
+		// 表里让 while-drain 死循环、拖挂 gateway——delete 先行使这条不变量无条件成立。
+		this.__sessions.delete(connId);
 		this.__detachPcHandlers(session);
 		this.__clearSessionSyncState(session);
-		this.__sessions.delete(connId);
 		await this.__finalizeSessionAsync(session);
 		this.__remoteLog(`rtc.closed conn=${connId}`);
 		this.logger.info?.(`${this.__rtcTag} [${connId}] closed`);
@@ -236,7 +240,15 @@ export class WebRtcPeer {
 		// 下次复用会建新实例从 false 起。
 		this.__stopping = true;
 		while (this.__sessions.size > 0) {
-			const closing = [...this.__sessions.values()].map((s) => this.closeByConnId(s.connId, s));
+			// per-session catch：单个 closeByConnId reject 不能中断其余 session 的清理，也不能
+			// 打断 while-drain 兜底循环。session 在 closeByConnId 首个 await 前已同步从 Map 删除，
+			// 故失败的 session 不会被下一轮重复处理、也不会无限循环。失败降级为 warn 诊断而非
+			// 静默全吞，保留定位线索。
+			const closing = [...this.__sessions.values()].map((s) =>
+				this.closeByConnId(s.connId, s).catch((err) => {
+					this.logger.warn?.(`${this.__rtcTag} [${s.connId}] closeByConnId failed during closeAll: ${err?.message ?? err}`);
+				}),
+			);
 			await Promise.all(closing);
 		}
 	}
@@ -1028,6 +1040,10 @@ export class WebRtcPeer {
 		// FBQ.init 承担 fs 残留清理（含同 connId 唯一后缀文件，不会撞旧实例）；MemoryQueue.init 是 no-op。
 		// await 期间可能发生 closeByConnId / 同 connId 二次 ondatachannel，因此后面必须身份重核才能赋字段。
 		await queue.init();
+		// 故意不为同 connId 并发 setup 引入 rpcSetupInProgress 协调锁：双 loop / 泄漏被下方身份重核
+		// + 段首 teardown 结构性挡死（rpcChannel 在 ondatachannel 同步路径单调前移：先到者被后到
+		// teardown 收割，后到者 dc 已非 rpcChannel 则自毁返回）；即便分析有误，孤儿也只是空转 idle
+		// 任务 + 少量内存（无 producer → 无 spill → 无 FD），无崩溃 / 丢数据。
 		// 身份重核：init 期间 session 可能被 closeByConnId 从 Map 删除，或被同 connId 二次
 		// ondatachannel 把 rpcChannel 替换成新 dc。任一不再成立都视为 stale，destroy queue 后
 		// 直接退出，绝不污染 session 三件套字段。monitor 自然 GC，无需 summarize（无 drop）。