lightclawbot 1.2.0-beta.3 → 1.2.5

package/dist/src/socket/chat.js

@@ -0,0 +1,257 @@
+/**
+ * LightClaw — Chat（会话元信息）处理器
+ *
+ * 收敛 EVENT_CHAT_REQUEST 各子类型的处理逻辑，与 handlers.ts 中的
+ * 消息 / 历史 / Agents 等事件处理保持平级解耦，避免 handlers.ts 膨胀。
+ *
+ * 涉及的持久化文件：
+ *   `~/.openclaw/agents/<agentId>/chats/<userId>/chats.json`
+ *    └─ 以 ChatMeta[] 形式存储该用户在该 Agent 下的会话元信息列表
+ *        （不包含消息正文，正文以 jsonl 形式另外存储）
+ *
+ * 四个处理器（对应 data.type）：
+ *   - list：   读取 chats.json 返回 { chats }；文件不存在 / 解析失败
+ *             时返回空数组，不抛错，避免阻塞前端。
+ *   - create： 新建一条会话元数据，chatId = randomUUID()，插入列表最前。
+ *             文件或目录不存在时由 writeChatsFile 递归创建。
+ *   - update： 根据 chatId 修改 title（并置 titleLocked=true + 刷新 updatedAt）；
+ *             文件或条目不存在时回 error，不隐式创建。
+ *   - delete： 根据 chatId 从列表剔除，原子写回；文件或条目不存在时回 error。
+ *
+ * 全部响应均通过 EVENT_CHAT_RESPONSE + ReliableEmitter 发出（带 ACK + 重试）。
+ * 错误处理统一走 createChatErrorSender 生成的回调，保证日志 / 响应结构一致。
+ */
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import { CHANNEL_KEY, EVENT_CHAT_RESPONSE } from '../config.js';
+import { generateMsgId } from '../dedup.js';
+import { readChatsFile, readChatsFileOrInitDefault, resolveChatsFilePath, writeChatsFile } from '../utils/common.js';
+/**
+ * 生成统一的错误响应发送器。
+ *
+ * 背景：list / create / update / delete 四个 handler 的错误处理结构完全一致：
+ *   1. 打同一格式日志：`[CHANNEL_KEY] Chat <type> error: <msg>`
+ *   2. 通过 EVENT_CHAT_RESPONSE 回同一组基础字段（msgId/from/to/type/agentId/error）
+ * 仅差异项：
+ *   - `type` 不同
+ *   - `chatId` 是否需要回显（update/delete 需要）
+ *   - list 出错时前端期望一个兜底的空列表 `chats: []`，避免 UI 处理 undefined
+ *
+ * 因此将其封装为模块级工厂，handler 开头调用一次即可，避免重复闭包。
+ *
+ * @param ctx   共享上下文（见 ChatErrorSenderContext）
+ * @param extra 额外字段（如 `chatId`、兜底 `chats: []`），会与 error 一并合并到响应体
+ * @returns     ChatErrorSender — 调用时传入错误信息即可
+ */
+function createChatErrorSender(ctx, extra = {}) {
+    const { responseMsgId, botClientId, userId, agentId, type, reliableEmitter, log } = ctx;
+    return (error) => {
+        log?.error(`[${CHANNEL_KEY}] Chat ${type} error: ${error}`);
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type,
+            agentId,
+            timestamp: Date.now(),
+            ...extra,
+            error,
+        }, responseMsgId);
+    };
+}
+/**
+ * 处理 EVENT_CHAT_REQUEST(type=list)：返回该用户在指定 Agent 下的会话列表。
+ *
+ * 行为：
+ *   1. 解析当前用户 + Agent 的 chats.json 绝对路径
+ *   2. 调用 readChatsFileOrInitDefault 读取：文件不存在时**主动落盘一条 chatId=''
+ *      的默认会话兜底条目**，保证前端拉列表永远拿到至少一项；格式异常时返回 []
+ *   3. 通过 EVENT_CHAT_RESPONSE 回 { chats }；若意外抛异常则回 { chats: [], error }
+ *
+ * 为什么 list 路径要主动兜底？
+ *   - 用户首次连接拉列表 → 拿到默认对话 → UI 展示一致，不会出现
+ *     “先空态、首条消息后又凭空多出一项”的诡异闪烁；
+ *   - 兜底是幂等的：若 chats.json 已存在则等价于纯读取，无副作用；
+ *   - 与 ensureSessionInHistory 的被动兜底形成双保险，覆盖“前端跳过 list
+ *     直接发消息”的极端场景。
+ *
+ * 为什么 create/update/delete/history:request 仍走纯只读 readChatsFile？
+ *   - 它们要么是用户主动操作（隐式创建语义已在 create 中处理），
+ *     要么是只读查询（不应有写盘副作用），由 list 路径统一负责兜底即可。
+ */
+export function handleChatList(params) {
+    const { userId, agentId, botClientId, reliableEmitter, log } = params;
+    // 当前用户在当前 Agent 下的会话记录保存路径，即 chats.json 的绝对路径
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    // 响应 msgId：同时做 ReliableEmitter 的 ack key，成功 / 失败分支共用同一枚
+    const responseMsgId = generateMsgId();
+    // list 出错时，用一个空数组兑底，避免 UI 处理 undefined
+    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'list', reliableEmitter, log }, { chats: [] });
+    try {
+        // 主动兜底读取：文件不存在则落盘一条 chatId='' 的默认会话；存在则等价于纯只读
+        const chats = readChatsFileOrInitDefault(chatsPath);
+        log?.info(`[${CHANNEL_KEY}] Chat list: userId=${userId} agentId=${agentId} count=${chats.length}`);
+        // 正常分支：统一经 ReliableEmitter 发送，依赖其 ACK + 重试保障送达
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type: 'list',
+            agentId,
+            chats,
+            timestamp: Date.now(),
+        }, responseMsgId);
+    }
+    catch (err) {
+        // 兼容 Error / 非 Error 投掷（如字符串 throw），统一拼接为可读消息
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * 处理 EVENT_CHAT_REQUEST(type=create)：新建一条会话元数据。
+ *
+ * 行为：
+ *   1. 解析 `~/.openclaw/agents/<agentId>/chats/<userId>/chats.json`
+ *   2. 文件不存在 → 以空列表起步（writeChatsFile 会递归建目录 + 原子落盘）
+ *   3. 文件存在   → 读取并在头部插入新会话（新建的默认置顶于列表最前）
+ *   4. 新会话默认 `title = '新会话'`，`chatId = randomUUID()`，createdAt = updatedAt = now
+ *   5. 通过 EVENT_CHAT_RESPONSE 返回 { chat: 新建项 }
+ */
+export function handleChatCreate(params) {
+    const { userId, agentId, botClientId, reliableEmitter, log } = params;
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    // 响应 msgId：成功 / 失败分支共用，侜助前端根据 msgId 反查原请求
+    const responseMsgId = generateMsgId();
+    const sendError = createChatErrorSender({
+        responseMsgId,
+        botClientId,
+        userId,
+        agentId,
+        type: 'create',
+        reliableEmitter,
+        log,
+    });
+    try {
+        // 读取已有列表：文件不存在则返回 [] —— create 是隐式创建语义
+        const existing = readChatsFile(chatsPath);
+        const now = Date.now();
+        const newChat = {
+            chatId: randomUUID(),
+            title: '新会话',
+            // 新建时 titleLocked=false：首条消息后可被自动标题生成策略改写
+            titleLocked: false,
+            createdAt: now,
+            updatedAt: now,
+            pinned: false,
+            // sessionIdHistory：同一 chat 历史上使用过的 sessionId（支持会话分支 / 重置）
+            sessionIdHistory: [],
+        };
+        // 新会话插入到最前，writeChatsFile 会在目录不存在时逐级创建（tmp → rename 原子落盘）
+        const nextChats = [newChat, ...existing];
+        writeChatsFile(chatsPath, nextChats);
+        log?.info(`[${CHANNEL_KEY}] Chat create: userId=${userId} agentId=${agentId} chatId=${newChat.chatId}`);
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type: 'create',
+            agentId,
+            chats: [newChat],
+            timestamp: Date.now(),
+        }, responseMsgId);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}
+export function handleChatUpdate(params) {
+    const { userId, agentId, chatId, title, botClientId, reliableEmitter, log } = params;
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    const responseMsgId = generateMsgId();
+    // update 错误响应需要回显 chatId，便于前端关联请求
+    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'update', reliableEmitter, log }, { chatId });
+    // title 可能为纯空白字符，trim 后再判断，避免“空标题”落盘
+    const nextTitle = title?.trim();
+    if (!nextTitle) {
+        sendError('Missing title');
+        return;
+    }
+    // 文件必须存在，update 不负责创建（语义上：无源数据则无从更新）
+    if (!fs.existsSync(chatsPath)) {
+        sendError(`Chats file not found: ${chatsPath}`);
+        return;
+    }
+    try {
+        const chats = readChatsFile(chatsPath);
+        // O(n) 线性查找；chats.json 一般单用户单 Agent 规模有限，无需 Map 索引
+        const idx = chats.findIndex((c) => c.chatId === chatId);
+        if (idx < 0) {
+            sendError(`Chat not found: chatId=${chatId}`);
+            return;
+        }
+        // 更新：title + updatedAt + titleLocked
+        // titleLocked=true：用户主动改名后锁定，防止被自动标题生成策略覆盖
+        const updated = {
+            ...chats[idx],
+            title: nextTitle,
+            titleLocked: true,
+            updatedAt: Date.now(),
+        };
+        // 浅拷贝后原位替换，保留其他项的顺序（列表排序给前端决定，后端不托管）
+        const nextChats = [...chats];
+        nextChats[idx] = updated;
+        // 原子落盘：writeChatsFile 内部使用 tmp + rename 保证不损坏原文件
+        writeChatsFile(chatsPath, nextChats);
+        log?.info(`[${CHANNEL_KEY}] Chat update: userId=${userId} agentId=${agentId} chatId=${chatId} title="${nextTitle}"`);
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type: 'update',
+            agentId,
+            chats: [updated],
+            timestamp: Date.now(),
+        }, responseMsgId);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}
+export function handleChatDelete(params) {
+    const { userId, agentId, chatId, botClientId, reliableEmitter, log } = params;
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    const responseMsgId = generateMsgId();
+    // delete 错误响应需要回显 chatId，便于前端关联请求
+    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'delete', reliableEmitter, log }, { chatId });
+    // 文件必须存在，delete 不负责创建（无文件 == 无可删的项，返回明确错误）
+    if (!fs.existsSync(chatsPath)) {
+        sendError(`Chats file not found: ${chatsPath}`);
+        return;
+    }
+    try {
+        const chats = readChatsFile(chatsPath);
+        // 先确认条目存在再写盘，避免“无效删除”仍触发一次磁盘 IO
+        const idx = chats.findIndex((c) => c.chatId === chatId);
+        if (idx < 0) {
+            sendError(`Chat not found: chatId=${chatId}`);
+            return;
+        }
+        // 剔除目标项，保留其余顺序（不重排，不影响前端缓存的列表索引）
+        const nextChats = chats.filter((c) => c.chatId !== chatId);
+        // 原子落盘：writeChatsFile 内部使用 tmp + rename 保证不损坏原文件
+        writeChatsFile(chatsPath, nextChats);
+        log?.info(`[${CHANNEL_KEY}] Chat delete: userId=${userId} agentId=${agentId} chatId=${chatId} remaining=${nextChats.length}`);
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type: 'delete',
+            agentId,
+            chats: chats.filter((c) => c.chatId === chatId),
+            timestamp: Date.now(),
+        }, responseMsgId);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}

