evolcore 0.0.1 → 0.0.3

package/dist/core/role/runtime-policy.js

@@ -0,0 +1,141 @@
+import { getRoleDefinition } from '../../config/roles.js';
+import { PUBLIC_PERMISSION_MODES } from '../permission/mode.js';
+const PERMISSION_MODE_AUTHORITY = {
+    readonly: 0,
+    auto: 1,
+    request: 2,
+    bypass: 3,
+};
+/** Resolve permissionMode exclusively from the selected role policy. */
+export function resolveRuntimePermissionMode(input) {
+    const role = input.role || 'none';
+    const definition = getRoleDefinition(role, input.selfAid);
+    const configured = definition?.permissions?.permissionMode?.default;
+    if (typeof configured !== 'string' || !PUBLIC_PERMISSION_MODES.includes(configured)) {
+        return {
+            effectiveValue: 'readonly',
+            role,
+            decidedBy: 'safe-fallback',
+            reason: !definition
+                ? 'role_not_found'
+                : configured === undefined ? 'role_permission_mode_missing' : 'role_permission_mode_invalid',
+        };
+    }
+    return {
+        effectiveValue: configured,
+        role,
+        decidedBy: 'role',
+    };
+}
+/** Keep a per-run override at or below the authority granted by the current role. */
+export function constrainRuntimePermissionMode(input) {
+    const roleDecision = resolveRuntimePermissionMode(input);
+    if (input.requestedValue === undefined || input.requestedValue === null || input.requestedValue === '') {
+        return { ...roleDecision, constrained: false };
+    }
+    const requestedValue = PUBLIC_PERMISSION_MODES.includes(input.requestedValue)
+        ? input.requestedValue
+        : 'readonly';
+    if (PERMISSION_MODE_AUTHORITY[requestedValue] > PERMISSION_MODE_AUTHORITY[roleDecision.effectiveValue]) {
+        return {
+            ...roleDecision,
+            requestedValue,
+            constrained: true,
+            reason: 'role_authority_ceiling',
+        };
+    }
+    return {
+        effectiveValue: requestedValue,
+        role: roleDecision.role,
+        requestedValue,
+        decidedBy: 'override',
+        constrained: false,
+    };
+}
+/** Apply an optional role policy to a resolved string-valued config field. */
+export function resolveRuntimeStringField(input) {
+    const role = input.role || 'none';
+    const configuredValue = typeof input.configuredValue === 'string'
+        && input.configuredValue.trim().length > 0
+        ? input.configuredValue
+        : undefined;
+    const policy = getRoleDefinition(role, input.selfAid)?.permissions?.[input.field];
+    const defaultValue = typeof policy?.default === 'string' && policy.default.trim().length > 0
+        ? policy.default
+        : undefined;
+    // Missing or malformed policies must not erase otherwise valid runtime config.
+    if (!policy || defaultValue === undefined) {
+        return {
+            effectiveValue: configuredValue,
+            role,
+            field: input.field,
+            decidedBy: configuredValue === undefined ? 'unconfigured' : 'configured',
+            constrained: false,
+        };
+    }
+    if (!policy.allowOverride) {
+        return {
+            effectiveValue: defaultValue,
+            role,
+            field: input.field,
+            decidedBy: 'role',
+            constrained: true,
+            reason: 'override_disabled',
+        };
+    }
+    if (configuredValue === undefined) {
+        return {
+            effectiveValue: defaultValue,
+            role,
+            field: input.field,
+            decidedBy: 'role',
+            constrained: true,
+            reason: 'configured_value_missing',
+        };
+    }
+    const allowedValues = Array.isArray(policy.allowedValues)
+        ? policy.allowedValues.filter((value) => typeof value === 'string')
+        : [];
+    if (allowedValues.length > 0 && !allowedValues.includes(configuredValue)) {
+        return {
+            effectiveValue: defaultValue,
+            role,
+            field: input.field,
+            decidedBy: 'role',
+            constrained: true,
+            reason: 'value_not_allowed',
+        };
+    }
+    return {
+        effectiveValue: configuredValue,
+        role,
+        field: input.field,
+        decidedBy: 'configured',
+        constrained: false,
+    };
+}
+/** Validate a relation-level string override before it is persisted. */
+export function validateRuntimeStringFieldOverride(input) {
+    const role = input.role || 'none';
+    const policy = getRoleDefinition(role, input.selfAid)?.permissions?.[input.field];
+    if (!policy)
+        return { ok: true };
+    if (!policy.allowOverride) {
+        return {
+            ok: false,
+            code: 'ROLE_OVERRIDE_DISABLED',
+            message: `Role ${role} cannot override ${input.field}`,
+        };
+    }
+    const allowedValues = Array.isArray(policy.allowedValues)
+        ? policy.allowedValues.filter((value) => typeof value === 'string')
+        : [];
+    if (allowedValues.length > 0 && !allowedValues.includes(input.value)) {
+        return {
+            ok: false,
+            code: 'ROLE_VALUE_NOT_ALLOWED',
+            message: `Value ${input.value} is not allowed for ${input.field} by role ${role}`,
+        };
+    }
+    return { ok: true };
+}

