@coclaw/openclaw-coclaw 0.22.2 → 0.22.3

package/index.js

@@ -23,6 +23,15 @@ import { registerModelDefaultHandlers } from './src/model-default/index.js';
 import { getPluginVersion, __resetPluginVersion } from './src/plugin-version.js';
 export { getPluginVersion, __resetPluginVersion };
 
+// 收纳 register() 在 full 模式启动的 fire-and-forget 初始化任务（topic / chat-history
+// load + reconcile）的完成信号。默认 Promise.resolve() 让 awaitPluginInit() 在 register
+// 未跑或非 full 模式时立即返回。每次 full register 都重置——多次 register 互不串扰。
+let __pluginInitDone = Promise.resolve();
+
+export function awaitPluginInit() {
+	return __pluginInitDone;
+}
+
 // 侧门注册表观测：patch OpenClaw embeddedRunState.activeRuns 的 set/delete，
 // 用于跟踪 sessionId 何时注册/注销（agent 取消流程实际读取的就是这张表）。
 // OpenClaw 侧门形状变化时（缺失 / 抛异常），通过 remoteLog 上报为升级契约变更的早期信号。
@@ -171,16 +180,19 @@ const plugin = {
 		const topicManager = new TopicManager({ logger });
 		const chatHistoryManager = new ChatHistoryManager({ logger });
 
-		// 懒加载 topic / chat history 数据（best-effort，不阻断注册）
-		topicManager.load('main').catch((err) => {
+		// 懒加载 topic / chat history 数据（best-effort，不阻断注册）。
+		// 两条 promise 收成一个 bundle 挂到 __pluginInitDone，让测试 / 关心 done 时机的
+		// caller 通过 awaitPluginInit() 显式等待——生产 gateway 不调即原 fire-and-forget 语义
+		const topicLoadP = topicManager.load('main').catch((err) => {
 			logger.warn?.(`[coclaw] topic manager load failed: ${String(err?.message ?? err)}`);
 		});
-		chatHistoryManager.load('main')
+		const chatHistoryLoadP = chatHistoryManager.load('main')
 			.then(() => manager.listAllEntries('main'))
 			.then((entries) => chatHistoryManager.reconcileAll('main', entries))
 			.catch((err) => {
 				logger.warn?.(`[coclaw] chat history manager load/reconcile failed: ${String(err?.message ?? err)}`);
 			});
+		__pluginInitDone = Promise.all([topicLoadP, chatHistoryLoadP]);
 
 		// 追踪 chat 因 reset 产生的 session 流水。双源回调（hook + sessions.changed）共用 helper。
 		// recordSessionTransition 内部已 __reloadFromDisk + mutex，外层无需再 cache.has + load。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.22.2",
+  "version": "0.22.3",
   "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

@@ -76,7 +76,8 @@ export class ChatHistoryManager {
 	constructor(opts = {}) {
 		this.__resolveSessionsDir = opts.resolveSessionsDir ?? agentSessionsDir;
 		this.__logger = opts.logger ?? console;
-		/* c8 ignore next 2 -- ?? fallback：测试始终注入 */
+		// readFile / writeJsonFile DI 注入点用于精细 mock；不注入时默认走 fs.readFile + atomicWriteJsonFile。
+		// 默认构造路径由"通过 setRuntime 端到端落盘"测试覆盖。
 		this.__readFile = opts.readFile ?? fs.readFile;
 		this.__writeJsonFile = opts.writeJsonFile ?? atomicWriteJsonFile;
 		// 内存缓存：agentId -> { version, [sessionKey]: [...] }

package/src/file-manager/handler.js

@@ -796,8 +796,10 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				// done 已收到但 drain 未完成 — finishUpload 中会检测 dcClosed 并清理 tmp
 				if (!finishing) finishUpload();
 			} else {
+				// 等 ws 关闭后再 unlink——fopen 未完成时直接 safeUnlink 会扑空被吞，
+				// 随后 fopen 完成创建文件却没人清，留下孤儿 tmp
+				ws.on('close', () => safeUnlink(tmpPath));
 				ws.destroy();
-				safeUnlink(tmpPath);
 				const elapsed = Date.now() - startTime;
 				remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
 				log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
@@ -810,8 +812,9 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			wsError = true;
 			draining = false;
 			pendingQueue.length = 0;
+			// 同上：等 ws 关闭后再 unlink，避开 fopen-vs-unlink race
+			ws.on('close', () => safeUnlink(tmpPath));
 			ws.destroy();
-			safeUnlink(tmpPath);
 			const elapsed = Date.now() - startTime;
 			/* c8 ignore next -- ?? fallback for non-Error throw */
 			const errMsg = err?.message ?? String(err);

package/src/model-default/index.js

@@ -17,6 +17,9 @@ import { buildModelDefaultHandlers } from './handlers.js';
 import { mainAgentDir } from '../claw-paths.js';
 import { getClawConfig } from '../claw-config.js';
 
+// link-UNSAFE：模块级 dedup 缓存。`--link` 模式下两实例各自 lazy-load 一次
+// SDK（结果一致、运行无伤但去重失效）。当前仅 RPC handler 走该路径——
+// 不要在 hook 回调里访问本模块的 export。详见 docs/module-boundaries.md。
 let _configMutationP;
 let _modelsP;
 let _providerAuthP;

package/src/provider-auth/index.js

@@ -10,6 +10,9 @@
 import { buildProviderAuthHandlers } from './handlers.js';
 import { mainAgentDir } from '../claw-paths.js';
 
+// link-UNSAFE：模块级 dedup 缓存。`--link` 模式下两实例各自 lazy-load 一次
+// SDK（结果一致、运行无伤但去重失效）。当前仅 RPC handler 走该路径——
+// 不要在 hook 回调里访问本模块的 export。详见 docs/module-boundaries.md。
 let _sdkPromise;
 
 // 默认 loader 仅作 fallback：生产路径必须由入口（plugins/openclaw/index.js）注入 loadSdk，

package/src/realtime-bridge.js

@@ -1717,6 +1717,13 @@ export class RealtimeBridge {
 //   restart(opts) — 无论当前状态，确保 bridge 以给定 opts 运行（幂等）
 //   stop()        — 停止并销毁 singleton
 // 调用方无需感知 singleton 是否为 null，选"要运行"或"要停止"即可。
+//
+// link-UNSAFE 警告：以下 singleton 状态与所有读 singleton 的 export（restart /
+// stop / waitForSessionsReady / ensureAgentSession / gatewayAgentRpc /
+// broadcastPluginEvent）在 `--link` 安装模式下，hook 路径与 RPC 路径可能拿
+// 到不同 ESM 模块实例 → 两份独立 singleton。**不要在 api.on(...) hook 回调内
+// 调用本文件的任何 export**。hook 内若需触发 bridge 副作用，请走 RPC
+// （api.callGatewayMethod('coclaw.xxx', ...)）。详见 docs/module-boundaries.md。
 
 let singleton = null;
 

package/src/remote-log.js

@@ -3,6 +3,11 @@
  *
  * 将诊断日志缓冲并通过 WS 通道推送到 CoClaw server。
  * 单例模式——各模块直接 import { remoteLog } 使用。
+ *
+ * link-UNSAFE：buffer / sender / flushing 都是模块级状态。`--link` 模式下
+ * hook 实例可能从未被 setSender 注入 → hook 路径调 remoteLog 会落到没装
+ * sender 的实例 → 静默丢日志。**不要在 hook 回调内调用 remoteLog**；
+ * 要发就用 hook 入参里的 logger。详见 docs/module-boundaries.md。
  */
 
 const MAX_BUFFER = 1000;

package/src/runtime.js

@@ -1,4 +1,8 @@
-// runtime 单例：在 plugin 模式下由 register() 注入
+// runtime 单例：在 plugin 模式下由 register() 注入。
+// link-UNSAFE：`--link` 安装模式下 hook 与 RPC handler 可能跑在不同 ESM 实例 →
+// 两份独立 runtime；hook 实例从未被 setRuntime → getRuntime() 返回 null。
+// **不要在 hook 回调内调用 getRuntime()**——hook 入参 `api` 已带 runtime。
+// 详见 docs/module-boundaries.md。
 let runtime = null;
 
 export function setRuntime(rt) {

package/src/session-manager/manager.js

@@ -83,24 +83,22 @@ function shouldReplaceByPriority(current, next) {
 }
 
 export function createSessionManager(options = {}) {
-	/* c8 ignore next */
 	const logger = options.logger ?? console;
 	const resolveSessionsDir = options.resolveSessionsDir ?? agentSessionsDir;
 	const resolveStorePath = options.resolveStorePath ?? sessionStorePath;
 	const resolveTranscriptPath = options.resolveTranscriptPath ?? sessionTranscriptPath;
 
 	function sessionsDir(agentId = 'main') {
-		/* c8 ignore next */
 		const aid = typeof agentId === 'string' && agentId.trim() ? agentId.trim() : 'main';
 		return resolveSessionsDir(aid);
 	}
 
 	async function readIndex(agentId = 'main') {
-		/* c8 ignore next */
 		const aid = typeof agentId === 'string' && agentId.trim() ? agentId.trim() : 'main';
 		const file = resolveStorePath(aid);
 		const data = await readJsonSafe(file, {});
-		/* c8 ignore next */
+		// readJsonSafe 抛错时返回 {}（已是 object），此处兜底 sessions.json 内容是合法 JSON
+		// 但非 object（number / string / boolean / null / array 由下游 listAllEntries 单独处理）
 		if (!data || typeof data !== 'object') return {};
 		return data;
 	}
@@ -176,7 +174,6 @@ export function createSessionManager(options = {}) {
 		// 补充 sessions.json 中有索引但无 transcript 文件的 session（如 reset 后未对话、新建 session）
 		for (const [sessionKey, entry] of Object.entries(index)) {
 			const sid = entry?.sessionId;
-			/* c8 ignore next -- !sid 防御性检查 */
 			if (!sid || grouped.has(sid)) continue;
 			grouped.set(sid, {
 				sessionId: sid,
@@ -184,7 +181,7 @@ export function createSessionManager(options = {}) {
 				indexed: true,
 				archiveType: 'live',
 				fileName: null,
-				/* c8 ignore next -- ?? fallback */
+				// entry.updatedAt 缺失或非数字时回落 0；UI 端按 updatedAt 排序时无 transcript 项排到末位
 				updatedAt: entry.updatedAt ?? 0,
 				size: 0,
 			});
@@ -284,12 +281,10 @@ export function createSessionManager(options = {}) {
 				all.push(JSON.parse(line));
 			}
 			catch (err) {
-				/* c8 ignore next -- ?./?? fallback */
 				logger.warn?.(`[session-manager] bad json line skipped: ${String(err?.message ?? err)}`);
 			}
 		}
 		const messages = all.slice(cursor, cursor + limit);
-		/* c8 ignore next */
 		const nextCursor = cursor + limit < all.length ? String(cursor + limit) : null;
 		return {
 			agentId,
@@ -332,7 +327,6 @@ export function createSessionManager(options = {}) {
 				messages.push(row);
 			}
 			catch (err) {
-				/* c8 ignore next -- ?./?? fallback */
 				logger.warn?.(`[session-manager] bad json line skipped: ${String(err?.message ?? err)}`);
 			}
 		}

package/src/webrtc/webrtc-peer.js

@@ -996,9 +996,10 @@ export class WebRtcPeer {
 		// 'fbq' 模式下若 queueDir 不可用则降级到 mem，避免阻塞装配。
 		// 同 connId race 隔离（决策 4）：FBQ id 加唯一后缀 ${connId}-${ts}-${nonce}，
 		// 让新旧实例文件名物理不同，destroy/init 期间互不踩踏。MemoryQueue 不碰 fs，无此需求。
-		// connId 字符集（PRE-EXISTING 契约）：上游 server 分配 connId 形如 `c_<digits>`；
-		// FBQ / MemoryQueue 共用 `^[A-Za-z0-9._-]+$` 校验。若 server 将来引入特殊字符，
-		// queue 构造会抛 TypeError，由 __setupDataChannel 的 .catch 兜底 warn——非 B9b 引入。
+		// connId 字符集契约：FBQ / MemoryQueue 共用 `^[A-Za-z0-9._-]+$` 校验。
+		// 上游 server 分配 connId 形如 `c_<digits>` 符合契约；若 server 引入特殊字符，
+		// queue 构造抛 TypeError，由 __setupDataChannel 的 .catch 兜底 warn。
+		// 完整契约 / 违反后果 / 修复方向见 docs/connid-contract.md
 		const useFbq = this.__rpcQueueImpl === 'fbq' && !!this.__queueDir;
 		const fbqFallback = !useFbq && this.__rpcQueueImpl === 'fbq';
 		const queue = useFbq