package/dist/src/socket/handlers.js

@@ -12,12 +12,14 @@
  * 所有出站 socket.emit 通过 ReliableEmitter 实现 ACK 确认 + 自动重试，
  * 保证消息在网络抖动时不丢失。
  */
-import { CHANNEL_KEY, EVENT_MESSAGE_PRIVATE, EVENT_HISTORY_REQUEST, EVENT_HISTORY_RESPONSE, DEFAULT_HISTORY_LIMIT, DEFAULT_AGENT_ID, EVENT_SESSIONS_REQUEST, EVENT_SESSIONS_RESPONSE, KIND_FILE_DOWNLOAD, FILE_DOWNLOAD_STATUS } from '../config.js';
+import { CHANNEL_KEY, EVENT_MESSAGE_PRIVATE, EVENT_HISTORY_REQUEST, EVENT_HISTORY_RESPONSE, DEFAULT_HISTORY_LIMIT, DEFAULT_AGENT_ID, EVENT_AGENTS_REQUEST, EVENT_AGENTS_RESPONSE, KIND_FILE_DOWNLOAD, FILE_DOWNLOAD_STATUS, EVENT_CHAT_REQUEST, } from '../config.js';
 import { isDuplicate, debounceHistoryRequest, generateMsgId } from '../dedup.js';
 import { getLightclawRuntime } from '../runtime.js';