package/dist/core/session/adapters/claude-session-file-adapter.js

@@ -0,0 +1,218 @@
+/**
+ * Claude SessionFileAdapter
+ *
+ * Reads Claude Agent SDK session files from ~/.claude/projects/{encodedPath}/{sessionId}.jsonl
+ * and wraps sdkListSessions for name synchronization.
+ */
+import { listSessions as sdkListSessions } from '@anthropic-ai/claude-agent-sdk';
+import { encodePath } from '../../../utils/cross-platform.js';
+import { logger } from '../../../utils/logger.js';
+import { buildCliSessionPreview } from '../session-title.js';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+export class ClaudeSessionFileAdapter {
+    baseagent = 'claude';
+    getSessionFilePath(projectPath, agentSessionId) {
+        const homeDir = os.homedir();
+        const encodedPath = encodePath(projectPath);
+        return path.join(homeDir, '.claude', 'projects', encodedPath, `${agentSessionId}.jsonl`);
+    }
+    checkExists(projectPath, agentSessionId) {
+        const sessionFile = this.getSessionFilePath(projectPath, agentSessionId);
+        return fs.existsSync(sessionFile);
+    }
+    getFileInfo(projectPath, agentSessionId) {
+        const sessionFile = this.getSessionFilePath(projectPath, agentSessionId);
+        if (!fs.existsSync(sessionFile))
+            return { turns: 0 };
+        try {
+            const content = fs.readFileSync(sessionFile, 'utf-8');
+            const lines = content.split('\n').filter(l => l.trim());
+            let turns = 0;
+            let title;
+            for (const line of lines) {
+                const event = JSON.parse(line);
+                if (event.type === 'user' && event.message?.role === 'user') {
+                    const msgContent = event.message.content;
+                    const isToolResult = Array.isArray(msgContent) && msgContent.every((c) => c.type === 'tool_result');
+                    if (!isToolResult) {
+                        turns++;
+                    }
+                }
+                if (event.title && !title) {
+                    title = event.title;
+                }
+                if (event.sessionTitle && !title) {
+                    title = event.sessionTitle;
+                }
+            }
+            return { turns, title };
+        }
+        catch (error) {
+            logger.warn(`[ClaudeAdapter] Failed to read session file info: ${sessionFile}`, error);
+            return { turns: 0 };
+        }
+    }
+    readFirstMessage(projectPath, agentSessionId) {
+        const sessionFile = this.getSessionFilePath(projectPath, agentSessionId);
+        if (!fs.existsSync(sessionFile))
+            return null;
+        return this.readSessionPreview(sessionFile).title;
+    }
+    /**
+     * 单遍扫描会话文件，返回预览标题及是否含真人消息。
+     * - title：第一条真人消息（跳过脚手架 prompt）；全是脚手架时退回首条脚手架文本作兜底
+     * - hasReal：是否存在至少一条真人 user 消息（非 tool_result、非脚手架 prompt）
+     * 读失败时 title=null、hasReal=true（保守放行，避免误杀正常会话）。
+     */
+    readSessionPreview(sessionFile) {
+        try {
+            const content = fs.readFileSync(sessionFile, 'utf-8');
+            const lines = content.split('\n').filter(l => l.trim());
+            const messages = [];
+            for (const line of lines) {
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (event.type === 'user' && event.message?.role === 'user') {
+                    const raw = this.extractRawUserText(event.message.content);
+                    if (!raw)
+                        continue;
+                    messages.push(raw);
+                }
+            }
+            return buildCliSessionPreview(messages, 'claude');
+        }
+        catch (error) {
+            logger.warn(`[ClaudeAdapter] Failed to read session file: ${sessionFile}`, error);
+            return { title: null, hasReal: true };
+        }
+    }
+    readLastUserMessage(projectPath, agentSessionId) {
+        const sessionFile = this.getSessionFilePath(projectPath, agentSessionId);
+        if (!fs.existsSync(sessionFile))
+            return null;
+        try {
+            const content = fs.readFileSync(sessionFile, 'utf-8');
+            const lines = content.split('\n').filter(l => l.trim());
+            let lastMessage = null;
+            for (const line of lines) {
+                const event = JSON.parse(line);
+                if (event.type === 'user' && event.message?.role === 'user') {
+                    lastMessage = this.extractUserMessageText(event.message.content) ?? lastMessage;
+                }
+            }
+            return lastMessage;
+        }
+        catch (error) {
+            logger.warn(`[ClaudeAdapter] Failed to read last message from session file: ${sessionFile}`, error);
+        }
+        return null;
+    }
+    // CLI 会话白名单：只有真正由人手发起的终端会话才值得导入。
+    // 其它 entrypoint（sdk-ts=EvolCore 自身、sdk-py=security-guidance 等插件的后台 SDK 会话）
+    // 同样把 JSONL 写进项目目录，但不是用户会话，导入它们没有意义。
+    static CLI_ENTRYPOINTS = new Set(['cli', 'sdk-cli']);
+    // entrypoint 不可变，进程内缓存 filePath→entrypoint，避免重复读文件头部
+    entrypointCache = new Map();
+    // entrypoint 字段位于首个 user 事件行（实测恒在前 4 行内，cli 会话首次出现 < 8KB）。
+    // 插件会话首行 queue-operation 可能携带巨大 diff（数百 KB），把 entrypoint 推到很后面，
+    // 因此读取上限设为 32KB：cli 会话必命中，插件会话要么命中 sdk-py、要么读不到 → 一律排除。
+    static ENTRYPOINT_SCAN_BYTES = 32 * 1024;
+    /** 读取会话文件的 entrypoint，结果缓存在实例内（entrypoint 不可变，无需失效）。 */
+    readEntrypoint(filePath) {
+        if (this.entrypointCache.has(filePath))
+            return this.entrypointCache.get(filePath);
+        let fd;
+        let result = null;
+        try {
+            fd = fs.openSync(filePath, 'r');
+            const buf = Buffer.allocUnsafe(ClaudeSessionFileAdapter.ENTRYPOINT_SCAN_BYTES);
+            const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
+            const head = buf.toString('utf-8', 0, bytesRead);
+            const m = head.match(/"entrypoint":"([^"]*)"/);
+            result = m ? m[1] : null;
+        }
+        catch {
+            // keep null
+        }
+        finally {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+        }
+        this.entrypointCache.set(filePath, result);
+        return result;
+    }
+    scanCliSessions(projectPath, limit = 10) {
+        const homeDir = os.homedir();
+        const encodedPath = encodePath(projectPath);
+        const sessionDir = path.join(homeDir, '.claude', 'projects', encodedPath);
+        if (!fs.existsSync(sessionDir))
+            return [];
+        const candidates = fs.readdirSync(sessionDir)
+            .filter(f => f.endsWith('.jsonl'))
+            .filter(f => !f.startsWith('agent-'))
+            .map(f => {
+            const filePath = path.join(sessionDir, f);
+            const stat = fs.statSync(filePath);
+            return { uuid: f.replace('.jsonl', ''), filePath, mtime: stat.mtimeMs, size: stat.size };
+        })
+            .filter(f => f.size > 0)
+            .sort((a, b) => b.mtime - a.mtime);
+        // 按 mtime 降序惰性判定 entrypoint，凑够调用方要求的数量即停，避免读取全部文件。
+        // 通过 entrypoint 白名单后，单遍扫描文件取预览标题并判定是否含真人消息，
+        // 排除整段都是 Claude Code 脚手架 prompt（斜杠命令 / skill / hook 探测）的空壳会话。
+        const result = [];
+        for (const f of candidates) {
+            const entrypoint = this.readEntrypoint(f.filePath);
+            if (entrypoint && ClaudeSessionFileAdapter.CLI_ENTRYPOINTS.has(entrypoint)) {
+                const preview = this.readSessionPreview(f.filePath);
+                if (!preview.hasReal)
+                    continue;
+                result.push({ uuid: f.uuid, mtime: f.mtime, title: preview.title || undefined });
+                if (result.length >= limit)
+                    break;
+            }
+        }
+        return result;
+    }
+    async listSdkSessions(projectPath) {
+        try {
+            const sessions = await sdkListSessions({ dir: projectPath });
+            return sessions.map(s => ({
+                sessionId: s.sessionId,
+                title: s.customTitle || undefined,
+            }));
+        }
+        catch (error) {
+            logger.debug('[ClaudeAdapter] SDK listSessions failed (non-critical):', error);
+            return [];
+        }
+    }
+    /** 提取 user 事件的原始文本（未截断），用于合成 prompt 判定。 */
+    extractRawUserText(messageContent) {
+        if (typeof messageContent === 'string') {
+            const text = messageContent.trim().replace(/\s+/g, ' ');
+            return text || null;
+        }
+        else if (Array.isArray(messageContent)) {
+            const textContent = messageContent.find((c) => c.type === 'text');
+            if (textContent?.text) {
+                const text = textContent.text.trim().replace(/\s+/g, ' ');
+                return text || null;
+            }
+        }
+        return null;
+    }
+    extractUserMessageText(messageContent) {
+        const text = this.extractRawUserText(messageContent);
+        if (!text)
+            return null;
+        return text.substring(0, 50) + (text.length > 50 ? '...' : '');
+    }
+}

