@ai-agent-forge/agent-forge 0.88.1 → 0.88.3

package/dist/core/session-manager.js

@@ -10,6 +10,7 @@ import { normalizePath, resolvePath } from "../utils/paths.js";
 import { AGENT_SESSIONS_DIR_NAME } from "./agent-session-paths.js";
 import { t } from "./i18n/index.js";
 import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, createInterruptedToolResultMessage, } from "./messages.js";
+import { listSessionsViaIndex, recordSessionUpdate } from "./session-index.js";
 import { FileSessionStorageProvider, SessionHeaderScanLimitError, } from "./session-storage.js";
 export const CURRENT_SESSION_VERSION = 3;
 function sameSessionRevision(left, right) {
@@ -564,6 +565,73 @@ async function buildSessionInfo(filePath, signal, fileStats) {
         return null;
     }
 }
+/**
+ * 从内存 fileEntries 派生会话索引字段（设计 docs/design/会话索引.md §4）。
+ *
+ * 与 buildSessionInfo() 逐语义对应（该函数从磁盘重读同一文件应得到相同值）：
+ * - name = 最新一条 session_info（显式空串清除）；
+ * - messageCount = 全部 message 条目数（不限角色）；
+ * - modifiedMs = 最后一条 user/assistant 消息活动时间（getMessageActivityTime），
+ *   缺失时回退 header 时间戳，再缺失（畸形 header）时回退当前时间——对应
+ *   buildSessionInfo 的 stats.mtime 兜底，钩子侧文件刚写完，mtime≈now；
+ * - firstMessage = 首条有正文的 user 消息文本，无则 "(no messages)"；
+ * - createdMs = header 时间戳；
+ * - profileId/profileVersion = header 的 profile 锁（与 buildSessionInfo 读回一致）。
+ * 返回 null 表示无会话头（无可索引字段）。
+ */
+function deriveSessionIndexFields(entries) {
+    const header = entries.find((e) => e.type === "session");
+    if (!header)
+        return null;
+    let name;
+    let messageCount = 0;
+    let firstMessage = "";
+    let lastActivityTime;
+    for (const entry of entries) {
+        if (entry.type === "session")
+            continue;
+        if (entry.type === "session_info") {
+            name = entry.name?.trim() || undefined;
+            continue;
+        }
+        if (entry.type !== "message")
+            continue;
+        messageCount++;
+        const activityTime = getMessageActivityTime(entry);
+        if (typeof activityTime === "number") {
+            lastActivityTime = Math.max(lastActivityTime ?? 0, activityTime);
+        }
+        const message = entry.message;
+        if (!isMessageWithContent(message))
+            continue;
+        if (message.role !== "user" && message.role !== "assistant")
+            continue;
+        const textContent = extractTextContent(message);
+        if (!textContent)
+            continue;
+        if (!firstMessage && message.role === "user") {
+            firstMessage = textContent;
+        }
+    }
+    const headerTime = typeof header.timestamp === "string" ? new Date(header.timestamp).getTime() : NaN;
+    return {
+        sessionId: header.id,
+        cwd: typeof header.cwd === "string" ? header.cwd : "",
+        name,
+        parentSessionPath: header.parentSession,
+        // 与 buildSessionInfo 相同的守卫：畸形 header 的非字符串值读作缺席。
+        profileId: typeof header.profileId === "string" ? header.profileId : undefined,
+        profileVersion: typeof header.profileVersion === "string" ? header.profileVersion : undefined,
+        createdMs: headerTime,
+        modifiedMs: typeof lastActivityTime === "number" && lastActivityTime > 0
+            ? lastActivityTime
+            : Number.isNaN(headerTime)
+                ? Date.now()
+                : headerTime,
+        messageCount,
+        firstMessage: firstMessage || "(no messages)",
+    };
+}
 const MAX_CONCURRENT_SESSION_INFO_LOADS = 10;
 const MAX_CONCURRENT_SESSION_DISCOVERY_LOADS = 64;
 const CURRENT_SESSION_LIST_PUBLISH_INTERVAL = 10;
