@coclaw/openclaw-coclaw 0.4.1 → 0.5.1

package/index.js

@@ -6,10 +6,11 @@ import { registerCoclawCli } from './src/cli-registrar.js';
 import { resolveErrorMessage } from './src/common/errors.js';
 import { notBound, bindOk, unbindOk } from './src/common/messages.js';
 import { coclawChannelPlugin } from './src/channel-plugin.js';
-import { ensureAgentSession, gatewayAgentRpc, restartRealtimeBridge, stopRealtimeBridge } from './src/realtime-bridge.js';
+import { ensureAgentSession, gatewayAgentRpc, restartRealtimeBridge, stopRealtimeBridge, waitForSessionsReady } from './src/realtime-bridge.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 { 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';
@@ -78,13 +79,40 @@ const plugin = {
 		const logger = api?.logger ?? console;
 		const manager = createSessionManager({ logger });
 		const topicManager = new TopicManager({ logger });
+		const chatHistoryManager = new ChatHistoryManager({ logger });
 
-		// 懒加载 topic 数据（best-effort，不阻断注册）
+		// 懒加载 topic / chat history 数据（best-effort，不阻断注册）
 		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)}`);
+		});
 
 		api.registerChannel({ plugin: coclawChannelPlugin });
+
+		// 追踪 chat 因 reset 产生的孤儿 session
+		if (typeof api.on === 'function') {
+			api.on('session_start', async (event, ctx) => {
+				if (!event.resumedFrom) return; // 首次创建，无前任
+				const agentId = ctx?.agentId ?? 'main';
+				const sessionKey = event.sessionKey;
+				if (!sessionKey) return;
+				try {
+					if (!chatHistoryManager.__cache.has(agentId)) {
+						await chatHistoryManager.load(agentId);
+					}
+					await chatHistoryManager.recordArchived({
+						agentId,
+						sessionKey,
+						sessionId: event.resumedFrom,
+					});
+				} catch (err) {
+					logger.warn?.(`[coclaw] chat history record failed: ${String(err?.message ?? err)}`);
+				}
+			});
+		}
+
 		api.registerService({
 			id: 'coclaw-realtime-bridge',
 			async start() {
@@ -139,8 +167,9 @@ const plugin = {
 
 		api.registerGatewayMethod('coclaw.info', async ({ respond }) => {
 			try {
+				await waitForSessionsReady();
 				const version = await getPluginVersion();
-				respond(true, { version, capabilities: ['topics'] });
+				respond(true, { version, capabilities: ['topics', 'chatHistory'] });
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -270,6 +299,42 @@ const plugin = {
 			}
 		});
 
+		api.registerGatewayMethod('coclaw.chatHistory.list', async ({ params, respond }) => {
+			try {
+				const agentId = params?.agentId?.trim?.() || 'main';
+				const sessionKey = params?.sessionKey?.trim?.();
+				if (!sessionKey) {
+					respond(false, { error: 'sessionKey required' });
+					return;
+				}
+				if (!chatHistoryManager.__cache.has(agentId)) {
+					await chatHistoryManager.load(agentId);
+				}
+				const result = await chatHistoryManager.list({ agentId, sessionKey });
+				respond(true, result);
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		// TODO: coclaw.topics.getHistory 未来可废弃，UI 改用 coclaw.sessions.getById
+		api.registerGatewayMethod('coclaw.sessions.getById', ({ params, respond }) => {
+			try {
+				const sessionId = params?.sessionId?.trim?.();
+				if (!sessionId) {
+					respond(false, { error: 'sessionId required' });
+					return;
+				}
+				const agentId = params?.agentId?.trim?.() || 'main';
+				const limit = params?.limit;
+				respond(true, manager.getById({ agentId, sessionId, limit }));
+			}
+			catch (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.4.1",
+  "version": "0.5.1",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",

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

@@ -0,0 +1,171 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import nodePath from 'node:path';
+
+import { atomicWriteJsonFile } from '../utils/atomic-write.js';
+import { createMutex } from '../utils/mutex.js';
+
+const HISTORY_FILE = 'coclaw-chat-history.json';
+
+function emptyStore() {
+	return { version: 1 };
+}
+
+/**
+ * Chat History 管理器：追踪 chat（sessionKey）因 reset 产生的孤儿 session。
+ *
+ * 每个 agentId 对应一份 coclaw-chat-history.json，按需懒加载到内存。
+ * 写操作通过 mutex + atomicWriteJsonFile 保证一致性。
+ *
+ * 文件结构示例：
+ * {
+ *   "version": 1,
+ *   "agent:main:main": [
+ *     { "sessionId": "xxx", "archivedAt": 1742003000000 }
+ *   ]
+ * }
+ */
+export class ChatHistoryManager {
+	/**
+	 * @param {object} [opts]
+	 * @param {string} [opts.rootDir] - agents 根目录，默认 ~/.openclaw/agents
+	 * @param {object} [opts.logger]
+	 * @param {Function} [opts.readFile] - 测试注入
+	 * @param {Function} [opts.writeJsonFile] - 测试注入
+	 */
+	constructor(opts = {}) {
+		this.__rootDir = opts.rootDir ?? nodePath.join(os.homedir(), '.openclaw', 'agents');
+		this.__logger = opts.logger ?? console;
+		this.__readFile = opts.readFile ?? fs.readFile;
+		this.__writeJsonFile = opts.writeJsonFile ?? atomicWriteJsonFile;
+		// 内存缓存：agentId -> { version, [sessionKey]: [...] }
+		this.__cache = new Map();
+		// 每个 agentId 一把锁
+		this.__mutexes = new Map();
+		// 进行中的 load Promise（防止并发 load 竞态）
+		this.__loadingPromises = new Map();
+	}
+
+	__sessionsDir(agentId) {
+		return nodePath.join(this.__rootDir, agentId, 'sessions');
+	}
+
+	__historyFilePath(agentId) {
+		return nodePath.join(this.__sessionsDir(agentId), HISTORY_FILE);
+	}
+
+	__mutex(agentId) {
+		if (!this.__mutexes.has(agentId)) {
+			this.__mutexes.set(agentId, createMutex());
+		}
+		return this.__mutexes.get(agentId);
+	}
+
+	/**
+	 * 从磁盘加载指定 agent 的 chat history 到内存。
+	 * @param {string} agentId
+	 */
+	async load(agentId) {
+		if (this.__cache.has(agentId)) return;
+		const pending = this.__loadingPromises.get(agentId);
+		if (pending) return pending;
+
+		const p = this.__doLoad(agentId).finally(() => {
+			this.__loadingPromises.delete(agentId);
+		});
+		this.__loadingPromises.set(agentId, p);
+		return p;
+	}
+
+	async __doLoad(agentId) {
+		const filePath = this.__historyFilePath(agentId);
+		try {
+			const raw = await this.__readFile(filePath, 'utf8');
+			const data = JSON.parse(raw);
+			if (data && typeof data === 'object' && typeof data.version === 'number') {
+				this.__cache.set(agentId, data);
+				return;
+			}
+		} catch {
+			// 文件不存在或解析失败，初始化空数据
+		}
+		this.__cache.set(agentId, emptyStore());
+	}
+
+	__ensureLoaded(agentId) {
+		/* c8 ignore start -- recordArchived/list 均先 __reloadFromDisk，此分支为防御性守卫 */
+		if (!this.__cache.has(agentId)) {
+			throw new Error(`ChatHistoryManager: agent "${agentId}" not loaded, call load() first`);
+		}
+		/* c8 ignore stop */
+	}
+
+	__getStore(agentId) {
+		this.__ensureLoaded(agentId);
+		return this.__cache.get(agentId);
+	}
+
+	async __persist(agentId) {
+		const store = this.__getStore(agentId);
+		await this.__writeJsonFile(this.__historyFilePath(agentId), store);
+	}
+
+	/**
+	 * 记录一个被抛弃的孤儿 session
+	 * @param {{ agentId: string, sessionKey: string, sessionId: string }} params
+	 */
+	async recordArchived({ agentId, sessionKey, sessionId }) {
+		if (!sessionKey || !sessionId) return;
+		await this.__mutex(agentId).withLock(async () => {
+			// 从磁盘重载确保最新状态：list() 无锁覆写 __cache 可能导致缓存过期
+			await this.__reloadFromDisk(agentId);
+			const store = this.__getStore(agentId);
+			if (!Array.isArray(store[sessionKey])) {
+				store[sessionKey] = [];
+			}
+			// 去重：同一 sessionId 不重复记录
+			if (store[sessionKey].some((r) => r.sessionId === sessionId)) return;
+			// 头部插入（最近的在前）
+			store[sessionKey].unshift({
+				sessionId,
+				archivedAt: Date.now(),
+			});
+			await this.__persist(agentId);
+		});
+	}
+
+	/**
+	 * 获取指定 chat 的孤儿 session 列表。
+	 * 每次调用从磁盘重载，确保跨模块实例一致性
+	 * （OpenClaw 的 hook 和 gateway method 可能在不同 ESM 模块实例中运行）。
+	 * @param {{ agentId: string, sessionKey: string }} params
+	 * @returns {Promise<{ history: { sessionId: string, archivedAt: number }[] }>}
+	 */
+	async list({ agentId, sessionKey }) {
+		await this.__reloadFromDisk(agentId);
+		const store = this.__getStore(agentId);
+		const history = Array.isArray(store[sessionKey]) ? store[sessionKey] : [];
+		return { history };
+	}
+
+	/**
+	 * 从磁盘重载指定 agent 的数据到内存（覆盖缓存）
+	 * @param {string} agentId
+	 */
+	async __reloadFromDisk(agentId) {
+		const filePath = this.__historyFilePath(agentId);
+		try {
+			const raw = await this.__readFile(filePath, 'utf8');
+			const data = JSON.parse(raw);
+			if (data && typeof data === 'object' && typeof data.version === 'number') {
+				this.__cache.set(agentId, data);
+				return;
+			}
+		} catch {
+			// 文件不存在或解析失败
+		}
+		if (!this.__cache.has(agentId)) {
+			this.__cache.set(agentId, emptyStore());
+		}
+	}
+}

package/src/realtime-bridge.js

@@ -479,7 +479,7 @@ export class RealtimeBridge {
 					this.gatewayReady = true;
 					this.__logDebug(`gateway connect ok <- id=${payload.id}`);
 					this.gatewayConnectReqId = null;
-					void this.__ensureAllAgentSessions();
+					this.__ensureSessionsPromise = this.__ensureAllAgentSessions();
 				}
 				else {
 					this.gatewayReady = false;
@@ -814,6 +814,11 @@ export async function stopRealtimeBridge() {
 	singleton = null; // 置 null 后须通过 restartRealtimeBridge 重建
 }
 
+export async function waitForSessionsReady() {
+	if (!singleton?.__ensureSessionsPromise) return;
+	await singleton.__ensureSessionsPromise;
+}
+
 export async function ensureAgentSession(agentId) {
 	if (!singleton) {
 		return { ok: false, error: 'bridge_not_started' };

package/src/session-manager/manager.js

@@ -1,4 +1,3 @@
-/* c8 ignore start */
 import fs from 'node:fs';
 import os from 'node:os';
 import nodePath from 'node:path';
@@ -25,6 +24,7 @@ const CRON_TIME_UTC_RE = /(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2})\s+UTC/;
 function formatCronTime(matchedText) {
 	const m = matchedText.match(CRON_TIME_UTC_RE);
 	if (!m) return '';
+	/* c8 ignore start -- Date 构造在正则已校验的输入下不会抛出 */
 	try {
 		const d = new Date(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:00Z`);
 		if (!Number.isFinite(d.getTime())) return '';
