lightclawbot 1.2.3 → 1.2.6-beta.0

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

@@ -5,7 +5,8 @@
  *   - onPartialReply    → 计算增量 → emit stream_chunk
  *   - onToolStart       → emit tool_start（前端决定如何渲染）
  *   - sendFinalReply    → 跨轮次去重后发送剩余增量（或丢弃）
- *   - markComplete      → 发 typing_stop；NO_REPLY 场景兜底一条提示
+ *   - markComplete      → 从 transcript 读 usage 并 emit usage 帧 → 发 typing_stop；
+ *                         NO_REPLY 场景兜底一条提示
  *
  * 关键状态：
  *   streamedText     当前 assistant 轮已流式推送的文本
@@ -17,6 +18,7 @@ import { uploadFileToServer } from "../file-storage.js";
 import { mediaUrlsToFiles } from "../media.js";
 import { createDeltaTrackerState, toStreamDeltaText } from "./delta-tracker.js";
 import { emitSignal } from "../utils/common.js";
+import { readSessionHistoryTail } from "../history/index.js";
 /** 派生/管理 subagent 的工具名；前端可据此特化渲染 tool_start。 */
 const SUBAGENT_TOOL_NAMES = new Set([
     "sessions_spawn",
@@ -30,7 +32,7 @@ function localizeAbortReplyText(text) {
     return OPENCLAW_ABORT_REPLY_RE.test(text.trim()) ? LOCALIZED_ABORT_REPLY : text;
 }
 export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
-    const { emitter, targetId, originalMsgId, log, effectiveApiKey, typingAlreadyStarted } = opts;
+    const { emitter, targetId, originalMsgId, log, effectiveApiKey, typingAlreadyStarted, sessionKey, agentId } = opts;
     // ── 增量追踪 & 已推送文本 ──
     let partialReplyState = createDeltaTrackerState();
     let streamedText = "";
@@ -54,6 +56,10 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
     let completed = false;
     /** openclaw abort 检测：sendFinalReply 收到 abort 文案时置 true，markComplete 据此跳过 NO_REPLY。 */
     let abortDetected = false;
+    // ── Token 用量 ──
+    // 把每一轮的 usage 写入 transcript jsonl（与 history 模块同源），
+    // 因此在 markComplete 时从 transcript 末尾读最近一条 assistant 消息的 usage，
+    // 然后 emit `kind='usage'` 帧给前端。
     // ── 串行化回调队列：保证 COS 上传等异步操作按顺序执行 ──
     let queuePromise = Promise.resolve();
     const enqueue = (fn) => {
@@ -110,11 +116,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;
         }
     };
@@ -223,13 +229,18 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
         getQueuedCounts: () => ({ ...counts }),
         getFailedCounts: () => ({ tool: 0, block: 0, final: 0 }),
         /**
-         * 标记本次 dispatch 完成 → 发 typing_stop。
+         * 标记本次 dispatch 完成 → 发 usage 帧（如有）→ 发 typing_stop。
          *
          * NO_REPLY 仅在"LLM 正常完成一次完整 run 但没产出可见文本"时才触发。
          * 以下场景均不发：
          *   - isAborted / abortDetected：/stop 或 abort 触发
          *   - hadLLMActivity 但 hadDispatch=false：LLM 启动但被中途打断（abort 没来得及 sendFinalReply）
          *   - !hadLLMActivity：followup 被 collect 合并 / plugin 拦截
+         *
+         * Token 用量帧的 emit 时机：
+         *   在 typing_stop **之前** 从 transcript 读 usage 并 emit 一次。前端依次收到：
+         *     ...stream_chunk → tool_start/end → ... → usage(可选) → typing_stop
+         *   这样保证"一次问答一次消耗"，且消耗信息在结束态前到达。
          */
         markComplete: (markOpts) => {
             completed = true;
@@ -256,13 +267,54 @@ 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)} ` +
                     `toolStart=${toolStartCount} assistantMsg=${assistantMessageCount} ` +
                     `streamedLen=${streamedText.length} historyRounds=${streamedHistory.length}`);
             }
+            // 在 typing_stop 之前 emit 一帧 usage（如有）。
+            // 数据源：从 transcript jsonl 读最近一条 assistant 消息的 usage（与 history 模块同源）。
+            // abort / 静默 dispatch / NO_REPLY 等异常路径下 transcript 可能没有可读 usage，
+            // 此时不 emit，前端按"无用量数据"渲染。
+            let usageToEmit;
+            // 非 abort + sessionKey 已知 → 从 transcript 读 usage
+            if (!isAborted && sessionKey) {
+                try {
+                    // 找到本轮最后一条 assistant
+                    const tailMessages = readSessionHistoryTail(sessionKey, {
+                        limit: 10,
+                        chatOnly: true,
+                        agentId,
+                    });
+                    // 找到最后一条 assistant 消息（一轮的最后一条 = 本次问答的累计 usage）
+                    let foundUsage;
+                    for (let i = tailMessages.length - 1; i >= 0; i -= 1) {
+                        const m = tailMessages[i];
+                        if (m.role === "assistant" && m.usage) {
+                            foundUsage = m.usage;
+                            break;
+                        }
+                    }
+                    if (foundUsage) {
+                        usageToEmit = foundUsage;
+                    }
+                    else {
+                        log?.warn(`[${CHANNEL_KEY}] [stream] no assistant.usage found in transcript tail ` +
+                            `(messages=${tailMessages.length})`);
+                    }
+                }
+                catch (err) {
+                    log?.warn(`[${CHANNEL_KEY}] [stream] read transcript failed: ` +
+                        `${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (usageToEmit) {
+                log?.info(`[${CHANNEL_KEY}] [stream] emit final usage: ` +
+                    `input=${usageToEmit.inputTokens} output=${usageToEmit.outputTokens} total=${usageToEmit.totalTokens}`);
+                emitSignal(signalCtx, "usage", "", undefined, { usage: usageToEmit });
+            }
             sendTypingStop();
         },
     };

