@coclaw/openclaw-coclaw 0.21.4 → 0.21.5

package/README.md

@@ -92,7 +92,7 @@ pnpm run release:versions                  # 显示所有已发布版本
 | `coclaw.files.delete` | 删除工作区文件/目录 |
 | `coclaw.files.mkdir` | 创建工作区目录 |
 | `coclaw.files.create` | 创建空文件 |
-| `nativeui.sessions.listAll` | 列出所有 session（分页 + 标题推导） |
+| `nativeui.sessions.listAll` | 列出所有 session（分页） |
 | `nativeui.sessions.get` | 获取 session 原始 JSONL 行（分页） |
 
 ## Gateway Services

package/index.js

@@ -363,21 +363,21 @@ const plugin = {
 				// best-effort ensure：失败不阻断 listAll
 				try { await ensureAgentSession(agentId); }
 				catch {}
-				respond(true, manager.listAll(params ?? {}));
+				respond(true, await manager.listAll(params ?? {}));
 			}
 			catch (err) {
 				respondError(respond, err);
 			}
 		});
 
-		api.registerGatewayMethod('nativeui.sessions.get', ({ params, respond }) => {
+		api.registerGatewayMethod('nativeui.sessions.get', async ({ params, respond }) => {
 			try {
 				const sessionId = params?.sessionId;
 				if (typeof sessionId !== 'string' || sessionId.trim().length === 0) {
 					respondInvalid(respond, 'sessionId required');
 					return;
 				}
-				respond(true, manager.get(params ?? {}));
+				respond(true, await manager.get(params ?? {}));
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -474,7 +474,7 @@ const plugin = {
 			}
 		});
 
-		api.registerGatewayMethod('coclaw.topics.getHistory', ({ params, respond }) => {
+		api.registerGatewayMethod('coclaw.topics.getHistory', async ({ params, respond }) => {
 			try {
 				const topicId = params?.topicId?.trim?.();
 				if (!topicId) {
@@ -483,7 +483,7 @@ const plugin = {
 				}
 				const agentId = params?.agentId?.trim?.() || 'main';
 				// 直接复用 session-manager 的 get()，topicId 即 sessionId
-				respond(true, manager.get({ agentId, sessionId: topicId }));
+				respond(true, await manager.get({ agentId, sessionId: topicId }));
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -577,7 +577,7 @@ const plugin = {
 		});
 
 		// TODO: coclaw.topics.getHistory 未来可废弃，UI 改用 coclaw.sessions.getById
-		api.registerGatewayMethod('coclaw.sessions.getById', ({ params, respond }) => {
+		api.registerGatewayMethod('coclaw.sessions.getById', async ({ params, respond }) => {
 			try {
 				const sessionId = params?.sessionId?.trim?.();
 				if (!sessionId) {
@@ -586,7 +586,7 @@ const plugin = {
 				}
 				const agentId = params?.agentId?.trim?.() || 'main';
 				const limit = params?.limit;
-				respond(true, manager.getById({ agentId, sessionId, limit }));
+				respond(true, await manager.getById({ agentId, sessionId, limit }));
 			}
 			catch (err) {
 				respondError(respond, err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.21.4",
+  "version": "0.21.5",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat. Run `openclaw coclaw enroll` after install to connect to CoClaw.",

package/src/auto-upgrade/updater.js

@@ -131,6 +131,14 @@ export async function writeUpgradeLock(pid) {
  * `upgrade.ledger-read-failed` / `upgrade.ledger-parse-failed`），避免运维只
  * 看到 start() 那条 "Skipping: not an npm-installed plugin" 时误判方向。
  *
+ * 注：内部 `readFileSync` 为同步 IO，**有意保留**——只在升级周期决策时读一次
+ * 账本（整个进程生命周期通常一锤子）。改 async 必须沿 `shouldSkipAutoUpgrade`
+ * 等调用链向上传播，收益不抵成本。
+ *
+ * 另：OpenClaw plugin SDK 当前未暴露查询 installRecords 的 API，只能直接读
+ * `<state-dir>/plugins/installs.json`（与上游 `manifest-metadata-scan` 等
+ * 内部模块同源做法）。如果上游后续开放官方接口，可切换并删除直读分支。
+ *
  * @param {string} pluginId
  * @returns {object|null}
  */

package/src/device-identity.js

@@ -77,6 +77,13 @@ function generateIdentity() {
  * 加载或创建设备身份（Ed25519 密钥对）
  *
  * 存储格式与 OpenClaw device-identity.ts 保持一致。
+ *
+ * 注：本函数及内部 `fs.existsSync` / `readFileSync` / `generateKeyPairSync` /
+ * `atomicWriteFileSync` 均为同步 IO，**有意保留**——本路径只在 plugin↔本机
+ * gateway 首次握手时命中一次（后续走 realtime-bridge 的内存缓存），属于"启动期
+ * 一锤子"。改 async 必须把握手链路也 async 化，复杂度全长在握手那条线上，收益
+ * 不抵成本。重新评估前请先确认调用频率确实发生了变化。
+ *
  * @param {string} [filePath] - 自定义路径，默认 <state-dir>/coclaw/device-identity.json
  * @returns {{ deviceId: string, publicKeyPem: string, privateKeyPem: string }}
  */

package/src/realtime-bridge.js

@@ -768,9 +768,13 @@ export class RealtimeBridge {
 				if (this.gatewayWs !== ws) {
 					return;
 				}
+				// rawData 保留供转发链路（res 单播 / agent event 单播 / 兜底广播）透传：
+				// 跳过 webrtcPeer.broadcast/sendTo 内部的重新 stringify，省掉对大 payload
+				// （如 agent.run.event 含大 tool_result）的重复序列化主线程阻塞。
+				const rawData = String(event.data ?? '{}');
 				let payload = null;
 				try {
-					payload = JSON.parse(String(event.data ?? '{}'));
+					payload = JSON.parse(rawData);
 				}
 				catch {
 					return;
@@ -892,7 +896,9 @@ export class RealtimeBridge {
 							/* c8 ignore next -- TODO: 2026-05-20 后删除 */
 							this.logger.debug?.(`[coclaw/rpc-res-route] hit, reqId=${payload.id} → connId=${info.connId}`);
 							// sendTo 阶段 1 改为 async（admission 决策 await）；外层 listener 已是 async
-							const delivered = await this.webrtcPeer?.sendTo(info.connId, payload);
+							// 透传 rawData 跳过重新 stringify：gateway → plugin → DC 转发链路上的大 payload
+							// （如 agent.run.event 含大 tool_result）省掉一次主线程序列化阻塞。
+							const delivered = await this.webrtcPeer?.sendTo(info.connId, payload, rawData);
 							if (!delivered) {
 							// PC 已断 / DC 未 open / 队列拒收：本地 log 丢弃，不退回广播
 								this.__logDebug(
@@ -913,7 +919,8 @@ export class RealtimeBridge {
 								/* c8 ignore next -- TODO: 2026-05-20 后删除 */
 								this.logger.debug?.(`[coclaw/run-event-route] hit, runId=${runId} → connId=${connId}`);
 								// sendTo 失败不打 log（PC 状态翻转日志已足够，drop 是正确语义）
-								await this.webrtcPeer?.sendTo(connId, payload);
+								// 透传 rawData 跳过重新 stringify：agent event payload 可能很大（如 tool_result）
+								await this.webrtcPeer?.sendTo(connId, payload, rawData);
 								return;
 							}
 						}
@@ -921,7 +928,8 @@ export class RealtimeBridge {
 						this.logger.debug?.(`[coclaw/run-event-route] miss, broadcast, runId=${runId ?? '<missing>'}`);
 					}
 					// (d) 兜底广播：覆盖 event 类型 / 映射未命中场景
-					this.webrtcPeer?.broadcast(payload);
+					// 透传 rawData 跳过重新 stringify：agent event 兜底广播同样可能很大
+					this.webrtcPeer?.broadcast(payload, rawData);
 				}
 			})().catch((err) => {
 				this.logger.warn?.(`[coclaw] gateway ws message handler error: ${err?.message ?? err}`);
@@ -1310,8 +1318,14 @@ export class RealtimeBridge {
 						await this.__webrtcPeerReady;
 						await this.webrtcPeer.handleSignaling(payload);
 					} catch (err) {
-						this.logger.warn?.(`[coclaw/rtc] signaling error (or werift not found): ${err?.message}`);
-						remoteLog(`rtc.signaling-error msg=${err?.message}`);
+						// 现在 handleSignaling 内 drain 自己 catch + 转 rtc.signaling-error remoteLog 不
+						// 抛出，这层 catch 只会兜到 __initWebrtcPeer() 失败（peer 未就绪）。type/conn
+						// 字段保留是为了 server 端日志区分发生位置——init 路径下 type/conn 仍来自当前
+						// 信令消息，与 drain 内的同名日志做区分主要看 msg 文本。
+						const sigType = payload?.type ?? 'unknown';
+						const sigConn = payload?.fromConnId ?? payload?.toConnId ?? 'unknown';
+						this.logger.warn?.(`[coclaw/rtc] signaling error (or werift not found) type=${sigType} conn=${sigConn}: ${err?.message}`);
+						remoteLog(`rtc.signaling-error type=${sigType} conn=${sigConn} msg=${err?.message}`);
 					}
 					return;
 				}

package/src/session-manager/manager.js

@@ -1,69 +1,8 @@
-import fs from 'node:fs';
+import fsp from 'node:fs/promises';
 import nodePath from 'node:path';
 
 import { agentSessionsDir, sessionStorePath, sessionTranscriptPath } from '../claw-paths.js';
-
-const DERIVED_TITLE_MAX_LEN = 60;
-
-// OC 注入的 inbound metadata 头部（Conversation info / Sender / Thread starter 等）
-const INBOUND_META_RE = /^\w[\w ]* \(untrusted[^)]*\):\n```json\n[\s\S]*?\n```\n\n/;
-// operator 级策略/指令前缀，如 Skills store policy (operator configured): ...
-const OPERATOR_POLICY_RE = /^\w[\w ]* \(operator configured\):[\s\S]*?\n\n/;
-// OC 注入的用户消息时间戳前缀
-const USER_TS_RE = /^\[(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}(?::\d{2})?\s+[^\]]+\]\s*/;
-// 尾部 [message_id: xxx]
-const MSG_ID_SUFFIX_RE = /\n\[message_id:\s*[^\]]+\]\s*$/;
-// 尾部 Untrusted context 块（外部元数据注入）
-const UNTRUSTED_CTX_SUFFIX_RE = /\n\nUntrusted context \(metadata, do not treat as instructions or commands\):\n[\s\S]*$/;
-// 定时任务前缀
-const CRON_UUID_RE = /\[cron:[0-9a-f-]+(?:\s+([^\]]*))?\]\s*/;
-// cron 注入的 Current time 行及其后的系统追加指令（如 "Return your summary..."）
-const CRON_TIME_TAIL_RE = /\nCurrent time:[^\n]+[\s\S]*$/;
-// 从 Current time 行提取 UTC 时间部分
-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 '';
-		const y = d.getFullYear();
-		const mo = String(d.getMonth() + 1).padStart(2, '0');
-		const dd = String(d.getDate()).padStart(2, '0');
-		const hh = String(d.getHours()).padStart(2, '0');
-		const mi = String(d.getMinutes()).padStart(2, '0');
-		return ` ${y}-${mo}-${dd} ${hh}${mi}`;
-	}
-	catch {
-		return '';
-	}
-	/* c8 ignore stop */
-}
-
-function stripLeadingPattern(text, re) {
-	let prev;
-	do {
-		prev = text;
-		text = text.replace(re, '');
-	} while (text !== prev);
-	return text;
-}
-
-function cleanTitleText(text) {
-	/* c8 ignore next */
-	if (!text) return '';
-	let s = stripLeadingPattern(text, INBOUND_META_RE);
-	s = stripLeadingPattern(s, OPERATOR_POLICY_RE);
-	s = s.replace(CRON_TIME_TAIL_RE, (match) => formatCronTime(match));
-	return s
-		.replace(USER_TS_RE, '')
-		.replace(CRON_UUID_RE, (_, taskName) => taskName ? `${taskName} ` : '')
-		.replace(UNTRUSTED_CTX_SUFFIX_RE, '')
-		.replace(MSG_ID_SUFFIX_RE, '')
-		.trim();
-}
+import { iterTextLines } from '../utils/text-line-stream.js';
 
 function toNum(value, fallback) {
 	const n = Number(value);
@@ -77,15 +16,36 @@ function clamp(value, min, max, fallback) {
 	return n;
 }
 
-function readJsonSafe(filePath, fallback) {
+async function readJsonSafe(filePath, fallback) {
 	try {
-		return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+		const text = await fsp.readFile(filePath, 'utf8');
+		return JSON.parse(text);
 	}
 	catch {
 		return fallback;
 	}
 }
 
+// readdir 与后续 stat 之间存在天然 race window（文件被并发删除/reset 归档）。
+// 统一把 ENOENT/ENOTDIR 视为"目录消失即空目录"，其它错误（如 EACCES）按原样上抛。
+async function safeReaddir(dir) {
+	try { return await fsp.readdir(dir); }
+	catch (err) {
+		if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return [];
+		/* c8 ignore next 2 -- 非 ENOENT/ENOTDIR 的 fs 错误按原样上抛 */
+		throw err;
+	}
+}
+
+async function safeAccess(filePath) {
+	try { await fsp.access(filePath); return true; }
+	catch (err) {
+		if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return false;
+		/* c8 ignore next 2 -- 非 ENOENT/ENOTDIR 的 fs 错误按原样上抛 */
+		throw err;
+	}
+}
+
 function parseSessionFileName(fileName) {
 	if (typeof fileName !== 'string' || !fileName.includes('.jsonl')) return null;
 	if (fileName.includes('.jsonl.delete.') || fileName.includes('.jsonl.deleted.')) return null;
@@ -118,60 +78,6 @@ function shouldReplaceByPriority(current, next) {
 	return next.updatedAt > current.updatedAt;
 }
 
-function truncateTitle(text, maxLen = DERIVED_TITLE_MAX_LEN) {
-	if (text.length <= maxLen) return text;
-	const cut = text.slice(0, maxLen - 1);
-	const lastSpace = cut.lastIndexOf(' ');
-	if (lastSpace > maxLen * 0.6) {
-		return `${cut.slice(0, lastSpace)}…`;
-	}
-	return `${cut}…`;
-}
-
-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;
-	}
-	return undefined;
-}
-
-function findFirstUserRawText(filePath, logger) {
-	const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
-	for (const line of lines) {
-		if (!line) continue;
-		try {
-			const row = JSON.parse(line);
-			if (row?.type !== 'message') continue;
-			if (row?.message?.role !== 'user') continue;
-			const raw = extractRawTextFromContent(row?.message?.content);
-			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)}`);
-		}
-	}
-	return undefined;
-}
-
-function deriveTitle(filePath, logger) {
-	const rawText = findFirstUserRawText(filePath, logger);
-	if (!rawText) return undefined;
-	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 = {}) {
 	/* c8 ignore next */
 	const logger = options.logger ?? console;
@@ -185,22 +91,22 @@ export function createSessionManager(options = {}) {
 		return resolveSessionsDir(aid);
 	}
 
-	function readIndex(agentId = 'main') {
+	async function readIndex(agentId = 'main') {
 		/* c8 ignore next */
 		const aid = typeof agentId === 'string' && agentId.trim() ? agentId.trim() : 'main';
 		const file = resolveStorePath(aid);
-		const data = readJsonSafe(file, {});
+		const data = await readJsonSafe(file, {});
 		/* c8 ignore next */
 		if (!data || typeof data !== 'object') return {};
 		return data;
 	}
 
-	function listAll(params = {}) {
+	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);
 		const cursor = clamp(params.cursor, 0, Number.MAX_SAFE_INTEGER, 0);
 		const dir = sessionsDir(agentId);
-		const index = readIndex(agentId);
+		const index = await readIndex(agentId);
 		const indexed = new Set(
 			Object.values(index)
 				.map((item) => item?.sessionId)
@@ -214,13 +120,20 @@ export function createSessionManager(options = {}) {
 			}
 		}
 
-		const files = fs.existsSync(dir) ? fs.readdirSync(dir) : [];
+		const files = await safeReaddir(dir);
 		const grouped = new Map();
 		for (const file of files) {
 			const parsed = parseSessionFileName(file);
 			if (!parsed?.sessionId) continue;
 			const full = nodePath.join(dir, file);
-			const stat = fs.statSync(full);
+			let stat;
+			try { stat = await fsp.stat(full); }
+			/* c8 ignore start -- readdir→stat race window：文件被并发删除时跳过 */
+			catch (err) {
+				if (err.code === 'ENOENT') continue;
+				throw err;
+			}
+			/* c8 ignore stop */
 			const row = {
 				sessionId: parsed.sessionId,
 				sessionKey: sessionKeyById.get(parsed.sessionId) ?? null,
@@ -256,20 +169,7 @@ export function createSessionManager(options = {}) {
 		const rows = Array.from(grouped.values());
 		rows.sort((a, b) => b.updatedAt - a.updatedAt);
 
-		const items = rows.slice(cursor, cursor + limit).map((row) => {
-			if (!row.fileName) {
-				return { ...row };
-			}
-			const transcriptPath = nodePath.join(dir, row.fileName);
-			const derivedTitle = deriveTitle(transcriptPath, logger);
-			if (!derivedTitle) {
-				return { ...row };
-			}
-			return {
-				...row,
-				derivedTitle,
-			};
-		});
+		const items = rows.slice(cursor, cursor + limit).map((row) => ({ ...row }));
 		const nextCursor = cursor + limit < rows.length ? String(cursor + limit) : null;
 		return {
 			agentId,
@@ -280,53 +180,74 @@ export function createSessionManager(options = {}) {
 		};
 	}
 
-	function resolveTranscriptFile(agentId, sessionId) {
+	async function resolveTranscriptFile(agentId, sessionId) {
 		const dir = sessionsDir(agentId);
 		// live 文件优先：同一 sessionId 可能同时存在 live 和 reset 文件
 		// （OpenClaw reset 后复用 sessionId），live 代表当前活跃 transcript
 		const livePath = resolveTranscriptPath(sessionId, agentId);
-		if (fs.existsSync(livePath)) {
-			return livePath;
-		}
-		const files = fs.existsSync(dir) ? fs.readdirSync(dir) : [];
+		if (await safeAccess(livePath)) return livePath;
+
+		const files = await safeReaddir(dir);
 		const resetPrefix = `${sessionId}.jsonl.reset.`;
-		const resetCandidates = files
-			.filter((name) => name.startsWith(resetPrefix))
-			.map((name) => {
-				const full = nodePath.join(dir, name);
-				const stat = fs.statSync(full);
-				return {
-					path: full,
-					archiveStamp: name.slice(resetPrefix.length),
-					updatedAt: stat.mtimeMs,
-				};
-			})
-			.sort((a, b) => {
-				if (a.archiveStamp !== b.archiveStamp) {
-					return b.archiveStamp.localeCompare(a.archiveStamp);
-				}
-				/* c8 ignore next -- 同一 sessionId 的 reset 文件不会有相同 archiveStamp */
-				return b.updatedAt - a.updatedAt;
+		const resetCandidates = [];
+		for (const name of files) {
+			if (!name.startsWith(resetPrefix)) continue;
+			const full = nodePath.join(dir, name);
+			let stat;
+			try { stat = await fsp.stat(full); }
+			/* c8 ignore start -- readdir→stat race window */
+			catch (err) {
+				if (err.code === 'ENOENT') continue;
+				throw err;
+			}
+			/* c8 ignore stop */
+			resetCandidates.push({
+				path: full,
+				archiveStamp: name.slice(resetPrefix.length),
+				updatedAt: stat.mtimeMs,
 			});
+		}
+		resetCandidates.sort((a, b) => {
+			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) {
 			return resetCandidates[0].path;
 		}
 		return null;
 	}
 
-	function get(params = {}) {
+	// 读 transcript 全文；不存在视为空字符串。返回原始文本，由调用方走 iterTextLines
+	// 流式扫描 + 解析，避免大文件 split 一次性卡 event loop。
+	async function readTranscriptText(file) {
+		try {
+			return await fsp.readFile(file, 'utf8');
+		}
+		/* c8 ignore start -- resolveTranscriptFile→readFile race window */
+		catch (err) {
+			if (err.code === 'ENOENT') return '';
+			throw err;
+		}
+		/* c8 ignore stop */
+	}
+
+	async function get(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, 100);
 		const cursor = clamp(params.cursor, 0, Number.MAX_SAFE_INTEGER, 0);
-		const file = resolveTranscriptFile(agentId, sessionId);
+		const file = await resolveTranscriptFile(agentId, sessionId);
 		if (!file) {
 			return { agentId, sessionId, total: 0, cursor: String(cursor), nextCursor: null, messages: [] };
 		}
 
+		const text = await readTranscriptText(file);
 		const all = [];
-		for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean)) {
+		for await (const line of iterTextLines(text)) {
 			try {
 				all.push(JSON.parse(line));
 			}
@@ -352,20 +273,21 @@ export function createSessionManager(options = {}) {
 	 * 按 sessionId 获取消息，返回完整 JSONL 行级结构。
 	 * 只返回 type==="message" 且有合法 message.role 的行。
 	 * @param {{ sessionId: string, agentId?: string, limit?: number }} params
-	 * @returns {{ messages: object[] }}
+	 * @returns {Promise<{ messages: object[] }>}
 	 */
-	function getById(params = {}) {
+	async 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);
+		const file = await resolveTranscriptFile(agentId, sessionId);
 		if (!file) {
 			return { messages: [] };
 		}
 
+		const text = await readTranscriptText(file);
 		const messages = [];
-		for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean)) {
+		for await (const line of iterTextLines(text)) {
 			try {
 				const row = JSON.parse(line);
 				if (row?.type !== 'message') continue;

package/src/utils/text-line-stream.js

@@ -0,0 +1,60 @@
+export const DEFAULT_YIELD_EVERY = 100;
+
+/**
+ * 流式扫描大字符串的行，分批让出 event loop。
+ *
+ * 不预先 split——按 \n 游标推进，避免大字符串一次性 split 卡主线程。
+ *
+ * 行终止与 split(/\r?\n/) 的语义差异：
+ * - 把 \n 视为"行终止符"而非"分隔符"。末尾 \n 之后**不产生**额外空段，即
+ *   `'foo\n'` 仅产 `['foo']`（split 会得 `['foo','']`）。`skipEmpty: false`
+ *   下亦如此——空段是"两个分隔符之间没字符"，末尾 \n 之后没有内容也没有下
+ *   一个分隔符，所以本来就不应该产空段。
+ * - 仅剥紧贴 \n 之前的 \r（CRLF 折行）。**孤立的 \r**（行内或末尾段无 \n）
+ *   按字面保留，与 split(/\r?\n/) 一致。
+ *
+ * 空行（连续 \n\n 之间的空段）按 skipEmpty 选项过滤，默认跳过。
+ *
+ * 让出策略：每处理 yieldEvery 行 await 一次 setImmediate，让 I/O 回调（如 RTC
+ * 数据通道帧、其它 RPC handler）有机会插入。Node 中首选 setImmediate 而非
+ * setTimeout(0)：后者最小延迟被钳制到 1ms，让出净开销显著更大。
+ *
+ * @param {string} text - 待扫描文本
+ * @param {{ yieldEvery?: number, skipEmpty?: boolean }} [opts]
+ * @returns {AsyncGenerator<string>}
+ */
+export async function* iterTextLines(text, opts = {}) {
+	if (typeof text !== 'string' || text.length === 0) return;
+	const yieldEvery = Number.isFinite(opts.yieldEvery) && opts.yieldEvery > 0
+		? Math.trunc(opts.yieldEvery)
+		: DEFAULT_YIELD_EVERY;
+	const skipEmpty = opts.skipEmpty !== false;
+
+	const len = text.length;
+	let start = 0;
+	let count = 0;
+
+	while (start < len) {
+		const lfIdx = text.indexOf('\n', start);
+		const terminatedByLf = lfIdx !== -1;
+		const end = terminatedByLf ? lfIdx : len;
+
+		// 仅当本段确实由 LF 终止时才剥末尾 \r（CRLF）。
+		// 末尾段（无 LF）保留原文，与 split(/\r?\n/) 行为一致——
+		// 否则 'a\r' 会被剥成 'a' 静默丢失，违反"行为等价"约定。
+		let lineEnd = end;
+		if (terminatedByLf && lineEnd > start && text.charCodeAt(lineEnd - 1) === 13) {
+			lineEnd--;
+		}
+
+		if (!skipEmpty || lineEnd > start) {
+			yield text.slice(start, lineEnd);
+		}
+
+		start = end + 1;
+
+		if (++count % yieldEvery === 0) {
+			await new Promise((resolve) => setImmediate(resolve));
+		}
+	}
+}