package/dist/core/session/adapters/codex-session-file-adapter.js

@@ -0,0 +1,333 @@
+/**
+ * Codex SessionFileAdapter
+ *
+ * Reads Codex thread data from ~/.codex/state_*.sqlite (read-only)
+ * and Codex rollout JSONL files for detailed session info.
+ *
+ * `node:sqlite` 是 Node 22.5+ 的实验性内置模块。低版本 Node 上懒加载会失败，
+ * adapter 自动降级到只读 rollout JSONL —— `checkExists/getFileInfo/readFirstMessage/
+ * readLastUserMessage` 仍可工作；`scanCliSessions/listSdkSessions` 因依赖 DB 索引
+ * 会返回空数组。
+ */
+import { createRequire } from 'module';
+import { buildCliSessionPreview, isEvolcoreRoutedMessage, sanitizeSessionTitle, } from '../session-title.js';
+import { logger } from '../../../utils/logger.js';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+const requireFromHere = createRequire(import.meta.url);
+let sqliteModule; // undefined = not tried, null = unavailable
+export const sanitizeCodexThreadTitle = sanitizeSessionTitle;
+const CODEX_INTERACTIVE_SOURCES = new Set(['cli', 'vscode']);
+function loadSqlite() {
+    if (sqliteModule !== undefined)
+        return sqliteModule;
+    try {
+        sqliteModule = requireFromHere('node:sqlite');
+    }
+    catch (e) {
+        logger.warn(`[CodexAdapter] node:sqlite unavailable (Node < 22.5?): ${e?.message || e}. Codex session listing falls back to rollout JSONL.`);
+        sqliteModule = null;
+    }
+    return sqliteModule;
+}
+export class CodexSessionFileAdapter {
+    baseagent = 'codex';
+    db = null;
+    dbInitialized = false;
+    /**
+     * 动态发现最新的 state_*.sqlite 文件
+     * Codex 使用 sqlx 迁移，DB 文件名含版本号（state_5, state_6, ...）
+     */
+    resolveStateDbPath() {
+        const codexHome = path.join(os.homedir(), '.codex');
+        if (!fs.existsSync(codexHome))
+            return null;
+        try {
+            const files = fs.readdirSync(codexHome)
+                .filter(f => /^state_\d+\.sqlite$/.test(f))
+                .sort((a, b) => {
+                const va = parseInt(a.match(/state_(\d+)/)?.[1] || '0');
+                const vb = parseInt(b.match(/state_(\d+)/)?.[1] || '0');
+                return vb - va;
+            });
+            return files.length > 0 ? path.join(codexHome, files[0]) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    getDb() {
+        if (this.dbInitialized)
+            return this.db;
+        this.dbInitialized = true;
+        const sqlite = loadSqlite();
+        if (!sqlite)
+            return null;
+        const dbPath = this.resolveStateDbPath();
+        if (!dbPath)
+            return null;
+        try {
+            this.db = new sqlite.DatabaseSync(dbPath, { readOnly: true });
+            logger.debug(`[CodexAdapter] Opened state DB: ${dbPath}`);
+        }
+        catch (error) {
+            logger.warn(`[CodexAdapter] Failed to open state DB: ${dbPath}`, error);
+            this.db = null;
+        }
+        return this.db;
+    }
+    checkExists(projectPath, agentSessionId) {
+        // 1. 优先查 state_*.sqlite（覆盖 CLI 创建的线程）
+        const db = this.getDb();
+        if (db) {
+            try {
+                const row = db.prepare('SELECT 1 FROM threads WHERE id = ? AND archived = 0').get(agentSessionId);
+                if (row)
+                    return true;
+            }
+            catch (error) {
+                logger.warn(`[CodexAdapter] checkExists DB query failed:`, error);
+            }
+        }
+        // 2. Fallback: 扫 ~/.codex/sessions/ 下的 rollout JSONL
+        //    SDK 创建的 thread 不写 state_*.sqlite，但会持久化到 sessions 目录
+        return !!this.findRolloutFile(agentSessionId);
+    }
+    /**
+     * 在 ~/.codex/sessions/ 下递归查找含 agentSessionId 的 rollout JSONL 文件
+     */
+    findRolloutFile(agentSessionId) {
+        const sessionsDir = path.join(os.homedir(), '.codex', 'sessions');
+        if (!fs.existsSync(sessionsDir))
+            return null;
+        try {
+            const search = (dir) => {
+                for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                    if (entry.isDirectory()) {
+                        const found = search(path.join(dir, entry.name));
+                        if (found)
+                            return found;
+                    }
+                    else if (entry.name.endsWith('.jsonl') && entry.name.includes(agentSessionId)) {
+                        return path.join(dir, entry.name);
+                    }
+                }
+                return null;
+            };
+            return search(sessionsDir);
+        }
+        catch {
+            return null;
+        }
+    }
+    getFileInfo(projectPath, agentSessionId) {
+        // 1. 优先查 state DB
+        const db = this.getDb();
+        if (db) {
+            try {
+                const row = db.prepare('SELECT title, first_user_message, rollout_path FROM threads WHERE id = ?').get(agentSessionId);
+                if (row) {
+                    const rolloutPath = this.resolveRolloutPath(row.rollout_path, agentSessionId);
+                    const preview = this.buildThreadPreview(row.first_user_message, rolloutPath, row.title, false, 80);
+                    return {
+                        turns: this.countTurnsFromRollout(rolloutPath),
+                        title: preview.title || undefined,
+                    };
+                }
+            }
+            catch (error) {
+                logger.warn(`[CodexAdapter] getFileInfo DB query failed:`, error);
+            }
+        }
+        // 2. Fallback: 从 sessions 目录查找 rollout 文件
+        const rolloutPath = this.findRolloutFile(agentSessionId);
+        if (rolloutPath) {
+            return { turns: this.countTurnsFromRollout(rolloutPath) };
+        }
+        return { turns: 0 };
+    }
+    readFirstMessage(projectPath, agentSessionId) {
+        // 1. 优先查 state DB
+        const db = this.getDb();
+        if (db) {
+            try {
+                const row = db.prepare('SELECT first_user_message, rollout_path FROM threads WHERE id = ?').get(agentSessionId);
+                if (row) {
+                    const rolloutPath = this.resolveRolloutPath(row.rollout_path, agentSessionId);
+                    return this.buildThreadPreview(row.first_user_message, rolloutPath).title;
+                }
+            }
+            catch (error) {
+                logger.warn(`[CodexAdapter] readFirstMessage DB query failed:`, error);
+            }
+        }
+        // 2. Fallback: 从 rollout JSONL 读取第一条 user_message
+        const rolloutPath = this.findRolloutFile(agentSessionId);
+        if (!rolloutPath)
+            return null;
+        return this.readUserMessageFromRollout(rolloutPath, 'first');
+    }
+    readLastUserMessage(projectPath, agentSessionId) {
+        // 1. 优先查 state DB 获取 rollout_path
+        const db = this.getDb();
+        let rolloutPath = null;
+        if (db) {
+            try {
+                const row = db.prepare('SELECT rollout_path FROM threads WHERE id = ?').get(agentSessionId);
+                if (row?.rollout_path && fs.existsSync(row.rollout_path)) {
+                    rolloutPath = row.rollout_path;
+                }
+            }
+            catch (error) {
+                logger.warn(`[CodexAdapter] readLastUserMessage DB query failed:`, error);
+            }
+        }
+        // 2. Fallback: 从 sessions 目录查找 rollout 文件
+        if (!rolloutPath) {
+            rolloutPath = this.findRolloutFile(agentSessionId);
+        }
+        if (!rolloutPath)
+            return null;
+        return this.readUserMessageFromRollout(rolloutPath, 'last');
+    }
+    scanCliSessions(projectPath, limit = 10) {
+        const db = this.getDb();
+        if (!db)
+            return [];
+        try {
+            const rows = db.prepare('SELECT id, updated_at, source, title, first_user_message, rollout_path FROM threads WHERE cwd = ? AND archived = 0 ORDER BY updated_at DESC').all(projectPath);
+            const sessions = [];
+            for (const row of rows) {
+                if (!CODEX_INTERACTIVE_SOURCES.has(row.source))
+                    continue;
+                // 排除 EvolCore 自身驱动 codex 产生的会话（首条 user 消息带路由前缀）。
+                // codex 无 entrypoint 字段，EvolCore 会话与真人 vscode 会话同为 source=vscode，
+                // 只能靠路由前缀区分——等同 Claude adapter 用 entrypoint 排除 sdk-ts。
+                if (isEvolcoreRoutedMessage(row.first_user_message))
+                    continue;
+                const rolloutPath = this.resolveRolloutPath(row.rollout_path, row.id);
+                const preview = this.buildThreadPreview(row.first_user_message, rolloutPath, row.title, false, 80);
+                if (!preview.hasReal)
+                    continue;
+                const timestamp = Number(row.updated_at) || 0;
+                sessions.push({
+                    uuid: row.id,
+                    mtime: timestamp < 1_000_000_000_000 ? timestamp * 1000 : timestamp,
+                    title: preview.title || undefined,
+                });
+                if (sessions.length >= limit)
+                    break;
+            }
+            return sessions;
+        }
+        catch (error) {
+            logger.warn(`[CodexAdapter] scanCliSessions failed:`, error);
+            return [];
+        }
+    }
+    async listSdkSessions(projectPath) {
+        const db = this.getDb();
+        if (!db)
+            return [];
+        try {
+            const rows = db.prepare('SELECT id, title FROM threads WHERE cwd = ? AND archived = 0 ORDER BY updated_at DESC').all(projectPath);
+            return rows.map(r => ({
+                sessionId: r.id,
+                title: sanitizeCodexThreadTitle(r.title),
+            }));
+        }
+        catch (error) {
+            logger.warn(`[CodexAdapter] listSdkSessions failed:`, error);
+            return [];
+        }
+    }
+    close() {
+        if (this.db) {
+            try {
+                this.db.close();
+            }
+            catch { /* ignore close errors */ }
+            this.db = null;
+        }
+        this.dbInitialized = false;
+    }
+    /**
+     * 从 rollout JSONL 读取第一条或最后一条 user_message
+     */
+    readUserMessageFromRollout(rolloutPath, which) {
+        const messages = this.readRolloutUserMessages(rolloutPath);
+        if (!messages)
+            return null;
+        const orderedMessages = which === 'first' ? messages : [...messages].reverse();
+        return buildCliSessionPreview(orderedMessages, 'codex').title;
+    }
+    resolveRolloutPath(rolloutPath, agentSessionId) {
+        if (typeof rolloutPath === 'string' && rolloutPath && fs.existsSync(rolloutPath)) {
+            return rolloutPath;
+        }
+        return this.findRolloutFile(agentSessionId);
+    }
+    buildThreadPreview(firstUserMessage, rolloutPath, explicitTitle, includeSyntheticFallback = true, maxLength = 50) {
+        const initial = buildCliSessionPreview([firstUserMessage], 'codex', {
+            explicitTitle,
+            includeSyntheticFallback,
+            maxLength,
+        });
+        if (initial.hasReal || !rolloutPath)
+            return initial;
+        const rolloutMessages = this.readRolloutUserMessages(rolloutPath);
+        if (!rolloutMessages)
+            return initial;
+        return buildCliSessionPreview(rolloutMessages, 'codex', {
+            explicitTitle,
+            includeSyntheticFallback,
+            maxLength,
+        });
+    }
+    readRolloutUserMessages(rolloutPath) {
+        try {
+            const content = fs.readFileSync(rolloutPath, 'utf-8');
+            const lines = content.split('\n').filter(l => l.trim());
+            const messages = [];
+            for (const line of lines) {
+                try {
+                    const event = JSON.parse(line);
+                    if (event.type === 'event_msg' && event.payload?.type === 'user_message' && event.payload.message) {
+                        messages.push(String(event.payload.message));
+                    }
+                }
+                catch { /* skip malformed line */ }
+            }
+            return messages;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 从 rollout JSONL 文件计算轮数（数 turn_context 行）
+     */
+    countTurnsFromRollout(rolloutPath) {
+        if (!rolloutPath || !fs.existsSync(rolloutPath))
+            return 0;
+        try {
+            const content = fs.readFileSync(rolloutPath, 'utf-8');
+            const lines = content.split('\n').filter(l => l.trim());
+            let turns = 0;
+            for (const line of lines) {
+                try {
+                    const event = JSON.parse(line);
+                    if (event.type === 'turn_context') {
+                        turns++;
+                    }
+                }
+                catch { /* skip malformed line */ }
+            }
+            return turns;
+        }
+        catch {
+            return 0;
+        }
+    }
+}