evolcore 0.0.32 → 0.0.34

package/dist/core/thread/thread-service.js

@@ -0,0 +1,770 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { agentSessionsDir, agentDir, agentThreadIndexPath, agentThreadSummariesDir, agentThreadSummaryPath } from '../../paths.js';
+import { atomicWriteJson, atomicReadJson } from '../../utils/atomic-write.js';
+import { appendJsonl, appendJsonlDurable, readAllJsonlLines, readLastJsonlLine, readLastJsonlLineStrict, chatDirPath, tryParseChannelSessionKey } from '../session/session-fs-store.js';
+import { sanitizeSessionTitle } from '../session/session-title.js';
+import { ThreadContextStorage } from './thread-context-storage.js';
+const THREAD_ID_RE = /^thread-[0-9]+-[0-9a-f]{4}-[0-9a-f]{4}$/;
+const RESERVED_THREAD_IDS = new Set(['current', 'main', 'all']);
+const THREAD_NAME_MAX_LEN = 80;
+const LIST_DEFAULT_LIMIT = 10;
+const LIST_MAX_LIMIT = 200;
+export class ThreadServiceError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'ThreadServiceError';
+    }
+}
+function newThreadId() {
+    const ms = Date.now();
+    const seq = Math.floor(Math.random() * 9999).toString().padStart(4, '0');
+    const rand = crypto.randomBytes(2).toString('hex');
+    return `thread-${ms}-${seq}-${rand}`;
+}
+function readIndex(indexPath) {
+    const raw = atomicReadJson(indexPath);
+    if (!raw || !Array.isArray(raw.threads)) {
+        return { version: 1, threads: [] };
+    }
+    return raw;
+}
+/**
+ * 把用户传入的 peer 归一成索引里实际存储的形态（对端在该渠道下的原生 ID）。
+ *
+ * 索引的 `peer` 字段存的是裸 ID（AUN 为裸 AID，内部话题为 `bg:`/`trigger:` 标识符），
+ * 而调用方可能传入带渠道前缀的写法。两种形态都接受：
+ *   `leiliang.agentid.cn`            → `leiliang.agentid.cn`
+ *   `aun#leiliang.agentid.cn`        → `leiliang.agentid.cn`
+ *   `aun#main#leiliang.agentid.cn`   → `leiliang.agentid.cn`（channelSessionKey）
+ *
+ * 对已经是裸 ID 的输入是幂等的；解析不出前缀时原样返回（由调用方按"无此对端"处理）。
+ */
+export function normalizeThreadPeer(input) {
+    if (input == null)
+        return undefined;
+    const raw = String(input).trim();
+    if (!raw)
+        return undefined;
+    if (!raw.includes('#'))
+        return raw;
+    const seg = raw.split('#').pop() ?? '';
+    try {
+        return decodeURIComponent(seg).trim() || undefined;
+    }
+    catch {
+        return seg.trim() || undefined;
+    }
+}
+/** 内部话题（daemon 命名空间的会话记录）的对端标识前缀。 */
+const INTERNAL_PEER_RE = /^(bg:|trigger:|daemon:|memory:)/;
+/** 该条目是否为内部话题（非真实联系人，通常没有消息日志）。 */
+export function isInternalThreadPeer(peer) {
+    return INTERNAL_PEER_RE.test(peer);
+}
+function writeIndex(indexPath, index) {
+    atomicWriteJson(indexPath, index);
+}
+/**
+ * 索引条目所属的渠道类型。
+ *
+ * 新条目带 `channelType` 字段，直接采用。历史条目缺该字段，按对端形态推断：
+ * `bg:`/`trigger:` 等内部标识只可能来自 daemon 命名空间，其余按 aun。
+ * 这样不重建索引也能修好内部话题的寻址（`ec thread rebuild-index` 会把真实值写回）。
+ */
+function entryChannelType(entry) {
+    const t = (entry.channelType ?? '').trim();
+    if (t)
+        return t;
+    return entry.peer && INTERNAL_PEER_RE.test(entry.peer) ? 'daemon' : 'aun';
+}
+export class ThreadService {
+    sessionManager;
+    constructor(sessionManager) {
+        this.sessionManager = sessionManager;
+    }
+    // ── P1a.1.3: 话题索引读写 ──
+    readThreadIndex(selfAid) {
+        return readIndex(agentThreadIndexPath(selfAid));
+    }
+    writeThreadIndex(selfAid, index) {
+        const indexPath = agentThreadIndexPath(selfAid);
+        fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+        writeIndex(indexPath, index);
+    }
+    findInIndex(selfAid, peer, threadId) {
+        const want = normalizeThreadPeer(peer);
+        const index = this.readThreadIndex(selfAid);
+        return index.threads.find(t => normalizeThreadPeer(t.peer) === want && t.threadId === threadId);
+    }
+    /**
+     * 该条目对应的会话目录。
+     * chatDirPath 内部会拼出 `<agentsRoot>/<aid>/sessions/<channelSessionKey>`，
+     * 因此 sessionsRoot 必须是 agents 根目录（~/.evolcore/agents）。
+     */
+    chatDirFor(selfAid, peer, channelType) {
+        const agentsRoot = path.dirname(agentDir(selfAid));
+        return chatDirPath(agentsRoot, entryChannelType({ channelType, peer }), peer, selfAid);
+    }
+    // ── P1a.1.2: 话题创建 ──
+    async createThread(input) {
+        const { selfAid, peerKind, name, label, topicStatus } = input;
+        const peer = normalizeThreadPeer(input.peer) ?? input.peer;
+        // Validate name
+        const sanitized = sanitizeSessionTitle(name);
+        if (!sanitized)
+            throw new ThreadServiceError('话题名称不能为空', 'INVALID_NAME');
+        if (sanitized.length > THREAD_NAME_MAX_LEN) {
+            throw new ThreadServiceError(`话题名称超过 ${THREAD_NAME_MAX_LEN} 字符`, 'NAME_TOO_LONG');
+        }
+        // Check for duplicate name on same peer
+        const index = this.readThreadIndex(selfAid);
+        const dup = index.threads.find(t => t.peer === peer && t.name === sanitized);
+        if (dup) {
+            throw new ThreadServiceError(`与 ${peer} 已有同名话题: ${sanitized}`, 'TOPIC_CONFLICT');
+        }
+        const threadId = newThreadId();
+        const now = Date.now();
+        // Create local session via SessionManager
+        // channel = 'aun#<selfAid>#main', channelId = peer, defaultProjectPath = '' (threads have no project)
+        const channelKey = `aun#${selfAid}#main`;
+        const session = await this.sessionManager.getOrCreateSession(channelKey, // channel
+        peer, // channelId
+        '', // defaultProjectPath — threads are not bound to a project
+        threadId, // threadId
+        { peerName: peer }, // metadata
+        sanitized, // name
+        undefined, // userId
+        peerKind === 'group' ? 'group' : 'private', // chatType
+        undefined, // baseagent — use default
+        selfAid, // selfAID
+        'aun', // channelType
+        peerKind === 'group' ? 'group' : 'agent', // peerType
+        undefined, // identity
+        label, // label
+        topicStatus ?? 'pending');
+        const entry = {
+            threadId,
+            sessionId: session.id,
+            peer,
+            channelType: 'aun',
+            peerKind,
+            name: sanitized,
+            label: label ?? null,
+            topicStatus: topicStatus ?? 'pending',
+            createdAt: now,
+            lastActiveAt: now,
+        };
+        index.threads.push(entry);
+        this.writeThreadIndex(selfAid, index);
+        return {
+            threadId,
+            sessionId: session.id,
+            name: sanitized,
+            peer,
+            peerKind,
+            createdAt: now,
+        };
+    }
+    // ── P1a.1.5: 话题改名 ──
+    async renameThread(input) {
+        const { selfAid, threadId, name } = input;
+        const peer = normalizeThreadPeer(input.peer) ?? input.peer;
+        const sanitized = sanitizeSessionTitle(name);
+        if (!sanitized)
+            throw new ThreadServiceError('话题名称不能为空', 'INVALID_NAME');
+        if (sanitized.length > THREAD_NAME_MAX_LEN) {
+            throw new ThreadServiceError(`话题名称超过 ${THREAD_NAME_MAX_LEN} 字符`, 'NAME_TOO_LONG');
+        }
+        const index = this.readThreadIndex(selfAid);
+        const entry = index.threads.find(t => t.peer === peer && t.threadId === threadId);
+        if (!entry)
+            throw new ThreadServiceError(`话题不存在: ${threadId}`, 'TOPIC_NOT_FOUND');
+        if (entry.name === sanitized)
+            return { changed: false, name: sanitized };
+        entry.name = sanitized;
+        entry.lastActiveAt = Date.now();
+        this.writeThreadIndex(selfAid, index);
+        this.appendThreadSnapshot(selfAid, entry);
+        // Sync to session
+        const session = await this.sessionManager.getThreadSession(entryChannelType(entry), entry.peer, threadId, selfAid);
+        if (session) {
+            await this.sessionManager.renameSession(session.id, sanitized);
+        }
+        return { changed: true, name: sanitized };
+    }
+    // ── P1a.1.6: 话题标签 ──
+    async labelThread(input) {
+        const { selfAid, threadId, label } = input;
+        const peer = normalizeThreadPeer(input.peer) ?? input.peer;
+        const index = this.readThreadIndex(selfAid);
+        const entry = index.threads.find(t => t.peer === peer && t.threadId === threadId);
+        if (!entry)
+            throw new ThreadServiceError(`话题不存在: ${threadId}`, 'TOPIC_NOT_FOUND');
+        entry.label = label;
+        entry.lastActiveAt = Date.now();
+        this.writeThreadIndex(selfAid, index);
+        this.appendThreadSnapshot(selfAid, entry);
+        const session = await this.sessionManager.getThreadSession(entryChannelType(entry), entry.peer, threadId, selfAid);
+        if (session) {
+            await this.sessionManager.setTopicLabel(session.id, label);
+        }
+    }
+    // ── P1a.1.6: 话题状态 ──
+    async statusThread(input) {
+        const { selfAid, threadId, topicStatus } = input;
+        const peer = normalizeThreadPeer(input.peer) ?? input.peer;
+        const index = this.readThreadIndex(selfAid);
+        const entry = index.threads.find(t => t.peer === peer && t.threadId === threadId);
+        if (!entry)
+            throw new ThreadServiceError(`话题不存在: ${threadId}`, 'TOPIC_NOT_FOUND');
+        entry.topicStatus = topicStatus;
+        entry.lastActiveAt = Date.now();
+        this.writeThreadIndex(selfAid, index);
+        this.appendThreadSnapshot(selfAid, entry);
+        const session = await this.sessionManager.getThreadSession(entryChannelType(entry), entry.peer, threadId, selfAid);
+        if (session) {
+            await this.sessionManager.setTopicStatus(session.id, topicStatus);
+        }
+    }
+    // ── list-peers ──
+    /**
+     * 列出某个 agent 有话题记录的所有对端，按**最近活跃时间**（真实消息往来）降序。
+     *
+     * 活跃时间取自该对端消息日志的最后一行，读尾行（不整文件加载）；
+     * 无消息日志或读取失败时退回索引里的管理动作时间。
+     * 内部话题（daemon 命名空间的会话记录）不是真实联系人，不在此列。
+     */
+    listPeers(selfAid) {
+        const index = this.readThreadIndex(selfAid);
+        const map = new Map();
+        for (const entry of index.threads) {
+            // 过滤内部话题（daemon 命名空间的会话记录），这类对端不是真实联系人
+            if (isInternalThreadPeer(entry.peer))
+                continue;
+            const existing = map.get(entry.peer);
+            if (!existing) {
+                map.set(entry.peer, {
+                    peerKind: entry.peerKind,
+                    threadCount: 1,
+                    lastActiveAt: entry.lastActiveAt,
+                    channelType: entryChannelType(entry),
+                });
+            }
+            else {
+                existing.threadCount++;
+                if (entry.lastActiveAt > existing.lastActiveAt)
+                    existing.lastActiveAt = entry.lastActiveAt;
+            }
+        }
+        return Array.from(map.entries())
+            .map(([peer, v]) => {
+            // 真实活跃时间 = 消息日志末行的时间戳。
+            // 取日志值而非与索引值取大：索引里的时间来自管理动作（改名/打标签/改状态），
+            // 那不是"活跃"。日志不存在或读不出时才退回索引值，保证仍有可排序的兜底。
+            const logPath = path.join(this.chatDirFor(selfAid, peer, v.channelType), 'messages.jsonl');
+            let lastActiveAt = v.lastActiveAt;
+            try {
+                const last = readLastJsonlLineStrict(logPath);
+                if (last?.ts)
+                    lastActiveAt = last.ts;
+            }
+            catch {
+                // 消息日志缺失/损坏时保持索引值
+            }
+            return { peer, peerKind: v.peerKind, threadCount: v.threadCount, lastActiveAt };
+        })
+            .sort((a, b) => b.lastActiveAt - a.lastActiveAt);
+    }
+    // ── list ──
+    listThreads(input) {
+        const { selfAid, status, label, unlabeled, sort, page = 1, limit: rawLimit } = input;
+        const peer = normalizeThreadPeer(input.peer);
+        const limit = Math.min(rawLimit ?? LIST_DEFAULT_LIMIT, LIST_MAX_LIMIT);
+        const index = this.readThreadIndex(selfAid);
+        let threads = index.threads.filter(t => {
+            if (peer && normalizeThreadPeer(t.peer) !== peer)
+                return false;
+            if (status && t.topicStatus !== status)
+                return false;
+            if (unlabeled && t.label)
+                return false;
+            if (label && t.label !== label)
+                return false;
+            return true;
+        });
+        // 先读消息日志并派生真实活跃时间，再排序、再分页——
+        // 否则 recent 排序用的是索引里的管理动作时间，与实际展示的活跃时间不一致。
+        const ts24h = Date.now() - 86400000;
+        // 按会话目录分组，每个目录只读一次 messages.jsonl。
+        // 键用 channelType + peer，避免不同命名空间下同名对端串数据。
+        const peerMessages = new Map();
+        for (const t of threads) {
+            const key = `${entryChannelType(t)}\u0000${t.peer}`;
+            if (!peerMessages.has(key)) {
+                const logPath = path.join(this.chatDirFor(selfAid, t.peer, t.channelType), 'messages.jsonl');
+                const msgs = [];
+                if (fs.existsSync(logPath)) {
+                    try {
+                        for (const m of readAllJsonlLines(logPath)) {
+                            const payload = m.payloadSummary;
+                            const text = (typeof payload === 'object' && payload !== null)
+                                ? (payload.text ?? payload.content ?? '')
+                                : (m.content ?? '');
+                            msgs.push({
+                                threadId: m.threadId ?? null,
+                                ts: m.ts ?? 0,
+                                snippet: String(text).replace(/\n/g, ' ').slice(0, 50),
+                            });
+                        }
+                    }
+                    catch { /* skip corrupt file */ }
+                }
+                peerMessages.set(key, msgs);
+            }
+        }
+        // 每条话题的最后一条消息 → 真实活跃时间。
+        // 不与索引值取大：索引里的时间来自管理动作（改名/打标签/改状态），不是活跃。
+        // 无消息时才退回索引值，保证空话题仍有可排序的兜底。
+        const lastMsgOf = new Map();
+        for (const t of threads) {
+            const msgs = (peerMessages.get(`${entryChannelType(t)}\u0000${t.peer}`) ?? [])
+                .filter(m => m.threadId === t.threadId);
+            const lastMsg = msgs.reduce((acc, m) => (!acc || m.ts > acc.ts) ? m : acc, null);
+            if (lastMsg)
+                lastMsgOf.set(t.threadId, lastMsg);
+        }
+        if (sort === 'created') {
+            threads.sort((a, b) => b.createdAt - a.createdAt);
+        }
+        else {
+            threads.sort((a, b) => (lastMsgOf.get(b.threadId)?.ts || b.lastActiveAt)
+                - (lastMsgOf.get(a.threadId)?.ts || a.lastActiveAt));
+        }
+        const total = threads.length;
+        const offset = (page - 1) * limit;
+        threads = threads.slice(offset, offset + limit);
+        threads = threads.map(t => {
+            const msgs = (peerMessages.get(`${entryChannelType(t)}\u0000${t.peer}`) ?? [])
+                .filter(m => m.threadId === t.threadId);
+            const msgTotal = msgs.length;
+            const msg24h = msgs.filter(m => m.ts >= ts24h).length;
+            const lastMsg = lastMsgOf.get(t.threadId);
+            const lastActiveAt = lastMsg?.ts || t.lastActiveAt;
+            // 读该话题的 summary（当前最新版本）
+            const summaryEntry = this.showSummary(selfAid, t.sessionId);
+            const summarySnippet = summaryEntry
+                ? summaryEntry.content.replace(/\n/g, ' ').slice(0, 100)
+                : undefined;
+            return {
+                ...t,
+                lastActiveAt,
+                internal: isInternalThreadPeer(t.peer),
+                msgTotal,
+                msg24h,
+                lastMsgSnippet: lastMsg?.snippet ?? '',
+                summarySnippet,
+            };
+        });
+        const totalMsgCount = threads.reduce((sum, t) => sum + (t.msgTotal ?? 0), 0);
+        return { threads, total, page, limit, hasMore: offset + threads.length < total, totalMsgCount, peer, selfAid, sort, status, label };
+    }
+    // ── show ──
+    async showThread(input) {
+        const { selfAid, peer, threadId } = input;
+        const entry = this.findInIndex(selfAid, peer, threadId);
+        if (!entry)
+            throw new ThreadServiceError(`话题不存在: ${threadId}`, 'TOPIC_NOT_FOUND');
+        // getThreadSession is only used to derive the `running` flag; if it fails
+        // (e.g. baseagent is empty in an old session file), fall back to running=false
+        // rather than letting the error propagate and block the whole show operation.
+        let running = false;
+        try {
+            const session = await this.sessionManager.getThreadSession(entryChannelType(entry), entry.peer, threadId, selfAid);
+            running = session?.processingState?.startsWith('processing') ?? false;
+        }
+        catch {
+            // ignore — running defaults to false
+        }
+        return { ...entry, running };
+    }
+    // ── history ──
+    /**
+     * 读取某话题（或主会话）的全部消息，时间正序。
+     *
+     * 从 messages.jsonl 按 threadId 过滤出该话题（或主会话）的全部消息，时间正序。
+     * historyThread 在其上做 direction / 时间区间过滤与分页；summary 游标取末条 ts。
+     */
+    _readThreadMessages(selfAid, peerInput, threadId) {
+        const peer = normalizeThreadPeer(peerInput) ?? peerInput;
+        // 不检查索引——允许读取已删除话题的历史（session 文件已移入 _trash，但 messages.jsonl 仍在）
+        // 索引里能查到条目时用条目的命名空间（内部话题在 daemon 下），查不到时退回 aun。
+        const indexed = this.readThreadIndex(selfAid).threads.find(t => t.threadId === threadId && normalizeThreadPeer(t.peer) === peer);
+        const chatDir = this.chatDirFor(selfAid, indexed?.peer ?? peer, indexed?.channelType);
+        const logPath = path.join(chatDir, 'messages.jsonl');
+        if (!fs.existsSync(logPath))
+            return { peer, messages: [] };
+        const messages = readAllJsonlLines(logPath)
+            .filter((m) => {
+            // threadId 为 undefined/null 时读主会话消息（threadId === null 的行），
+            // 否则按 threadId 精确匹配子话题消息。
+            if (threadId)
+                return m.threadId === threadId;
+            return m.threadId == null;
+        })
+            .map((m) => {
+            // 消息体优先取 payloadSummary.text（加密消息的明文摘要），
+            // 其次 content 字段，最后降级为空字符串。
+            const payload = m.payloadSummary;
+            const text = (typeof payload === 'object' && payload !== null)
+                ? (payload.text ?? payload.content ?? '')
+                : (m.content ?? '');
+            return {
+                msgId: String(m.msgId ?? m.id ?? ''),
+                dir: m.dir ?? 'in',
+                from: m.from ?? '',
+                to: m.to ?? '',
+                time: new Date(m.ts ?? 0).toLocaleString('zh-CN'),
+                timestamp: m.ts ?? 0,
+                msgType: m.msgType ?? 'text',
+                content: String(text),
+                sessionId: '',
+            };
+        });
+        return { peer, messages };
+    }
+    async historyThread(input) {
+        const { selfAid, threadId, limit = 50, before, after, direction = 'all' } = input;
+        const { peer, messages: all } = this._readThreadMessages(selfAid, input.peer, threadId);
+        const filtered = all.filter(m => {
+            if (direction === 'in' && m.dir !== 'in')
+                return false;
+            if (direction === 'out' && m.dir !== 'out')
+                return false;
+            if (before && m.timestamp > before)
+                return false;
+            if (after && m.timestamp < after)
+                return false;
+            return true;
+        });
+        const shown = filtered.slice(-limit);
+        return {
+            count: Math.min(filtered.length, limit),
+            total: filtered.length,
+            messages: shown,
+            threadId: threadId ?? '',
+            peer,
+        };
+    }
+    // ── index rebuild ──
+    async rebuildIndex(selfAid, dryRun = false) {
+        const sessionsDir = agentSessionsDir(selfAid);
+        const entries = [];
+        for (const dirEntry of fs.readdirSync(sessionsDir, { withFileTypes: true })) {
+            if (!dirEntry.isDirectory())
+                continue;
+            const chatDir = path.join(sessionsDir, dirEntry.name);
+            const threadsDir = path.join(chatDir, '_threads');
+            if (!fs.existsSync(threadsDir))
+                continue;
+            for (const f of fs.readdirSync(threadsDir, { withFileTypes: true })) {
+                if (!f.isFile() || !f.name.endsWith('.jsonl'))
+                    continue;
+                const sessionId = f.name.replace('.jsonl', '');
+                const metaPath = path.join(threadsDir, f.name);
+                try {
+                    const lines = readAllJsonlLines(metaPath);
+                    const last = lines[lines.length - 1];
+                    if (!last?.threadId)
+                        continue;
+                    // 渠道类型从目录名（channelSessionKey）解析，避免把 daemon 会话记成 aun。
+                    const parsedDir = tryParseChannelSessionKey(dirEntry.name);
+                    entries.push({
+                        threadId: last.threadId,
+                        sessionId,
+                        peer: last.channelId ?? '',
+                        channelType: parsedDir?.channelType ?? 'aun',
+                        peerKind: last.chatType === 'group' ? 'group' : 'private',
+                        name: last.name ?? last.threadId,
+                        label: last.label ?? null,
+                        topicStatus: last.topicStatus ?? 'pending',
+                        createdAt: last.createdAt ?? 0,
+                        lastActiveAt: last.updatedAt ?? 0,
+                    });
+                }
+                catch {
+                    // Skip corrupt files
+                }
+            }
+        }
+        if (!dryRun) {
+            const index = { version: 1, threads: entries };
+            this.writeThreadIndex(selfAid, index);
+        }
+        return { rebuilt: entries.length };
+    }
+    /**
+     * 检查话题索引的健康状态，区分两类问题：
+     *   missing — _threads JSONL 文件不存在（数据问题，严重，rebuild 会丢失属性改动）
+     *   stale   — 文件存在但最后一行的 name/label/topicStatus 与索引不一致（写盘时序问题，轻微）
+     */
+    checkIndex(selfAid) {
+        const index = this.readThreadIndex(selfAid);
+        const missingIds = [];
+        const staleIds = [];
+        for (const entry of index.threads) {
+            // 按条目自己的命名空间（aun / daemon）拼目录。历史上这里写死 `aun#main#`，
+            // 导致 daemon 命名空间的内部话题 100% 被误判为 missing。
+            const chatDir = this.chatDirFor(selfAid, entry.peer, entry.channelType);
+            const metaPath = path.join(chatDir, '_threads', `${entry.sessionId}.jsonl`);
+            if (!fs.existsSync(metaPath)) {
+                missingIds.push(entry.threadId);
+                continue;
+            }
+            // 检查最后一行是否与索引一致（name / label / topicStatus）
+            try {
+                const lines = readAllJsonlLines(metaPath);
+                const last = lines[lines.length - 1];
+                if (last && (last.name !== entry.name ||
+                    (last.label ?? null) !== (entry.label ?? null) ||
+                    (last.topicStatus ?? 'pending') !== entry.topicStatus)) {
+                    staleIds.push(entry.threadId);
+                }
+            }
+            catch {
+                // 文件损坏，归入 missing
+                missingIds.push(entry.threadId);
+            }
+        }
+        return {
+            total: index.threads.length,
+            missing: missingIds.length, missingIds,
+            stale: staleIds.length, staleIds,
+        };
+    }
+    /**
+     * 查主会话（show <peer> 不带 threadId）：读取与某对端的 active session。
+     */
+    async showMainSession(selfAid, peer) {
+        const normalized = normalizeThreadPeer(peer) ?? peer;
+        const channelKey = `aun#${selfAid}#main`;
+        const session = await this.sessionManager.getActiveSession(channelKey, normalized);
+        if (!session)
+            return undefined;
+        return {
+            threadId: session.threadId ?? '',
+            sessionId: session.id,
+            peer: normalized,
+            channelType: 'aun',
+            peerKind: session.chatType === 'group' ? 'group' : 'private',
+            name: session.name ?? peer,
+            label: session.label ?? null,
+            topicStatus: session.topicStatus ?? 'pending',
+            createdAt: session.createdAt ?? 0,
+            lastActiveAt: session.updatedAt ?? 0,
+            running: session.processingState?.startsWith('processing') ?? false,
+        };
+    }
+    // ── touch (update lastActiveAt) ──
+    touchThread(selfAid, peer, threadId) {
+        const want = normalizeThreadPeer(peer);
+        const indexPath = agentThreadIndexPath(selfAid);
+        const index = readIndex(indexPath);
+        const entry = index.threads.find(t => normalizeThreadPeer(t.peer) === want && t.threadId === threadId);
+        if (!entry)
+            return;
+        entry.lastActiveAt = Date.now();
+        fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+        writeIndex(indexPath, index);
+    }
+    // ── P2.1: 话题删除 ──
+    /**
+     * 删除话题：与 Menu /topic delete 保持一致，走 unbindSession 软删除机制
+     * （session 文件移入 chatDir/_trash/，索引条目直接删除）。
+     * 禁止删除：busy（processingState 有值）的话题，以及 threadId 为空的主会话。
+     */
+    async deleteThread(selfAid, peer, threadId) {
+        if (!threadId)
+            throw new ThreadServiceError('不能删除主会话', 'NOT_A_TOPIC');
+        const want = normalizeThreadPeer(peer);
+        const indexPath = agentThreadIndexPath(selfAid);
+        const index = readIndex(indexPath);
+        const entryIdx = index.threads.findIndex(t => normalizeThreadPeer(t.peer) === want && t.threadId === threadId);
+        if (entryIdx < 0)
+            throw new ThreadServiceError(`话题不存在: ${threadId}`, 'TOPIC_NOT_FOUND');
+        const entry = index.threads[entryIdx];
+        // 检查话题会话是否繁忙
+        const session = await this.sessionManager.getSessionById(entry.sessionId).catch(() => null);
+        if (session?.processingState) {
+            throw new ThreadServiceError(`话题正在处理中，无法删除: ${threadId}`, 'TOPIC_BUSY');
+        }
+        // 通过 unbindSession 软删除（与 Menu /topic delete 行为一致）
+        await this.sessionManager.unbindSession(entry.sessionId);
+        // 从 agent 级话题索引删掉条目
+        index.threads.splice(entryIdx, 1);
+        fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+        writeIndex(indexPath, index);
+    }
+    // ── ref resolution ──
+    static resolveRef(ref) {
+        if (ref === 'current')
+            return { kind: 'current' };
+        const slash = ref.lastIndexOf('/');
+        if (slash < 0)
+            return { kind: 'peer', peer: ref };
+        return { kind: 'thread', peer: ref.slice(0, slash), threadId: ref.slice(slash + 1) };
+    }
+    /**
+     * 按 sessionId 在话题索引里反查 peer + threadId。
+     * 用于 daemon 侧把 "current" ref 解析成具体话题。
+     */
+    resolveCurrentThread(selfAid, sessionId) {
+        const index = this.readThreadIndex(selfAid);
+        const entry = index.threads.find(t => t.sessionId === sessionId);
+        if (entry)
+            return { peer: entry.peer, threadId: entry.threadId };
+        return undefined;
+    }
+    /**
+     * 把话题的当前元数据追加一行到 _threads/<sessionId>.jsonl，
+     * 使 rebuildIndex 读最后一行时能拿到 rename/label/status 后的最新值。
+     * 追加的行以最后一行（当前权威快照）为底，只覆盖话题字段，
+     * 确保 readMetaLatest 读最后一行时不报 "baseagent is empty"。
+     *
+     * 不能从第一行继承：第一行是创建记录，agentSessionId 为 null、没有 turnState，
+     * 继承它会把已绑定的后端会话冲掉；而且 meta 文件超限压缩后第一行也不再是创建记录。
+     */
+    appendThreadSnapshot(selfAid, entry) {
+        const chatDir = this.chatDirFor(selfAid, entry.peer, entry.channelType);
+        const metaPath = path.join(chatDir, '_threads', `${entry.sessionId}.jsonl`);
+        if (!fs.existsSync(metaPath))
+            return;
+        const latest = readLastJsonlLine(metaPath) ?? {};
+        const now = entry.lastActiveAt;
+        appendJsonlDurable(metaPath, {
+            // session fields (id, baseagent, agentSessionId, metadata, activeTask...) — from the latest snapshot
+            ...latest,
+            id: latest.id ?? entry.sessionId,
+            projectPath: latest.projectPath ?? '',
+            chatType: entry.peerKind === 'group' ? 'group' : 'private',
+            metadata: latest.metadata ?? {},
+            // topic metadata — updated values
+            threadId: entry.threadId,
+            channelIdAlias: entry.peer,
+            name: entry.name,
+            label: entry.label,
+            topicStatus: entry.topicStatus,
+            createdAt: entry.createdAt,
+            createdAtStr: latest.createdAtStr ?? '',
+            updatedAt: now,
+            updatedAtStr: new Date(now).toISOString(),
+        });
+    }
+    // ── P1b static helpers (SessionManager 不参与) ──
+    /** 按 threadId 查找话题条目。用于 CLI 层校验，不需要实例化。 */
+    static findThreadById(selfAid, threadId) {
+        const index = readIndex(agentThreadIndexPath(selfAid));
+        return index.threads.find(t => t.threadId === threadId);
+    }
+    // ── Thread Context inbox（跨会话上下文的提醒缓存） ──
+    /** 跨话题发送成功后写入本端 inbox。 */
+    static appendInbox(selfAid, entry) {
+        new ThreadContextStorage().append(selfAid, entry);
+    }
+    /** 读取某会话的全部待注入 inbox 记录（含空洞检测结果）。 */
+    static readInbox(selfAid, targetSessionId) {
+        const storage = new ThreadContextStorage();
+        return storage.readAll(selfAid, targetSessionId).map(entry => ({
+            ...entry,
+            gapDetection: storage.detectGap(selfAid, entry.originSessionId, entry.timestamp),
+        }));
+    }
+    /** 注入完成后删除 inbox（注入一次语义）。 */
+    static clearInbox(selfAid, targetSessionId) {
+        new ThreadContextStorage().deleteFile(selfAid, targetSessionId);
+    }
+    // ── P3.1: 话题 summary 读写 ──
+    /**
+     * 写入一条 summary 记录（追加到 JSONL）。
+     * 支持 CAS：若传入 ifRev，只有当前最新版本号匹配时才写入。
+     *
+     * 自动记录 `coveredThroughTs`：写入时刻该话题最后一条消息的时间戳，
+     * 作为"这条摘要覆盖到哪"的游标。下次总结时用它作 `history --after` 起点，
+     * 只读增量。话题为空（或主会话无消息）时不记录该字段。
+     */
+    setSummary(selfAid, sessionId, content, ifRev) {
+        const dir = agentThreadSummariesDir(selfAid);
+        fs.mkdirSync(dir, { recursive: true });
+        const filePath = agentThreadSummaryPath(selfAid, sessionId);
+        const existing = this._readSummaryLines(filePath);
+        const currentRev = existing.length;
+        if (ifRev !== undefined && ifRev !== currentRev) {
+            throw new ThreadServiceError(`summary CAS 冲突：期望版本 ${ifRev}，当前版本 ${currentRev}`, 'SUMMARY_CAS_CONFLICT');
+        }
+        const coveredThroughTs = this.resolveCoveredThroughTs(selfAid, sessionId);
+        const entry = {
+            rev: currentRev + 1,
+            content,
+            updatedAt: Date.now(),
+            ...(coveredThroughTs !== undefined ? { coveredThroughTs } : {}),
+        };
+        appendJsonl(filePath, entry);
+        return { rev: entry.rev, ...(coveredThroughTs !== undefined ? { coveredThroughTs } : {}) };
+    }
+    /**
+     * 取该话题最新一条消息的时间戳，作为摘要的覆盖游标。
+     *
+     * 话题内总结时这就是"当前消息"，跨话题总结时（先读全增量再写）也是同一语义。
+     * 话题不存在或无消息时返回 undefined——此时摘要没有游标，下次总结只能全量读。
+     */
+    resolveCoveredThroughTs(selfAid, sessionId) {
+        const entry = this.readThreadIndex(selfAid).threads.find(t => t.sessionId === sessionId);
+        if (!entry)
+            return undefined;
+        const { messages } = this._readThreadMessages(selfAid, entry.peer, entry.threadId);
+        if (messages.length === 0)
+            return undefined;
+        return messages[messages.length - 1].timestamp;
+    }
+    /** 读取当前 summary（最新版本）。若不存在或已清空则返回 undefined。 */
+    showSummary(selfAid, sessionId) {
+        const filePath = agentThreadSummaryPath(selfAid, sessionId);
+        if (!fs.existsSync(filePath))
+            return undefined;
+        const all = readAllJsonlLines(filePath);
+        if (all.length === 0)
+            return undefined;
+        const last = all[all.length - 1];
+        if (last.content === null)
+            return undefined; // 已 clear
+        return last;
+    }
+    /** 读取 summary 全部历史版本（含 set 操作，不含 clear 墓碑）。 */
+    logSummary(selfAid, sessionId) {
+        const filePath = agentThreadSummaryPath(selfAid, sessionId);
+        return this._readSummaryLines(filePath);
+    }
+    /**
+     * 清空当前 summary（追加 content=null 的墓碑记录，历史版本保留）。
+     * 清空后 showSummary 返回 undefined，logSummary 仍有历史。
+     */
+    clearSummary(selfAid, sessionId) {
+        const filePath = agentThreadSummaryPath(selfAid, sessionId);
+        const existing = this._readSummaryLines(filePath);
+        if (existing.length === 0)
+            return; // 已无内容，幂等
+        const dir = agentThreadSummariesDir(selfAid);
+        fs.mkdirSync(dir, { recursive: true });
+        appendJsonl(filePath, { rev: existing.length + 1, content: null, updatedAt: Date.now() });
+    }
+    _readSummaryLines(filePath) {
+        if (!fs.existsSync(filePath))
+            return [];
+        const all = readAllJsonlLines(filePath);
+        // 过滤掉 clear 墓碑（content=null），只返回实际写入的版本
+        return all.filter(l => l.content !== null);
+    }
+}