@@ -618,6 +686,59 @@ async function listSessionsFromDir(dir, onProgress, signal) {
         return [];
     }
 }
+/**
+ * 旧的全量扫描：遍历 sessions 根下全部项目目录并逐文件构建 SessionInfo。
+ * 保留为索引缺失/损坏/版本不符时的重建源与 listAll 的 fail-open 降级路径
+ * （设计 docs/design/会话索引.md §5），行为与抽出前逐字节一致。
+ */
+async function scanAllSessionsFromRoot(sessionsDir, onProgress, signal) {
+    try {
+        if (!existsSync(sessionsDir))
+            return [];
+        const entries = await readdir(sessionsDir, { withFileTypes: true });
+        const dirs = entries
+            .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && entry.name !== AGENT_SESSIONS_DIR_NAME)
+            .map((entry) => join(sessionsDir, entry.name));
+        const dirFiles = await mapWithConcurrency(dirs, MAX_CONCURRENT_SESSION_DISCOVERY_LOADS, async (dir) => {
+            try {
+                return (await readdir(dir)).filter((file) => file.endsWith(".jsonl")).map((file) => join(dir, file));
+            }
+            catch {
+                return [];
+            }
+        }, signal);
+        const allFiles = dirFiles.flat();
+        const candidates = await mapWithConcurrency(allFiles, MAX_CONCURRENT_SESSION_DISCOVERY_LOADS, async (path) => {
+            try {
+                return { path, stats: await stat(path) };
+            }
+            catch {
+                return { path };
+            }
+        }, signal);
+        candidates.sort((a, b) => (b.stats?.mtimeMs ?? Number.NEGATIVE_INFINITY) - (a.stats?.mtimeMs ?? Number.NEGATIVE_INFINITY) ||
+            basename(b.path).localeCompare(basename(a.path)));
+        const totalFiles = candidates.length;
+        let loaded = 0;
+        let firstCandidateLoaded = false;
+        const partialSessions = [];
+        const results = await buildSessionInfosWithConcurrency(candidates, (info, index) => {
+            loaded++;
+            if (index === 0)
+                firstCandidateLoaded = true;
+            if (info)
+                partialSessions.push(info);
+            const publishPartial = firstCandidateLoaded &&
+                (index === 0 || loaded % ALL_SESSION_LIST_PUBLISH_INTERVAL === 0 || loaded === totalFiles);
+            onProgress?.(loaded, totalFiles, publishPartial ? sortSessionInfos([...partialSessions]) : undefined);
+        }, signal);
+        return sortSessionInfos(results.filter((info) => info !== null));
+    }
+    catch {
+        signal?.throwIfAborted();
+        return [];
+    }
+}
 /**
  * Manages conversation sessions as append-only trees stored in JSONL files.
  *
@@ -836,14 +957,46 @@ export class SessionManager {
                 return;
             this.storage.createExclusive(this.sessionFile, this.fileEntries);
             this.flushed = true;
+            // 首次落盘即预热索引条目（设计 docs/design/会话索引.md §4：写钩子是预热
+            // 优化，不承担正确性——条目缺失/过期由读路径的 mtime 令牌对账刷新）。
+            this.notifySessionIndex(true);
         }
         else {
             this.storage.append(this.sessionFile, entry);
         }
     }
+    /**
+     * 会话索引写钩子（设计 docs/design/会话索引.md §4）。定位是预热优化，不承担
+     * 正确性：条目缺失或过期由读路径的 mtime 令牌对账刷新。仅在默认布局且已落盘
+     * （flushed = 会话文件已存在于磁盘）时生效；自定义 --session-dir 与 inMemory
+     * 会话不进索引。字段从内存 fileEntries 派生（deriveSessionIndexFields，与
+     * buildSessionInfo 逐语义对齐）。索引维护的任何失败都在 recordSessionUpdate
+     * 内部吞掉，绝不影响会话持久化。
+     */
+    notifySessionIndex(immediate) {
+        if (!this.persist || !this.flushed || !this.sessionFile)
+            return;
+        if (this.sessionDir !== getDefaultSessionDirPath(this.cwd))
+            return;
+        const fields = deriveSessionIndexFields(this.fileEntries);
+        if (!fields)
+            return;
+        recordSessionUpdate({
+            sessionPath: this.sessionFile,
+            sessionId: fields.sessionId,
+            cwd: fields.cwd,
+            name: fields.name,
+            parentSessionPath: fields.parentSessionPath,
+            profileId: fields.profileId,
+            profileVersion: fields.profileVersion,
+            createdMs: fields.createdMs,
+            modifiedMs: fields.modifiedMs,
+            messageCount: fields.messageCount,
+            firstMessage: fields.firstMessage,
+            immediate,
+        });
+    }
     _appendEntry(entry) {
-        const previousEntries = this.fileEntries.slice();
-        const previousById = new Map(this.byId);
         const previousLeafId = this.leafId;
         const previousFlushed = this.flushed;
         const sessionFile = this.sessionFile;
@@ -854,10 +1007,16 @@ export class SessionManager {
         this.leafId = entry.id;
         try {
             this._persist(entry);
+            // 已落盘会话的每轮追加走节流路径（10s 窗口）；首 flush 由 _persist 内的
+            // immediate 钩子覆盖，此处不重复（previousFlushed=false）。
+            if (previousFlushed)
+                this.notifySessionIndex(false);
         }
         catch (error) {
-            this.fileEntries = previousEntries;
-            this.byId = previousById;
+            // push 与 catch 之间全同步，不可能有并发追加，pop 撤销的必是本次 entry。
+            this.fileEntries.pop();
+            if (this.byId.get(entry.id) === entry)
+                this.byId.delete(entry.id);
             this.leafId = previousLeafId;
             this.flushed = previousFlushed;
             try {
@@ -1061,6 +1220,10 @@ export class SessionManager {
             name: sanitizedName,
         };
         this._appendEntry(entry);
+        // 重命名的预热同步（设计 docs/design/会话索引.md §4）：文件已存在时立即
+        // 落盘索引；未落盘会话由 notifySessionIndex 的 flushed 守卫拦截。
+        if (this.flushed)
+            this.notifySessionIndex(true);
         return entry.id;
     }
     /** Get the current session name from the latest session_info entry, if any. */
@@ -1394,6 +1557,7 @@ export class SessionManager {
             if (this._hasConversation()) {
                 this._rewriteFile();
                 this.flushed = true;
+                this.notifySessionIndex(true);
             }
             else {
                 this.flushed = false;
@@ -1519,11 +1683,33 @@ export class SessionManager {
             cwd: resolvedTargetCwd,
             parentSession: resolvedSourcePath,
         };
-        storage.createExclusive(newSessionFile, [
+        const forkedEntries = [
             newHeader,
             // Copy all non-header entries from source
             ...sourceEntries.filter((entry) => entry.type !== "session"),
-        ]);
+        ];
+        storage.createExclusive(newSessionFile, forkedEntries);
+        // fork 直接写文件（不经 _persist），成功后预热索引条目（设计 §4：写钩子是
+        // 预热优化，不承担正确性）；仅在默认布局生效，失败吞掉（对账自愈）。
+        if (dir === getDefaultSessionDirPath(resolvedTargetCwd)) {
+            const fields = deriveSessionIndexFields(forkedEntries);
+            if (fields) {
+                recordSessionUpdate({
+                    sessionPath: newSessionFile,
+                    sessionId: fields.sessionId,
+                    cwd: fields.cwd,
+                    name: fields.name,
+                    parentSessionPath: fields.parentSessionPath,
+                    profileId: fields.profileId,
+                    profileVersion: fields.profileVersion,
+                    createdMs: fields.createdMs,
+                    modifiedMs: fields.modifiedMs,
+                    messageCount: fields.messageCount,
+                    firstMessage: fields.firstMessage,
+                    immediate: true,
+                });
+            }
+        }
         return new SessionManager(resolvedTargetCwd, dir, newSessionFile, true, undefined, undefined, storage);
     }
     /**
@@ -1585,52 +1771,21 @@ export class SessionManager {
             return sortSessionInfos(await listSessionsFromDir(customSessionDir, progress, abortSignal));
         }
         const sessionsDir = getSessionsDir();
-        try {
-            if (!existsSync(sessionsDir))
-                return [];
-            const entries = await readdir(sessionsDir, { withFileTypes: true });
-            const dirs = entries
-                .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && entry.name !== AGENT_SESSIONS_DIR_NAME)
-                .map((entry) => join(sessionsDir, entry.name));
-            const dirFiles = await mapWithConcurrency(dirs, MAX_CONCURRENT_SESSION_DISCOVERY_LOADS, async (dir) => {
-                try {
-                    return (await readdir(dir)).filter((file) => file.endsWith(".jsonl")).map((file) => join(dir, file));
-                }
-                catch {
-                    return [];
-                }
-            }, abortSignal);
-            const allFiles = dirFiles.flat();
-            const candidates = await mapWithConcurrency(allFiles, MAX_CONCURRENT_SESSION_DISCOVERY_LOADS, async (path) => {
-                try {
-                    return { path, stats: await stat(path) };
-                }
-                catch {
-                    return { path };
-                }
-            }, abortSignal);
-            candidates.sort((a, b) => (b.stats?.mtimeMs ?? Number.NEGATIVE_INFINITY) - (a.stats?.mtimeMs ?? Number.NEGATIVE_INFINITY) ||
-                basename(b.path).localeCompare(basename(a.path)));
-            const totalFiles = candidates.length;
-            let loaded = 0;
-            let firstCandidateLoaded = false;
-            const partialSessions = [];
-            const results = await buildSessionInfosWithConcurrency(candidates, (info, index) => {
-                loaded++;
-                if (index === 0)
-                    firstCandidateLoaded = true;
-                if (info)
-                    partialSessions.push(info);
-                const publishPartial = firstCandidateLoaded &&
-                    (index === 0 || loaded % ALL_SESSION_LIST_PUBLISH_INTERVAL === 0 || loaded === totalFiles);
-                progress?.(loaded, totalFiles, publishPartial ? sortSessionInfos([...partialSessions]) : undefined);
-            }, abortSignal);
-            return sortSessionInfos(results.filter((info) => info !== null));
-        }
-        catch {
-            abortSignal?.throwIfAborted();
-            return [];
+        // 默认布局走会话元数据索引（设计 docs/design/会话索引.md §5）：命中时亚秒级
+        // 返回；undefined（索引层意外 IO 失败等）fail-open 到旧全量扫描兜底。
+        const viaIndex = await listSessionsViaIndex({
+            sessionsRoot: sessionsDir,
+            buildInfo: (path) => buildSessionInfo(path, abortSignal),
+            scanAll: () => scanAllSessionsFromRoot(sessionsDir, progress, abortSignal),
+            // 索引命中路径发布单次完整已排序快照（loaded === total）；重建路径的进度
+            // 由 scanAll 按旧语义发布，不重复。
+            onHit: (sessions) => progress?.(sessions.length, sessions.length, sessions),
+            signal: abortSignal,
+        });
+        if (viaIndex !== undefined) {
+            return viaIndex;
         }
+        return scanAllSessionsFromRoot(sessionsDir, progress, abortSignal);
     }
 }
 //# sourceMappingURL=session-manager.js.map