@coclaw/openclaw-coclaw 0.22.1 → 0.22.2

package/index.js

@@ -9,7 +9,7 @@ import { readConfig } from './src/config.js';
 import { setRuntime } from './src/runtime.js';
 import { createSessionManager } from './src/session-manager/manager.js';
 import { TopicManager } from './src/topic-manager/manager.js';
-import { ChatHistoryManager } from './src/chat-history-manager/manager.js';
+import { ChatHistoryManager, classifyChatHistorySessionKey } from './src/chat-history-manager/manager.js';
 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';
@@ -175,9 +175,12 @@ const plugin = {
 		topicManager.load('main').catch((err) => {
 			logger.warn?.(`[coclaw] topic manager load failed: ${String(err?.message ?? err)}`);
 		});
-		chatHistoryManager.load('main').catch((err) => {
-			logger.warn?.(`[coclaw] chat history manager load failed: ${String(err?.message ?? err)}`);
-		});
+		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)}`);
+			});
 
 		// 追踪 chat 因 reset 产生的 session 流水。双源回调（hook + sessions.changed）共用 helper。
 		// recordSessionTransition 内部已 __reloadFromDisk + mutex，外层无需再 cache.has + load。
@@ -195,37 +198,32 @@ const plugin = {
 		// 该 helper 可直接作为 bridge.onSessionCreated 回调（签名兼容；缺失字段走兜底：
 		// agentId 走 parts[1] fallback、archivedSessionId 走 manager 翻 head 路径）。
 		async function handleSessionCreated({ agentId, sessionKey, sessionId, archivedSessionId }) {
-			if (!sessionKey || !sessionId) {
+			// sessionKey / sessionId 非字符串时（上游 schema 异常）直接当 missing 处理，避免 split 抛 TypeError
+			// 或脏值落盘。manager 内部入口同样会校验（深度防御）。
+			if (typeof sessionKey !== 'string' || !sessionKey
+				|| typeof sessionId !== 'string' || !sessionId) {
 				// 早返值得警惕：上游事件 schema 异常，或 topic（无 sessionKey）误入双源链路。
 				// 打 log + remoteLog 让运维能定位事件源；不影响其他通道。
+				// 日志兼容性：缺失（null/undefined）→ 'null'；其它非字符串类型 → 'invalid'。
+				const formatField = (v) => v == null
+					? 'null'
+					: (typeof v === 'string' ? v : 'invalid');
 				logger.warn?.(
-					`[coclaw] chat history early-return: missing sessionKey/sessionId`,
+					`[coclaw] chat history early-return: missing/invalid sessionKey/sessionId`,
 				);
 				remoteLog(
-					`chat-history.missing-keys sessionKey=${sessionKey ?? 'null'} sessionId=${sessionId ?? 'null'}`,
+					`chat-history.missing-keys sessionKey=${formatField(sessionKey)} sessionId=${formatField(sessionId)}`,
 				);
 				return;
 			}
-			// topic 上游伪造的 explicit fake sessionKey（形态 `agent:<agentId>:explicit:<sid>`）
-			// 不属于 chat 流水范畴：CoClaw 自管 topic 元信息，不应进 chat-history 桶。
-			// 当前 F1 实验已证明该路径不触发本回调，此守卫属防御性兜底。
-			// 前提假设：(a) sessionKey 首段是 `agent`；(b) `explicit` 占第 3 段（即 parts[2]，
-			// 0-indexed 数）。两条同时成立才命中本守卫；若上游 schema 演进（如挪位置 / 增前缀 /
-			// 改首段名），需复评本守卫。
-			const parts = sessionKey.split(':');
-			if (parts[0] === 'agent' && parts[2] === 'explicit') {
-				remoteLog(`chat-history.skip-explicit sessionKey=${sessionKey}`);
-				return;
-			}
-			// subagent 是 OpenClaw 程序自起的子任务 run（mode=run 一次性 / mode=session 持久绑定），
-			// 形态 `agent:<id>:subagent:<uuid>`，嵌套子代理为 `agent:<id>:subagent:<uuid>:subagent:<uuid2>`。
-			// 它不是人机对话流；父 agent 的 transcript 里已含子代理最终输出（作为 user message 回流），
-			// 因此不入 chat-history。
-			// 判定从 parts[2] 起找 'subagent' 段，避免 agentId 恰好叫 'subagent' 时误伤。
-			if (parts[0] === 'agent' && parts.indexOf('subagent', 2) >= 0) {
-				remoteLog(`chat-history.skip-subagent sessionKey=${sessionKey}`);
+			// sessionKey 路由分类（explicit / subagent / cron 跳过，详见 classifyChatHistorySessionKey）。
+			// 守卫必须与启动期对账 reconcileAll 内的守卫一致——共用同一 helper 避免侧门。
+			const cls = classifyChatHistorySessionKey(sessionKey);
+			if (!cls.ok) {
+				remoteLog(`chat-history.skip-${cls.reason} sessionKey=${sessionKey}`);
 				return;
 			}
+			const parts = sessionKey.split(':');
 			let resolvedAgentId = agentId;
 			if (!resolvedAgentId) {
 				resolvedAgentId = (parts[0] === 'agent' && parts[1]) ? parts[1] : 'main';
@@ -251,6 +249,18 @@ const plugin = {
 					archivedSessionId: event?.resumedFrom,
 				});
 			});
+			// cron 顶替主会话 sid 时不走 session_start hook、不广播 sessions.changed reason=create。
+			// cron_changed action=finished 是 cron 完成的可感知通道（v2026.4.29+ 支持，见
+			// openclaw-repo/src/plugins/hook-types.ts）。main 模式 cron 不带 sessionId → 早返天然过滤；
+			// 真触发顶替的"显式 session:<sk>"/"current" 路径 event.sessionId/sessionKey 都齐。
+			api.on('cron_changed', async (event) => {
+				if (event?.action !== 'finished') return;
+				if (!event?.sessionId || !event?.sessionKey) return;
+				await handleSessionCreated({
+					sessionKey: event.sessionKey,
+					sessionId: event.sessionId,
+				});
+			});
 		}
 
 		// bridge 启动/重启的闭包 helper：把 onSessionCreated 接到 handleSessionCreated。

package/package.json

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

@@ -12,6 +12,38 @@ function emptyStore() {
 	return { version: 1 };
 }
 
+/**
+ * 判定 sessionKey 是否应纳入 chat-history 流水。
+ * 不纳入的三类，命中即返回对应 reason：
+ *   - explicit：topic 用的伪 sessionKey，CoClaw 自管不入 chat-history
+ *   - subagent：OpenClaw 程序自起的子任务（含嵌套）
+ *   - cron：isolated cron 跑出的伪 sessionKey（含上游证实主 sessions.json 也会承载此类条目）
+ *
+ * 必须被所有写 chat-history 的入口（事件路径 / 启动对账等）共用，否则启动对账等绕过事件路径
+ * 的入口会把伪 sessionKey 写进 chat-history。
+ *
+ * 非字符串 / 空串 sessionKey 视为非法输入（ok=false reason=null），由 caller 自行决定怎么处理。
+ *
+ * @param {string} sessionKey
+ * @returns {{ ok: boolean, reason: 'explicit' | 'subagent' | 'cron' | null }}
+ */
+export function classifyChatHistorySessionKey(sessionKey) {
+	if (typeof sessionKey !== 'string' || !sessionKey) {
+		return { ok: false, reason: null };
+	}
+	const parts = sessionKey.split(':');
+	if (parts[0] !== 'agent') return { ok: true, reason: null };
+	// 三个跳过类别都用"parts[2] 严格相等"，与上游 routing 一致：
+	// - isCronSessionKey / isSubagentSessionKey 都只在 rest 起始处（即 parts[2]）匹配；
+	// - cron 跑出的子代理（agent:<id>:cron:<jobId>:subagent:<uuid>）上游不视作 subagent，
+	//   由 cron 守卫挡住即可，避免与 IM per-account DM accountId="cron"/"subagent" 形态冲突
+	//   （accountId 仅按 [a-z0-9_-]{1,64} 校验，"cron"/"subagent" 都是合法账户名）。
+	if (parts[2] === 'explicit') return { ok: false, reason: 'explicit' };
+	if (parts[2] === 'cron') return { ok: false, reason: 'cron' };
+	if (parts[2] === 'subagent') return { ok: false, reason: 'subagent' };
+	return { ok: true, reason: null };
+}
+
 /**
  * Chat History 管理器：追踪 chat（sessionKey）下的 session 流水。
  *
@@ -131,7 +163,44 @@ export class ChatHistoryManager {
 
 	async __persist(agentId) {
 		const store = this.__getStore(agentId);
-		await this.__writeJsonFile(this.__historyFilePath(agentId), store);
+		// 自愈守卫：list[1..]（非头位）若仍有未归档项视为脏数据（cron 顶替 / 旧版本写入 / 异常 race
+		// 残留），强制补 archivedAt。放在 __persist 内是为了覆盖所有写盘路径——新增写入点自动受护。
+		this.__sanitizeAllSessionKeys(store, agentId);
+		try {
+			await this.__writeJsonFile(this.__historyFilePath(agentId), store);
+		} catch (err) {
+			// 写盘失败时清除该 agent 的内存 cache：caller 此前在 mutex 内已对 in-place list 做过
+			// unshift / splice / sanitize，这些修改不能随后被下一次"reload 命中 cache 不读盘"
+			// 的路径误持久化。删 cache 让下次操作的 __reloadFromDisk 必须重读磁盘（或 ENOENT 降级
+			// 为 empty store），保证内存与磁盘最终一致。
+			this.__cache.delete(agentId);
+			throw err;
+		}
+	}
+
+	/**
+	 * 遍历 store 内每个 sessionKey 的 list，把 `list[1..]` 中 `!archivedAt` 的项强制
+	 * 写上 `archivedAt = Date.now()`。每修一条同时打本地 warn + remoteLog 暴露信号。
+	 * @param {object} store
+	 * @param {string} agentId
+	 */
+	__sanitizeAllSessionKeys(store, agentId) {
+		if (!store || typeof store !== 'object') return;
+		const now = Date.now();
+		for (const [sessionKey, list] of Object.entries(store)) {
+			if (!Array.isArray(list) || list.length <= 1) continue;
+			for (let i = 1; i < list.length; i++) {
+				const item = list[i];
+				if (!item || typeof item !== 'object' || item.archivedAt) continue;
+				item.archivedAt = now;
+				this.__logger.warn?.(
+					`[coclaw] chat-history sanitize: non-head unarchived entry coerced sessionKey=${sessionKey} sid=${item.sessionId}`,
+				);
+				remoteLog(
+					`chat-history.sanitize-coerce sessionKey=${sessionKey} sid=${item.sessionId} agentId=${agentId}`,
+				);
+			}
+		}
 	}
 
 	/**
@@ -153,7 +222,10 @@ export class ChatHistoryManager {
 	 * @param {{ agentId: string, sessionKey: string, currentSessionId: string, archivedSessionId?: string }} params
 	 */
 	async recordSessionTransition({ agentId, sessionKey, currentSessionId, archivedSessionId }) {
-		if (!sessionKey || !currentSessionId) return;
+		// 严格类型校验：上游 hook payload 异常时（非字符串 sessionId / sessionKey）静默拒绝，避免把脏值落盘。
+		if (typeof sessionKey !== 'string' || !sessionKey) return;
+		if (typeof currentSessionId !== 'string' || !currentSessionId) return;
+		if (typeof archivedSessionId !== 'string' || !archivedSessionId) archivedSessionId = undefined;
 		// 规范化：archivedSessionId 与 currentSessionId 相同属上游契约异常（resumedFrom 不应等于 sessionId），
 		// 丢弃避免在空 list 起手时写出"同 sid 既是头又是归档"的双份记录。打 remoteLog 暴露信号
 		// 让运维捕捉到上游可能的回归——只在真触发时打一次，正常路径噪声为零。
@@ -206,6 +278,42 @@ export class ChatHistoryManager {
 		});
 	}
 
+	/**
+	 * 启动期对账：把 sessions.json 当前 entries 喂进来，对每条调
+	 * recordSessionTransition；现有幂等 + sanitize 自动吞重复。用于覆盖 plugin/gateway
+	 * 重启窗口期 cron 顶替导致的漏归档（cron_changed hook 是主通道，但 gateway 重启不回放
+	 * 已完成的 cron event，靠启动对账兜底当前 sessions.json 的 head sid）。
+	 *
+	 * sessions.json 里可能含 isolated cron / subagent / explicit 形态的 sessionKey
+	 * 条目（上游 run-session-state.ts:57-60 证实 isolated cron 写主 sessions.json），
+	 * 用 classifyChatHistorySessionKey 守卫滤掉避免污染 chat-history。
+	 *
+	 * 单条 entry 抛错 try/catch 隔离，不阻塞后续；caller 已在外层 .catch 兜底。
+	 *
+	 * @param {string} agentId
+	 * @param {{ sessionKey: string, sessionId: string }[]} entries
+	 */
+	async reconcileAll(agentId, entries) {
+		if (!Array.isArray(entries)) return;
+		for (const entry of entries) {
+			if (!entry || typeof entry !== 'object') continue;
+			const { ok } = classifyChatHistorySessionKey(entry.sessionKey);
+			if (!ok) continue;
+			try {
+				await this.recordSessionTransition({
+					agentId,
+					sessionKey: entry.sessionKey,
+					currentSessionId: entry.sessionId,
+				});
+			}
+			catch (err) {
+				this.__logger.warn?.(
+					`[coclaw] chat-history reconcile entry failed sessionKey=${entry.sessionKey}: ${String(err?.message ?? err)}`,
+				);
+			}
+		}
+	}
+
 	/**
 	 * 获取指定 chat 的 session 列表（原始数组：首位可能是未归档的当前活跃 session）。
 	 * 每次调用从磁盘重载，确保跨模块实例一致性

package/src/session-manager/manager.js

@@ -37,6 +37,10 @@ async function safeReaddir(dir) {
 	}
 }
 
+// OpenClaw ISO 时间戳：YYYY-MM-DDTHH-MM-SS[.sss]Z（与 artifacts.ts ARCHIVE_TIMESTAMP_RE 对齐：毫秒可选）
+// 用于过滤 rsync/备份等场景带入的非法后缀（如 .jsonl.reset.<ts>.bak）
+const ARCHIVE_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(?:\.\d{3})?Z$/;
+
 async function safeAccess(filePath) {
 	try { await fsp.access(filePath); return true; }
 	catch (err) {
@@ -101,6 +105,26 @@ export function createSessionManager(options = {}) {
 		return data;
 	}
 
+	// 启动期对账用：直接读 sessions.json 把当前所有 sessionKey -> sessionId 摘出来。
+	// 不扫 transcript 文件 / 不做 stat，因此远比 listAll 轻量；缺/坏文件返回空数组。
+	async function listAllEntries(agentId = 'main') {
+		const idx = await readIndex(agentId);
+		// sessions.json 异常被写成数组时，Object.entries 会生成 "0"/"1" 假键，
+		// 把它们当 sessionKey 喂下游会污染。直接拒绝数组形态，同时打 warn 暴露异常。
+		if (Array.isArray(idx)) {
+			logger.warn?.(`[session-manager] sessions.json for agent=${agentId} is an array, expected object — returning empty entries`);
+			return [];
+		}
+		const out = [];
+		for (const [sessionKey, item] of Object.entries(idx)) {
+			const sid = item?.sessionId;
+			if (typeof sessionKey !== 'string' || !sessionKey) continue;
+			if (typeof sid !== 'string' || !sid) continue;
+			out.push({ sessionKey, sessionId: sid });
+		}
+		return out;
+	}
+
 	async function listAll(params = {}) {
 		const agentId = typeof params.agentId === 'string' && params.agentId.trim() ? params.agentId.trim() : 'main';
 		const limit = clamp(params.limit, 1, 200, 50);
@@ -182,16 +206,24 @@ export function createSessionManager(options = {}) {
 
 	async function resolveTranscriptFile(agentId, sessionId) {
 		const dir = sessionsDir(agentId);
-		// live 文件优先：同一 sessionId 可能同时存在 live 和 reset 文件
+		// live 文件优先：同一 sessionId 可能同时存在 live 和 reset/deleted 归档
 		// （OpenClaw reset 后复用 sessionId），live 代表当前活跃 transcript
 		const livePath = resolveTranscriptPath(sessionId, agentId);
 		if (await safeAccess(livePath)) return livePath;
 
-		const files = await safeReaddir(dir);
+		// .reset.<ts> 与 .deleted.<ts> 都代表 session 的最终态，合并扫描按时间戳取最新
+		// 时间戳是 OpenClaw ISO YYYY-MM-DDTHH-MM-SS[.sss]Z（artifacts.ts 锁住毫秒可选），字典序 = 时间序
 		const resetPrefix = `${sessionId}.jsonl.reset.`;
-		const resetCandidates = [];
+		const deletedPrefix = `${sessionId}.jsonl.deleted.`;
+		const files = await safeReaddir(dir);
+		const candidates = [];
 		for (const name of files) {
-			if (!name.startsWith(resetPrefix)) continue;
+			let archiveStamp;
+			if (name.startsWith(resetPrefix)) archiveStamp = name.slice(resetPrefix.length);
+			else if (name.startsWith(deletedPrefix)) archiveStamp = name.slice(deletedPrefix.length);
+			else continue;
+			// 严格 ISO 时间戳校验，过滤 .jsonl.reset.<ts>.bak 等带尾巴的备份/同步残留
+			if (!ARCHIVE_TS_RE.test(archiveStamp)) continue;
 			const full = nodePath.join(dir, name);
 			let stat;
 			try { stat = await fsp.stat(full); }
@@ -201,21 +233,21 @@ export function createSessionManager(options = {}) {
 				throw err;
 			}
 			/* c8 ignore stop */
-			resetCandidates.push({
+			candidates.push({
 				path: full,
-				archiveStamp: name.slice(resetPrefix.length),
+				archiveStamp,
 				updatedAt: stat.mtimeMs,
 			});
 		}
-		resetCandidates.sort((a, b) => {
+		candidates.sort((a, b) => {
 			if (a.archiveStamp !== b.archiveStamp) {
 				return b.archiveStamp.localeCompare(a.archiveStamp);
 			}
-			/* c8 ignore next -- 同一 sessionId 的 reset 文件不会有相同 archiveStamp */
+			/* c8 ignore next -- 同 sessionId 同 archiveStamp 的归档实测 0 case */
 			return b.updatedAt - a.updatedAt;
 		});
-		if (resetCandidates.length > 0) {
-			return resetCandidates[0].path;
+		if (candidates.length > 0) {
+			return candidates[0].path;
 		}
 		return null;
 	}
@@ -272,6 +304,7 @@ export function createSessionManager(options = {}) {
 	/**
 	 * 按 sessionId 获取消息，返回完整 JSONL 行级结构。
 	 * 只返回 type==="message" 且有合法 message.role 的行。
+	 * limit 语义：不传/null/非 number/NaN/Infinity/<1 → 返回全部；>=1 的有限 number → 取最后 Math.trunc(limit) 条。无默认/最大值。
 	 * @param {{ sessionId: string, agentId?: string, limit?: number }} params
 	 * @returns {Promise<{ messages: object[] }>}
 	 */
@@ -279,7 +312,10 @@ export function createSessionManager(options = {}) {
 		const agentId = typeof params.agentId === 'string' && params.agentId.trim() ? params.agentId.trim() : 'main';
 		const sessionId = typeof params.sessionId === 'string' ? params.sessionId.trim() : '';
 		if (!sessionId) throw new Error('sessionId required');
-		const limit = clamp(params.limit, 1, 500, 500);
+		// limit 类型严格：只接受 number 且 >= 1。string/bool/array 走非 number 分支被拒，
+		// 0 / 负数 / NaN / Infinity / (0,1) 区间也都视为"不限"——(0,1) 不视为不限的话 Math.trunc 后会变 0、slice(-0) 退化为全部
+		const useLimit = typeof params.limit === 'number' && Number.isFinite(params.limit) && params.limit >= 1;
+		const limitNum = useLimit ? Math.trunc(params.limit) : 0;
 		const file = await resolveTranscriptFile(agentId, sessionId);
 		if (!file) {
 			return { messages: [] };
@@ -300,10 +336,9 @@ export function createSessionManager(options = {}) {
 				logger.warn?.(`[session-manager] bad json line skipped: ${String(err?.message ?? err)}`);
 			}
 		}
-		// 取最后 limit 条
-		const sliced = messages.length > limit ? messages.slice(-limit) : messages;
+		const sliced = (useLimit && messages.length > limitNum) ? messages.slice(-limitNum) : messages;
 		return { messages: sliced };
 	}
 
-	return { listAll, get, getById };
+	return { listAll, listAllEntries, get, getById };
 }