-import { readSessionHistoryWithCron, listSessions } from '../history/index.js';
+import { readSessionHistoryWithCron, readSessionHistoriesByIds, loadSessionStore } from '../history/index.js';
+import { handleChatList, handleChatCreate, handleChatUpdate, handleChatDelete } from './chat.js';
 import { uploadFileToServer } from '../file-storage.js';
 import { guessMimeByExt } from '../media.js';
+import { ensureSessionInHistory, readChatsFile, resolveChatsFilePath } from '../utils/common.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 /**
@@ -72,6 +74,7 @@ export function bindSocketHandlers(socket, deps) {
         onEvent?.();
         log?.info(`[${CHANNEL_KEY}] Message from Agent: ${data.agentId}, ${data.from}: "${(data.content || '').slice(0, 60)}" files=${data.files?.length ?? 0}`);
         // /stop 及自然语言 abort 不做旁路，统一交给 openclaw fast-abort。
+        const chatId = extractChatId(data);
         handleMessage({
             senderId: data.from,
             text: data.content || '',
@@ -79,6 +82,32 @@ export function bindSocketHandlers(socket, deps) {
             files: data.files ?? [],
             timestamp: data.timestamp,
             agentId: data.agentId, // 透传前端指定的 agentId
+            chatId, // 透传前端指定的 chatId（多会话分桶用）
+        });
+        // ④ 异步登记当前生效的 sessionId 到 chats.json[chatId].sessionIdHistory。
+        //
+        // 为什么用 setImmediate？
+        //   - 首条消息到达时，框架还未创建 session，sessions.json 查不到该 sessionKey；
+        //   - /reset 等场景下，框架会在派发消息前 rotate sessionId，本回合的当前 sessionId
+        //     是 rotate 之后的新 ID；
+        //   - 把登记放到下一个事件循环 tick，给框架留出时序窗口（创建/rotate session）；
+        //   - 与主消息流解耦，登记失败不影响 handleMessage 主流程。
+        //
+        // 即使本次未登记成功（首条消息时 sessions.json 还没条目），下一条消息进来时
+        // 仍会再次触发本逻辑，幂等的 ensureSessionInHistory 会补登记，最终一致。
+        setImmediate(() => {
+            try {
+                recordSessionInHistory({
+                    userId: data.from,
+                    agentId: data.agentId,
+                    chatId,
+                    accountId: account.accountId,
+                    log,
+                });
+            }
+            catch (err) {
+                log?.warn(`[${CHANNEL_KEY}] recordSessionInHistory(message:private) error: ${err instanceof Error ? err.message : String(err)}`);
+            }
         });
     });
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -124,23 +153,91 @@ export function bindSocketHandlers(socket, deps) {
                 log?.info(`[${CHANNEL_KEY}], 当前agentId为：${resolvedAgentId}`);
                 // 始终用 effectiveAgentId 调用 buildAgentSessionKey 生成 sessionKey：
                 // - 前端传了合法 agentId → 用它；否则降级到 baseRoute.agentId（框架路由解析出的默认值）
-                const sessionKey = pluginRuntime.channel.routing.buildAgentSessionKey({
+                //
+                // 框架生成的基础 sessionKey 形如：
+                //   agent:<agentId>:<channel>:direct:<userId>
+                // 当前端带上 chatId（多会话场景）时，需要在基础 sessionKey 末尾追加 `:<chatId>`，
+                // 形成：agent:<agentId>:<channel>:direct:<userId>:<chatId>，
+                // 以区分同一用户下的不同会话历史文件。框架本身不感知 chatId，
+                // 故在此处显式拼接，保持与写入端（chat 维度的 sessionId）一致。
+                const baseSessionKey = pluginRuntime.channel.routing.buildAgentSessionKey({
                     agentId: resolvedAgentId,
                     channel: CHANNEL_KEY,
                     accountId: baseRoute.accountId,
                     peer: { kind: 'direct', id: data.from },
                     dmScope: 'per-channel-peer',
                 });
-                log?.info(`[${CHANNEL_KEY}] userId=${data.from}，当前的sessionKey=${sessionKey}`);
-                // 从本地持久化存储中读取该 session 的历史消息
-                // includeCron: true 表示同时读取定时任务产生的消息（如每日推送）
-                const messages = readSessionHistoryWithCron(sessionKey, {
-                    limit: data.limit ?? DEFAULT_HISTORY_LIMIT,
-                    chatOnly: data.chatOnly ?? true,
-                    includeCron: true,
-                    agentId: resolvedAgentId,
-                });
-                log?.info(`[${CHANNEL_KEY}] History request: userId=${data.from} sessionKey=${sessionKey} found=${messages.length}`);
+                const chatIdSuffix = extractChatId(data);
+                const sessionKey = chatIdSuffix ? `${baseSessionKey}:${chatIdSuffix}` : baseSessionKey;
+                log?.info(`[${CHANNEL_KEY}] userId=${data.from}，chatId=${chatIdSuffix || '-'}，当前的sessionKey=${sessionKey}`);
+                // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                // ① 兜底登记当前 sessionId 到 sessionIdHistory
+                //
+                // 为什么在拉历史时也做登记？—— 兜底覆盖一个边界场景：用户 reset 后没再
+                // 发过消息，只是重新打开聊天界面拉历史。此时 message:private 的登记
+                // 路径不会被触发，仅靠这里能补登记，确保历史不丢。
+                //
+                // 必须先于读历史，因为读历史依赖 sessionIdHistory 来合并多份 jsonl，
+                // 当前 sessionId 也要一起读到。
+                // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                try {
+                    const store = loadSessionStore(resolvedAgentId);
+                    const currentSessionId = store[sessionKey]?.sessionId;
+                    if (currentSessionId) {
+                        ensureSessionInHistory(resolvedAgentId, data.from, chatIdSuffix, currentSessionId);
+                    }
+                }
+                catch (err) {
+                    log?.warn(`[${CHANNEL_KEY}] ensureSessionInHistory(history:request) error: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                // ② 读取历史消息：优先按 sessionIdHistory 合并多份 jsonl（跨 reset 历史回看）
+                //
+                // - chats.json 命中（含 chatId === '' 的默认对话兜底条目）：
+                //     把该 chat 用过的所有 sessionId（含归档的旧 sessionId）的 jsonl
+                //     全部读出来按 timestamp 合并；
+                // - 否则：退化到原来的"按 sessionKey 读当前 jsonl + cron 合并"路径，
+                //   保持向后兼容（chats.json 不存在 / 解析异常等极端场景）。
+                // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                const limit = data.limit ?? DEFAULT_HISTORY_LIMIT;
+                const chatOnly = data.chatOnly ?? true;
+                let messages = [];
+                let readMode = 'single-session-with-cron';
+                try {
+                    // 查询侧使用与登记侧同一个 chatId（已在 extractChatId 统一归一）。
+                    const targetChatId = chatIdSuffix;
+                    const chatsPath = resolveChatsFilePath(resolvedAgentId, data.from);
+                    // 这里使用**纯只读**的 readChatsFile：
+                    //   - 拉历史是只读接口，不应该在用户还没发任何消息前就把
+                    //     chats.json 写到磁盘（避免凭空出现一个默认对话）；
+                    //   - 如果是默认对话首次消息后拉历史，前面的 ensureSessionInHistory
+                    //     已经走 readChatsFileOrInitDefault 打点过 chats.json，这里能读到。
+                    const matched = readChatsFile(chatsPath).find((c) => c.chatId === targetChatId);
+                    const historyIds = matched?.sessionIdHistory ?? [];
+                    if (historyIds.length > 0) {
+                        messages = readSessionHistoriesByIds(historyIds, {
+                            limit,
+                            chatOnly,
+                            agentId: resolvedAgentId,
+                        });
+                        readMode = 'multi-session';
+                    }
+                }
+                catch (err) {
+                    log?.warn(`[${CHANNEL_KEY}] readSessionHistoriesByIds fallback to single-session: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (messages.length === 0 && readMode !== 'multi-session') {
+                    // 退路 / 兜底：仅当未走多 sessionId 合并路径时，退化到按当前 sessionKey 读（含 cron 合并）。
+                    // 已走 multi-session 但消息为空，意味着 chats.json 里 sessionIdHistory 全部 jsonl 都没内容，
+                    // 这是合理的"空历史"状态，不应再退回 single-session 路径，避免重复 cron 拼接的副作用。
+                    messages = readSessionHistoryWithCron(sessionKey, {
+                        limit,
+                        chatOnly,
+                        includeCron: true,
+                        agentId: resolvedAgentId,
+                    });
+                }
+                log?.info(`[${CHANNEL_KEY}] History request: userId=${data.from} sessionKey=${sessionKey} mode=${readMode} found=${messages.length}`);
                 // 过滤掉内容为空的消息（既无文字也无附件），避免客户端渲染空气泡
                 const historyMsgId = generateMsgId();
                 reliableEmitter.emitWithAck(EVENT_HISTORY_RESPONSE, {
@@ -168,31 +265,171 @@ export function bindSocketHandlers(socket, deps) {
             }
         });
     });
-    socket.on(EVENT_SESSIONS_REQUEST, (data) => {
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // 事件：Agents 列表请求（agents:request）
+    // 职责：读取 openclaw.json 中 agents.list 并返回给客户端（支持热更新，不缓存）
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    socket.on(EVENT_AGENTS_REQUEST, (data, ack) => {
+        // 立即回复 ACK，告知服务端请求已收到
+        ack?.();
+        if (data.from === botClientId)
+            return;
         // 通知框架收到入站事件（更新 lastEventAt，防止 stale-socket 误判）
         onEvent?.();
         try {
-            const sessions = listSessions();
-            const sessionsMsgId = generateMsgId();
-            reliableEmitter.emitWithAck(EVENT_SESSIONS_RESPONSE, {
-                requestId: data.requestId,
-                sessions,
-                msgId: sessionsMsgId,
-            }, sessionsMsgId);
+            // 获取插件运行时，读取最新配置
+            const pluginRuntime = getLightclawRuntime();
+            const currentCfg = pluginRuntime.config.loadConfig();
+            const agentsList = currentCfg.agents?.list ?? [];
+            log?.info(`[${CHANNEL_KEY}] Agents request: count=${agentsList.length}`);
+            const agentsMsgId = generateMsgId();
+            reliableEmitter.emitWithAck(EVENT_AGENTS_RESPONSE, {
+                msgId: agentsMsgId,
+                to: data.from,
+                from: botClientId,
+                agents: agentsList,
+                timestamp: Date.now(),
+            }, agentsMsgId);
         }
         catch (err) {
-            log?.error(`[${CHANNEL_KEY}] Sessions list error: ${err}`);
-            const sessionsErrMsgId = generateMsgId();
-            reliableEmitter.emitWithAck(EVENT_SESSIONS_RESPONSE, {
-                requestId: data.requestId,
-                sessions: [],
+            log?.error(`[${CHANNEL_KEY}] Agents request error: ${err}`);
+            const agentsErrMsgId = generateMsgId();
+            reliableEmitter.emitWithAck(EVENT_AGENTS_RESPONSE, {
+                msgId: agentsErrMsgId,
+                from: botClientId,
+                to: data.from,
+                agents: [],
                 error: err instanceof Error ? err.message : String(err),
-                msgId: sessionsErrMsgId,
-            }, sessionsErrMsgId);
+                timestamp: Date.now(),
+            }, agentsErrMsgId);
+        }
+    });
+    socket.on(EVENT_CHAT_REQUEST, (data, ack) => {
+        ack?.();
+        log?.info(`[${CHANNEL_KEY}] Received chat request from ${data.from}: ${data.type}`);
+        if (!data?.from) {
+            log?.warn(`[${CHANNEL_KEY}] Chat request missing userId, ignoring`);
+            return;
+        }
+        // 回环防御
+        if (data.from === botClientId)
+            return;
+        onEvent?.();
+        switch (data.type) {
+            case 'list':
+                handleChatList({
+                    userId: data.from,
+                    agentId: data.agentId,
+                    botClientId,
+                    reliableEmitter,
+                    log,
+                });
+                break;
+            case 'create':
+                handleChatCreate({
+                    userId: data.from,
+                    agentId: data.agentId,
+                    botClientId,
+                    reliableEmitter,
+                    log,
+                });
+                break;
+            case 'update':
+                handleChatUpdate({
+                    userId: data.from,
+                    agentId: data.agentId,
+                    chatId: data.chatId,
+                    title: data.title,
+                    botClientId,
+                    reliableEmitter,
+                    log,
+                });
+                break;
+            case 'delete':
+                handleChatDelete({
+                    userId: data.from,
+                    agentId: data.agentId,
+                    chatId: data.chatId,
+                    botClientId,
+                    reliableEmitter,
+                    log,
+                });
+                break;
         }
     });
 }
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 内部工具：从 PrivateMessageData / HistoryRequestData 中统一提取 chatId
+//
+// 抽离原因：原代码同一字段在 message:private（||）、setImmediate（??）、
+// history:request（?.trim()）三处使用了三种不同写法，虽然在协议正常时结果一致，
+// 但语义有偏差且日后极易踩坑。统一为 extractChatId 后：
+//   - 入参可能是 undefined / null / 非字符串 / 含空白字符串 / 合法字符串；
+//   - 一律 trim 后归一为字符串；undefined / null / 非字符串 → ''；
+//   - 返回值要么是 ''（默认对话标识），要么是非空合法 chatId。
+// 这样写入侧（chats.json[chatId].sessionIdHistory）与读取侧（按 chatId 查询）
+// 始终拿到同一个值，杜绝因写法差异引起的"找不到 chat 条目"问题。
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+function extractChatId(data) {
+    const raw = data?.extra?.chatId;
+    if (typeof raw !== 'string')
+        return '';
+    return raw.trim();
+}
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 内部工具：把当前 chat 在用的 sessionId 登记到 chats.json[chatId].sessionIdHistory
+//
+// 设计要点：
+//   1. 解析 sessionKey —— 与 history:request 分支保持一致：
+//        agent:<agentId>:<channel>:direct:<userId>[:<chatId>]
+//      若无 chatId 直接早返（无 chatId 的会话不在 chats.json 中登记）。
+//   2. 通过 agentId 合法性校验，避免前端伪造 agentId 污染他人 chats.json。
+//   3. 从 sessions.json 索引读出当前 sessionKey 对应的 sessionId
+//      —— 框架在派发消息前完成 mint/rotate，本时刻读到的就是"当前生效"的 sessionId。
+//   4. 调用幂等的 ensureSessionInHistory：已存在则跳过；新出现则末尾追加并落盘。
+//
+// 调用时机：
+//   - EVENT_MESSAGE_PRIVATE：在 setImmediate 中异步调用，确保框架已建好/rotate 好 session；
+//   - EVENT_HISTORY_REQUEST：在 sessionKey 解析后同步调用，作为兜底登记入口。
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+function recordSessionInHistory(params) {
+    const { userId, agentId, chatId, accountId, log } = params;
+    // 取最新配置，复用 history 分支同款 agentId 校验逻辑（防止伪造 agentId）
+    const pluginRuntime = getLightclawRuntime();
+    const currentCfg = pluginRuntime.config.loadConfig();
+    const currentCfgTyped = currentCfg;
+    const validAgentIds = currentCfgTyped.agents?.list?.map((a) => a.id) ?? [DEFAULT_AGENT_ID];
+    const resolvedAgentId = agentId && validAgentIds.includes(agentId) ? agentId : DEFAULT_AGENT_ID;
+    // 计算 sessionKey（必须与 history:request 一致，否则查不到 sessions.json 条目）
+    const baseRoute = pluginRuntime.channel.routing.resolveAgentRoute({
+        cfg: currentCfg,
+        channel: CHANNEL_KEY,
+        accountId,
+        peer: { kind: 'direct', id: userId },
+    });
+    const baseSessionKey = pluginRuntime.channel.routing.buildAgentSessionKey({
+        agentId: resolvedAgentId,
+        channel: CHANNEL_KEY,
+        accountId: baseRoute.accountId,
+        peer: { kind: 'direct', id: userId },
+        dmScope: 'per-channel-peer',
+    });
+    // 与 history:request 保持完全一致的 sessionKey 拼接规则：
+    //   - 空 chatId  → 不追加后缀，直接用 baseSessionKey（默认对话场景）
+    //   - 非空 chatId → 追加 `:<chatId>` 后缀（多会话场景）
+    // 这是写入侧已建立的约定，框架对无 chatId 会话写到 baseSessionKey 上。
+    const sessionKey = chatId ? `${baseSessionKey}:${chatId}` : baseSessionKey;
+    // 查 sessions.json 拿当前生效 sessionId；首条消息时可能查不到 → 跳过，下一条消息会补登记
+    const store = loadSessionStore(resolvedAgentId);
+    const currentSessionId = store[sessionKey]?.sessionId;
+    if (!currentSessionId) {
+        log?.info(`[${CHANNEL_KEY}] recordSessionInHistory: sessionId not found yet, skip. sessionKey=${sessionKey}`);
+        return;
+    }
+    // 登记 sessionId 到 chats.json，确保历史记录能被查到；已存在则跳过，新增则末尾追加并落盘
+    ensureSessionInHistory(resolvedAgentId, userId, chatId, currentSessionId);
+}
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // 文件下载处理器（kind=file:download, status=download_req）
 //
 // 流程：
@@ -220,7 +457,10 @@ async function handleFileDownloadReq(data, botClientId, reliableEmitter, account
             content: '',
             timestamp: Date.now(),
             kind: KIND_FILE_DOWNLOAD,
-            extra: { transferData: { transferId, status: FILE_DOWNLOAD_STATUS.ERROR, error } },
+            extra: {
+                chatId: extractChatId(data),
+                transferData: { transferId, status: FILE_DOWNLOAD_STATUS.ERROR, error },
+            },
         }, msgId);
         log?.error(`[${CHANNEL_KEY}] file:download(error) sent: transferId=${transferId}, error=${error}`);
     };
@@ -255,6 +495,7 @@ async function handleFileDownloadReq(data, botClientId, reliableEmitter, account
         timestamp: Date.now(),
         kind: KIND_FILE_DOWNLOAD,
         extra: {
+            chatId: extractChatId(data),
             transferData: {
                 transferId,
                 status: FILE_DOWNLOAD_STATUS.READY,
@@ -283,6 +524,7 @@ async function handleFileDownloadReq(data, botClientId, reliableEmitter, account
             timestamp: Date.now(),
             kind: KIND_FILE_DOWNLOAD,
             extra: {
+                chatId: extractChatId(data),
                 transferData: {
                     transferId,
                     status: FILE_DOWNLOAD_STATUS.URL,

package/dist/src/streaming/stream-reply-sink.js

@@ -110,11 +110,11 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
             enrichedText = enrichedText ? `${enrichedText}\n\n${urlSection}` : urlSection;
         }
         if (files.length > 0) {
-            emitter.sendFiles(targetId, enrichedText, files, originalMsgId);
+            emitter.sendFiles(targetId, enrichedText, files, originalMsgId, signalCtx.chatId);
             emittedUserVisible = true;
         }
         else if (enrichedText.trim()) {
-            emitter.sendReply(targetId, enrichedText, originalMsgId);
+            emitter.sendReply(targetId, enrichedText, originalMsgId, signalCtx.chatId);
             emittedUserVisible = true;
         }
     };
@@ -256,7 +256,7 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
                     : "LLM only produced thinking, no visible text";
                 log?.warn(`[${CHANNEL_KEY}] [stream] NO_REPLY: counts=${JSON.stringify(counts)} ` +
                     `toolStart=${toolStartCount} assistantMsg=${assistantMessageCount}. Cause: ${cause}`);
-                emitter.sendReply(targetId, "NO_REPLY", originalMsgId);
+                emitter.sendReply(targetId, "NO_REPLY", originalMsgId, signalCtx.chatId);
             }
             else {
                 log?.info(`[${CHANNEL_KEY}] [stream] markComplete: counts=${JSON.stringify(counts)} ` +