@@ -38,6 +38,7 @@ function formatCronTime(matchedText) {
 	catch {
 		return '';
 	}
+	/* c8 ignore stop */
 }
 
 function stripLeadingPattern(text, re) {
@@ -50,6 +51,7 @@ function stripLeadingPattern(text, re) {
 }
 
 function cleanTitleText(text) {
+	/* c8 ignore next */
 	if (!text) return '';
 	let s = stripLeadingPattern(text, INBOUND_META_RE);
 	s = stripLeadingPattern(s, OPERATOR_POLICY_RE);
@@ -127,10 +129,12 @@ function truncateTitle(text, maxLen = DERIVED_TITLE_MAX_LEN) {
 
 function extractRawTextFromContent(content) {
 	if (typeof content === 'string') return content;
+	/* c8 ignore next */
 	if (!Array.isArray(content)) return undefined;
 	for (const part of content) {
 		if (!part || typeof part !== 'object') continue;
 		if (part.type !== 'text') continue;
+		/* c8 ignore next */
 		if (typeof part.text !== 'string') continue;
 		if (part.text.trim()) return part.text;
 	}
@@ -149,6 +153,7 @@ function findFirstUserRawText(filePath, logger) {
 			if (raw && raw.trim()) return raw;
 		}
 		catch (err) {
+			/* c8 ignore next -- ?./?? fallback */
 			logger.warn?.(`[session-manager] bad json line skipped when deriving title: ${String(err?.message ?? err)}`);
 		}
 	}
@@ -161,15 +166,18 @@ function deriveTitle(filePath, logger) {
 	const cleaned = cleanTitleText(rawText);
 	if (!cleaned) return undefined;
 	const normalized = cleaned.replace(/\s+/g, ' ').trim();
+	/* c8 ignore next */
 	if (!normalized) return undefined;
 	return truncateTitle(normalized, DERIVED_TITLE_MAX_LEN);
 }
 
 export function createSessionManager(options = {}) {
 	const rootDir = options.rootDir ?? nodePath.join(os.homedir(), '.openclaw', 'agents');
+	/* c8 ignore next */
 	const logger = options.logger ?? console;
 
 	function sessionsDir(agentId = 'main') {
+		/* c8 ignore next */
 		const aid = typeof agentId === 'string' && agentId.trim() ? agentId.trim() : 'main';
 		return nodePath.join(rootDir, aid, 'sessions');
 	}
@@ -177,6 +185,7 @@ export function createSessionManager(options = {}) {
 	function readIndex(agentId = 'main') {
 		const file = nodePath.join(sessionsDir(agentId), 'sessions.json');
 		const data = readJsonSafe(file, {});
+		/* c8 ignore next */
 		if (!data || typeof data !== 'object') return {};
 		return data;
 	}
@@ -225,6 +234,7 @@ 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,
@@ -289,6 +299,7 @@ export function createSessionManager(options = {}) {
 				if (a.archiveStamp !== b.archiveStamp) {
 					return b.archiveStamp.localeCompare(a.archiveStamp);
 				}
+				/* c8 ignore next -- 同一 sessionId 的 reset 文件不会有相同 archiveStamp */
 				return b.updatedAt - a.updatedAt;
 			});
 		if (resetCandidates.length > 0) {
@@ -314,10 +325,12 @@ 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,
@@ -329,6 +342,40 @@ export function createSessionManager(options = {}) {
 		};
 	}
 
-	return { listAll, get };
+	/**
+	 * 按 sessionId 获取消息，返回完整 JSONL 行级结构。
+	 * 只返回 type==="message" 且有合法 message.role 的行。
+	 * @param {{ sessionId: string, agentId?: string, limit?: number }} params
+	 * @returns {{ messages: object[] }}
+	 */
+	function getById(params = {}) {
+		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);
+		const file = resolveTranscriptFile(agentId, sessionId);
+		if (!file) {
+			return { messages: [] };
+		}
+
+		const messages = [];
+		for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean)) {
+			try {
+				const row = JSON.parse(line);
+				if (row?.type !== 'message') continue;
+				const msg = row?.message;
+				if (!msg || typeof msg !== 'object' || !msg.role) continue;
+				messages.push(row);
+			}
+			catch (err) {
+				/* c8 ignore next -- ?./?? fallback */
+				logger.warn?.(`[session-manager] bad json line skipped: ${String(err?.message ?? err)}`);
+			}
+		}
+		// 取最后 limit 条
+		const sliced = messages.length > limit ? messages.slice(-limit) : messages;
+		return { messages: sliced };
+	}
+
+	return { listAll, get, getById };
 }
-/* c8 ignore stop */