package/dist/src/usage/index.js

@@ -0,0 +1,4 @@
+/**
+ * LightClaw — Usage 模块
+ */
+export { normalizeUsage } from './normalize.js';

package/dist/src/usage/normalize.js

@@ -0,0 +1,47 @@
+/**
+ * LightClaw — Usage 归一函数
+ *
+ * 当前阶段直接读取 OpenClaw 的字段（input/output/...），
+ * 未来如果遇到和当前 OpenClaw 不一致的agent或者其他模型需要兼容
+ * 可以把本函数升级为「多适配器」，对外 API保持不变，调用方 0 改动。
+ */
+export function normalizeUsage(raw, ctx = {}) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    // OpenClaw 落盘格式的字段直接取（v1：input/output；v2：inputTokens/outputTokens 双兼容）
+    const inputTokens = pickNumber(r, ['inputTokens', 'input']);
+    const outputTokens = pickNumber(r, ['outputTokens', 'output']);
+    // 三者全无则视为无效数据
+    if (inputTokens === undefined && outputTokens === undefined) {
+        const totalOnly = pickNumber(r, ['totalTokens', 'total']);
+        if (totalOnly === undefined)
+            return null;
+    }
+    const totalTokensRaw = pickNumber(r, ['totalTokens', 'total']);
+    const totalTokens = totalTokensRaw ?? (inputTokens ?? 0) + (outputTokens ?? 0);
+    return {
+        inputTokens,
+        outputTokens,
+        totalTokens,
+        cachedInputTokens: pickNumber(r, ['cachedInputTokens', 'cacheRead']),
+        cacheWriteTokens: pickNumber(r, ['cacheWriteTokens', 'cacheWrite']),
+        reasoningTokens: pickNumber(r, ['reasoningTokens']),
+        model: ctx.model,
+        provider: ctx.provider,
+        raw: r,
+    };
+}
+/**
+ * 在对象中按候选键名顺序查找第一个 finite number 字段。
+ * 抽出此函数是为了让字段命名兼容（v1 短名 / v2 长名）逻辑保持一处，
+ * 后续如果 OpenClaw 又新增字段命名（比如 inputTokenCount），只需在候选列表里追加。
+ */
+function pickNumber(obj, keys) {
+    for (const key of keys) {
+        const v = obj[key];
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}

package/dist/src/usage/types.js

@@ -0,0 +1 @@
+export {};