@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

package/dist/core/src/env/session/session-component.js

@@ -0,0 +1,981 @@
+/**
+ * @fileoverview Session Component
+ *
+ * Component for managing session lifecycle
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { BaseComponent } from "../component.js";
+import { MemorySessionStore, SQLiteSessionStore } from "./storage/index.js";
+import { createLogger } from "../log-trace/logger.js";
+import { envKeyToConfigKey } from "../../config/env-key.js";
+import { TracedAs } from "../log-trace/decorator.js";
+import { SummaryAgent } from "../agent/summary-agent.js"; // (new)
+import { SESSION_CONFIG_REGISTRATION, SESSION_DEFAULTS } from "./session-config-registration.js";
+import { parseSearchQuery, matchesQuery } from "./search-query-parser.js";
+import path from "path";
+// Create logger for session component
+const logger = createLogger("session");
+/**
+ * SessionComponent
+ *
+ * Manages session lifecycle including:
+ * - Session CRUD operations
+ * - Message management
+ * - Active session tracking
+ */
+export class SessionComponent extends BaseComponent {
+    name = "session";
+    version = "1.1.0"; // (new)
+    config;
+    store;
+    activeSessionId;
+    hooksConfig = {};
+    /** ConfigComponent 用于配置管理 */
+    configComponent;
+    /** 配置变更 watcher 清理函数 */
+    configWatcher;
+    /** Summary Agent for checkpoint generation [new] */
+    summaryAgent;
+    /** PromptComponent reference for SummaryAgent */
+    promptComponent;
+    /** LLMComponent reference for SummaryAgent */
+    llmComponent;
+    constructor() {
+        super();
+    }
+    /**
+     * Initialize the component
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    async init(config) {
+        // 调用基类 init，注入 env
+        await super.init(config);
+        // 从 options 获取 ConfigComponent
+        const options = config?.options;
+        if (!options?.configComponent) {
+            throw new Error("ConfigComponent is required for SessionComponent initialization");
+        }
+        this.configComponent = options.configComponent;
+        await this.registerConfig(options);
+        // Initialize store based on config
+        const storageConfig = this.config?.storage;
+        if (storageConfig?.type === "sqlite") {
+            this.store = new SQLiteSessionStore(storageConfig.dbPath);
+            logger.info(`[SessionComponent] Using SQLite storage: ${storageConfig.dbPath || "default path"}`);
+        }
+        else {
+            this.store = new MemorySessionStore();
+            logger.info("[SessionComponent] Using memory storage");
+        }
+        this.setStatus("running");
+        logger.info("[SessionComponent] Initialized");
+    }
+    /**
+     * 获取默认 session 数据库路径
+     */
+    getDefaultSessionDbPath() {
+        const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
+        return path.join(home, ".local", "share", "roy-agent", "sessions.db");
+    }
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. Defaults - 默认值（最低）
+     * 2. FileSource - 从配置文件加载
+     * 3. EnvSource - 从环境变量加载
+     * 4. config 对象 - 直接传入的配置（最高）
+     */
+    async registerConfig(options) {
+        const configComponent = options.configComponent;
+        if (!configComponent)
+            return;
+        const { configPath, envPrefix, config } = options;
+        const prefix = envPrefix !== undefined ? envPrefix : "SESSION";
+        // 1. 使用 registerComponent 注册配置结构（keys 和 sources，不含 defaults）
+        configComponent.registerComponent(SESSION_CONFIG_REGISTRATION);
+        // 2. 注册 FileSource（如果提供了 configPath）
+        if (configPath) {
+            configComponent.registerSource({
+                type: "file",
+                relativePath: configPath,
+                optional: true,
+                watch: false
+            });
+        }
+        // 3. 注册 EnvSource
+        configComponent.registerSource({
+            type: "env",
+            envPrefix: prefix,
+            priority: 20,
+            watch: false
+        });
+        // 4. 从 sources 加载配置（FileSource 和 EnvSource）
+        await configComponent.load("session");
+        // 5. 后备方案：直接读取环境变量（确保所有环境变量都被处理）
+        for (const envKey of Object.keys(process.env)) {
+            const configKey = envKeyToConfigKey(envKey, prefix, "session");
+            if (!configKey)
+                continue;
+            const value = process.env[envKey];
+            if (value !== undefined) {
+                await configComponent.set(configKey, value);
+            }
+        }
+        // 6. 设置默认值（只有当配置不存在时）
+        for (const [key, value] of Object.entries(SESSION_DEFAULTS)) {
+            if (configComponent.get(key) === undefined) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 7. 特殊处理 dbPath 动态默认值（优先级高于 SESSION_DEFAULTS）
+        if (configComponent.get("session.storage.dbPath") === undefined) {
+            await configComponent.set("session.storage.dbPath", this.getDefaultSessionDbPath());
+        }
+        // 8. 直接配置对象（最高优先级）
+        if (config) {
+            const flatConfig = this.flattenConfig(config);
+            for (const [key, value] of Object.entries(flatConfig)) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 9. 注册配置热更新监听
+        this.registerConfigWatcher(configComponent);
+        // 10. 解析最终配置
+        this.config = this.buildConfig(configComponent);
+    }
+    /**
+     * 构建最终配置对象
+     */
+    buildConfig(configComponent) {
+        return {
+            defaultDirectory: configComponent.get("session.defaultDirectory"),
+            defaultTitleTemplate: configComponent.get("session.defaultTitleTemplate"),
+            maxMessages: configComponent.get("session.maxMessages"),
+            compactionThreshold: configComponent.get("session.compactionThreshold"),
+            autoCompact: configComponent.get("session.autoCompact"),
+            storage: {
+                type: configComponent.get("session.storage.type"),
+                dbPath: configComponent.get("session.storage.dbPath"),
+            },
+        };
+    }
+    /**
+     * 将配置对象展平为点号路径
+     */
+    flattenConfig(obj, prefix = "session") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const fullKey = `${prefix}.${key}`;
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                Object.assign(result, this.flattenConfig(value, fullKey));
+            }
+            else {
+                result[fullKey] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * 注册配置热更新监听
+     */
+    registerConfigWatcher(configComponent) {
+        if (typeof configComponent.watch !== "function") {
+            return;
+        }
+        this.configWatcher = configComponent.watch("session.*", (event) => {
+            this.onConfigChange(event);
+        });
+    }
+    /**
+     * 处理配置变更
+     */
+    onConfigChange(event) {
+        logger.info(`Session config changed: ${event.key}`, {
+            oldValue: event.oldValue,
+            newValue: event.newValue
+        });
+    }
+    /**
+     * Start the component
+     */
+    async onStart() {
+        logger.info("[SessionComponent] Started");
+    }
+    /**
+     * Stop the component
+     */
+    async onStop() {
+        // 清理配置 watcher
+        this.configWatcher?.();
+        this.configWatcher = undefined;
+        // 清理资源
+        await this.store?.close();
+        this.store = undefined;
+        this.setStatus("stopped");
+        logger.info("[SessionComponent] Stopped");
+    }
+    // ============ Session CRUD ============
+    /**
+     * Create a new session
+     */
+    async create(options = {}) {
+        // Execute before hooks
+        await this.executeBeforeHooks("create", { options });
+        // Generate title if not provided
+        const title = options.title ?? this.generateTitle();
+        // Create session
+        const session = await this.store.create({
+            ...options,
+            title,
+        });
+        logger.info(`[SessionComponent] Created session: ${session.id}`, { title });
+        // Execute after hooks
+        await this.executeAfterHooks("create", { session, options });
+        return session;
+    }
+    /**
+     * Get a session by ID
+     */
+    async get(id) {
+        await this.executeBeforeHooks("session.get", { id });
+        const session = await this.store?.get(id);
+        await this.executeAfterHooks("session.get", { session });
+        return session;
+    }
+    /**
+     * Get a session with full context (for Memory Agent)
+     */
+    async getSession(id) {
+        const session = await this.get(id);
+        if (!session) {
+            return null;
+        }
+        const messages = await this.getMessages(id);
+        return {
+            sessionId: session.id,
+            title: session.title || "Untitled",
+            messages: messages.map(m => ({
+                role: m.role,
+                content: m.content,
+                timestamp: m.timestamp,
+            })),
+        };
+    }
+    /**
+     * Search sessions by query (for Memory Agent)
+     *
+     * Simple implementation: list all sessions and return them for the agent to filter
+     */
+    async searchSessions(query, options) {
+        const limit = options?.limit ?? 20;
+        // 如果指定了 session_id，只返回该会话
+        if (options?.session_id) {
+            const session = await this.get(options.session_id);
+            if (session) {
+                const messages = await this.getMessages(options.session_id);
+                const lastMessage = messages[messages.length - 1];
+                return [{
+                        sessionId: session.id,
+                        title: session.title || "Untitled",
+                        preview: lastMessage?.content?.substring(0, 200) || "",
+                        timestamp: session.updatedAt || session.createdAt,
+                    }];
+            }
+            return [];
+        }
+        // 否则列出所有会话
+        const sessions = await this.list({ limit });
+        // 对每个会话获取预览
+        const results = [];
+        for (const session of sessions) {
+            if (results.length >= limit)
+                break;
+            const messages = await this.getMessages(session.id);
+            const lastMessage = messages[messages.length - 1];
+            const preview = lastMessage?.content?.substring(0, 200) || "";
+            // 简单过滤：如果 query 不为空，检查标题或预览是否包含 query
+            if (query) {
+                const lowerQuery = query.toLowerCase();
+                const titleMatch = (session.title || "").toLowerCase().includes(lowerQuery);
+                const previewMatch = preview.toLowerCase().includes(lowerQuery);
+                if (!titleMatch && !previewMatch) {
+                    continue;
+                }
+            }
+            results.push({
+                sessionId: session.id,
+                title: session.title || "Untitled",
+                preview,
+                timestamp: session.updatedAt || session.createdAt,
+            });
+        }
+        return results;
+    }
+    /**
+     * List all sessions
+     */
+    async list(options) {
+        await this.executeBeforeHooks("session.list", { options });
+        const sessions = (await this.store?.list(options)) ?? [];
+        await this.executeAfterHooks("session.list", { sessions });
+        return sessions;
+    }
+    /**
+     * Get total session count
+     */
+    async getCount() {
+        return (await this.store?.getCount()) ?? 0;
+    }
+    /**
+     * Update a session
+     */
+    async update(id, updates) {
+        await this.executeBeforeHooks("session.update", { id, updates });
+        const success = await this.store?.update(id, updates);
+        if (success) {
+            logger.info(`[SessionComponent] Updated session: ${id}`, { updates });
+            await this.executeAfterHooks("session.update", { id, updates });
+        }
+        return success ?? false;
+    }
+    /**
+     * Delete a session
+     */
+    async delete(id) {
+        await this.executeBeforeHooks("session.delete", { id });
+        const success = await this.store?.delete(id);
+        if (success) {
+            if (this.activeSessionId === id) {
+                this.activeSessionId = undefined;
+            }
+            logger.info(`[SessionComponent] Deleted session: ${id}`);
+            await this.executeAfterHooks("session.delete", { id });
+        }
+        return success ?? false;
+    }
+    // ============ Active Session ============
+    /**
+     * Get the current active session
+     */
+    getActiveSession() {
+        if (!this.activeSessionId)
+            return undefined;
+        // Synchronous getter, so we need to handle this carefully
+        // In a real implementation, we'd cache the active session
+        return undefined; // Will be populated by callers who need it
+    }
+    /**
+     * Get the active session ID
+     */
+    getActiveSessionId() {
+        return this.activeSessionId;
+    }
+    /**
+     * Set the active session
+     */
+    async setActiveSession(id) {
+        const session = await this.store?.get(id);
+        if (!session)
+            return false;
+        this.activeSessionId = id;
+        logger.info(`[SessionComponent] Active session set: ${id}`);
+        return true;
+    }
+    // ============ Messages ============
+    /**
+     * Add a message to a session
+     */
+    async addMessage(sessionId, message) {
+        // DEBUG: 记录添加消息的调用栈
+        const contentPreview = typeof message.content === "string"
+            ? message.content.substring(0, 100)
+            : JSON.stringify(message.content).substring(0, 100);
+        logger.info(`[SessionComponent.addMessage] sessionId=${sessionId}, role=${message.role}, content="${contentPreview}"`);
+        try {
+            const messageId = await this.store?.addMessage(sessionId, message);
+            logger.info(`[SessionComponent.addMessage] Success: messageId=${messageId}`);
+            return messageId;
+        }
+        catch (error) {
+            logger.error(`[SessionComponent] Failed to add message: ${error}`);
+            return undefined;
+        }
+    }
+    /**
+     * Get messages from a session
+     */
+    async getMessages(sessionId, options) {
+        const messages = await this.store?.getMessages(sessionId, options?.offset, options?.limit);
+        return messages ?? [];
+    }
+    /**
+     * Get message count for a session
+     */
+    async getMessageCount(sessionId, includeArchived) {
+        return this.store?.getMessageCount(sessionId, includeArchived) ?? 0;
+    }
+    /**
+     * Get indexes of all messages with the specified role
+     * @param sessionId - Session ID
+     * @param role - Role to filter by (e.g., "user", "assistant")
+     * @returns Array of message indexes (0-indexed, in chronological order)
+     */
+    async getMessageIndexes(sessionId, role) {
+        return this.store?.getMessageIndexes(sessionId, role) ?? [];
+    }
+    // ============ Hooks ============
+    async executeBeforeHooks(operation, context) {
+        // operation is like "create", so key should be "before.session.create"
+        const hookKey = `before.session.${operation}`;
+        const hooks = this.hooksConfig[hookKey] ?? [];
+        const hookContext = context;
+        // Execute registered hooks first
+        for (const hook of hooks) {
+            if (hook.before) {
+                await hook.before(hookContext);
+            }
+        }
+        // Also execute from hooks config if passed in options
+        const options = context.options;
+        if (options?.hooks) {
+            // options.hooks has keys like "before.session.create"
+            const hookArray = options.hooks[hookKey] ?? [];
+            for (const hook of hookArray) {
+                if (hook.before) {
+                    await hook.before(hookContext);
+                }
+            }
+        }
+    }
+    async executeAfterHooks(operation, context) {
+        const hookKey = `after.session.${operation}`;
+        const hooks = this.hooksConfig[hookKey] ?? [];
+        const hookContext = context;
+        // Execute registered hooks first
+        for (const hook of hooks) {
+            if (hook.after) {
+                await hook.after(hookContext);
+            }
+        }
+        // Also execute from hooks config if passed in options
+        const options = context.options;
+        if (options?.hooks) {
+            // options.hooks has keys like "after.session.create"
+            const hookArray = options.hooks[hookKey] ?? [];
+            for (const hook of hookArray) {
+                if (hook.after) {
+                    await hook.after(hookContext);
+                }
+            }
+        }
+    }
+    // ============ Helper Methods ============
+    generateTitle() {
+        const template = this.config?.defaultTitleTemplate ?? "Session - {date}";
+        const date = new Date().toISOString().replace("T", " ").substring(0, 19);
+        return template.replace("{date}", date);
+    }
+    // ============ Checkpoint Management [new] ============
+    /**
+     * Set components for SummaryAgent
+     *
+     * Call this after initialization if you need compact functionality
+     */
+    setSummaryComponents(promptComponent, llmComponent) {
+        this.promptComponent = promptComponent;
+        this.llmComponent = llmComponent;
+        this.summaryAgent = new SummaryAgent(promptComponent, llmComponent);
+    }
+    /**
+     * 初始化 SummaryAgent（如未初始化）
+     */
+    ensureSummaryAgent() {
+        if (!this.summaryAgent) {
+            if (!this.promptComponent || !this.llmComponent) {
+                throw new Error("SummaryAgent components not initialized. Call setSummaryComponents() first.");
+            }
+            this.summaryAgent = new SummaryAgent(this.promptComponent, this.llmComponent);
+        }
+    }
+    /**
+     * 生成场景化压缩提示 (Compact Hint)
+     *
+     * 两阶段自动压缩的第一阶段：
+     * 根据会话历史生成场景化的压缩提示
+     *
+     * @param sessionId 会话 ID
+     * @returns 生成的场景化提示
+     */
+    async generateCompactHint(sessionId) {
+        const session = await this.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        // 获取最新 checkpoint 之后的所有消息
+        const latestCheckpoint = this.getLatestCheckpoint(session);
+        const startIndex = latestCheckpoint?.messageIndex ?? 0;
+        const MAX_SAFE_MESSAGES = Number.MAX_SAFE_INTEGER;
+        const messages = await this.store.getMessages(sessionId, startIndex, MAX_SAFE_MESSAGES, { includeArchived: false });
+        if (messages.length < 3) {
+            logger.warn("[SessionComponent] Not enough messages for hint generation");
+            return "";
+        }
+        // 确保 SummaryAgent 已初始化
+        this.ensureSummaryAgent();
+        // 生成提示
+        const result = await this.summaryAgent.generateCompactHint({
+            messages: messages.map((m) => ({ role: m.role, content: m.content })),
+            sessionContext: {
+            // 可以扩展更多上下文信息
+            },
+        });
+        logger.info("[SessionComponent] Compact hint generated", {
+            sessionId,
+            hintLength: result.hint.length,
+        });
+        return result.hint;
+    }
+    /**
+     * Compact a session
+     *
+     * 1. Get messages from latest checkpoint to current
+     * 2. Call Summary Agent to generate checkpoint
+     * 3. Save checkpoint and archive messages
+     *
+     * 支持 scenarioHint 参数，用于指导不同场景下的压缩重点提取
+     */
+    async compact(sessionId, options) {
+        const session = await this.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        // 1. Determine start position
+        const latestCheckpoint = this.getLatestCheckpoint(session);
+        const startIndex = latestCheckpoint?.messageIndex ?? 0;
+        // 2. Get messages to compact
+        // Use MAX_SAFE_INTEGER to ensure we get ALL messages (default limit=50 can cause issues)
+        const MAX_SAFE_MESSAGES = Number.MAX_SAFE_INTEGER;
+        const messages = await this.store.getMessages(sessionId, startIndex, MAX_SAFE_MESSAGES, { includeArchived: false });
+        if (messages.length < 3) {
+            throw new Error("Not enough messages to compact (minimum 3 required)");
+        }
+        // 3. Extract recent messages for checkpoint context
+        // We need the last 2 turns of user query + assistant text response (no tool calls/results)
+        const recentMessages = this.extractRecentMessages(messages, 2);
+        // 4. Ensure Summary Agent is initialized
+        this.ensureSummaryAgent();
+        // 5. Execute before hooks
+        await this.executeBeforeHooks("compact", { session, options });
+        // 6. Call Summary Agent (with scenarioHint if provided)
+        const summaryResult = await this.summaryAgent.run({
+            messages: messages.map((m) => ({ role: m.role, content: m.content })),
+            userContext: options?.summary,
+            outputFormat: "json",
+            scenarioHint: options?.scenarioHint, // Pass scenario hint to SummaryAgent
+        });
+        // 7. Generate checkpoint ID
+        const checkpointId = `cp_${Date.now().toString(36)}_${Math.random().toString(36).substring(2, 8)}`;
+        // 8. Create checkpoint object (include recentMessages for fresh history context)
+        const checkpoint = {
+            id: checkpointId,
+            messageIndex: startIndex,
+            title: summaryResult.title,
+            summary: [
+                `Process: ${summaryResult.processKeyPoints.join("; ")}`,
+                `State: ${summaryResult.currentState}`,
+            ].join("\n"),
+            processKeyPoints: summaryResult.processKeyPoints,
+            currentState: summaryResult.currentState,
+            nextSteps: summaryResult.nextSteps,
+            userIntents: summaryResult.userIntents,
+            messageCountBefore: messages.length,
+            createdAt: Date.now(),
+            type: "compact",
+            recentMessages, // Preserve recent messages for context
+        };
+        // 9. Save checkpoint
+        await this.store.saveCheckpoint(sessionId, checkpoint);
+        // 10. Archive messages
+        await this.store.archiveMessages(sessionId, checkpointId, messages.length);
+        // 11. Create and add checkpoint message (user role)
+        const checkpointMessage = this.createCheckpointMessage(checkpoint);
+        await this.store.addMessage(sessionId, checkpointMessage);
+        // 12. Update session
+        const updatedSession = await this.get(sessionId);
+        const remainingMessageCount = updatedSession?.messageCount ?? 0;
+        const checkpointCount = updatedSession?.metadata?.checkpoints?.checkpoints?.length ?? 0;
+        logger.info(`[SessionComponent] Compacted session: ${sessionId}`, {
+            checkpointId,
+            archivedCount: messages.length,
+            remainingCount: remainingMessageCount,
+            hasScenarioHint: !!options?.scenarioHint,
+            recentMessagesCount: recentMessages.length,
+        });
+        // 13. Execute after hooks
+        await this.executeAfterHooks("compact", { session, checkpoint, options });
+        return {
+            checkpoint,
+            deletedMessageCount: messages.length,
+            remainingMessageCount,
+            checkpointCount,
+        };
+    }
+    /**
+     * Extract recent messages from the conversation for checkpoint context
+     *
+     * Extracts the last N turns of user query + assistant text response,
+     * excluding tool calls and tool results.
+     *
+     * @param messages - All messages in the conversation
+     * @param turnCount - Number of turns to extract (default: 2)
+     * @returns Array of recent messages formatted as { role, content }
+     */
+    extractRecentMessages(messages, turnCount = 2) {
+        const recentMessages = [];
+        let turnsExtracted = 0;
+        // Iterate from the most recent messages backwards
+        // We need to find user + assistant pairs
+        let i = messages.length - 1;
+        while (i >= 0 && turnsExtracted < turnCount) {
+            const msg = messages[i];
+            // Skip checkpoint messages
+            if (msg.metadata?.isCheckpoint) {
+                i--;
+                continue;
+            }
+            // Check if this is a text response (no tool calls/results)
+            const hasToolParts = msg.parts?.some(p => p.type === 'tool-call' || p.type === 'tool-result');
+            if (msg.role === 'assistant' && !hasToolParts && msg.content.trim()) {
+                // Found an assistant text response
+                recentMessages.unshift({
+                    role: 'assistant',
+                    content: msg.content,
+                });
+                // Look for the preceding user message
+                let j = i - 1;
+                while (j >= 0) {
+                    const prevMsg = messages[j];
+                    if (prevMsg.metadata?.isCheckpoint) {
+                        j--;
+                        continue;
+                    }
+                    if (prevMsg.role === 'user') {
+                        recentMessages.unshift({
+                            role: 'user',
+                            content: prevMsg.content,
+                        });
+                        turnsExtracted++;
+                        break;
+                    }
+                    j--;
+                }
+                i = j;
+            }
+            else {
+                i--;
+            }
+        }
+        logger.debug("[SessionComponent] Extracted recent messages", {
+            turnCount,
+            messagesExtracted: recentMessages.length,
+        });
+        return recentMessages;
+    }
+    /**
+     * Preview compact operation
+     */
+    async previewCompact(sessionId) {
+        const session = await this.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        const latestCheckpoint = this.getLatestCheckpoint(session);
+        const startIndex = latestCheckpoint?.messageIndex ?? 0;
+        // Use MAX_SAFE_INTEGER to ensure we get ALL messages (default limit=50 can cause issues)
+        const MAX_SAFE_MESSAGES = Number.MAX_SAFE_INTEGER;
+        const messages = await this.store.getMessages(sessionId, startIndex, MAX_SAFE_MESSAGES, { includeArchived: false });
+        // Rough estimate: ~4 tokens per character
+        const estimatedTokens = messages.reduce((sum, m) => sum + m.content.length * 0.25, 0);
+        return {
+            messageCountToCompact: messages.length,
+            estimatedCheckpointTokens: Math.round(estimatedTokens * 0.1), // Checkpoint is ~10% of original
+            wouldTrigger: messages.length >= (this.config?.maxMessages ?? 50),
+        };
+    }
+    /**
+     * Get all checkpoints for a session
+     */
+    async getCheckpoints(sessionId) {
+        return await this.store.getCheckpoints(sessionId);
+    }
+    /**
+     * Get a specific checkpoint
+     */
+    async getCheckpoint(sessionId, checkpointId) {
+        return await this.store.getCheckpoint(sessionId, checkpointId);
+    }
+    /**
+     * Delete a checkpoint and restore archived messages
+     */
+    async deleteCheckpoint(sessionId, checkpointId) {
+        await this.executeBeforeHooks("deleteCheckpoint", { sessionId, checkpointId });
+        const success = await this.store.deleteCheckpoint(sessionId, checkpointId);
+        if (success) {
+            logger.info(`[SessionComponent] Deleted checkpoint: ${checkpointId}`);
+            await this.executeAfterHooks("deleteCheckpoint", { sessionId, checkpointId });
+        }
+        return success;
+    }
+    /**
+     * Get session context
+     *
+     * Returns messages starting from the latest checkpoint by default
+     */
+    async getContext(sessionId, options) {
+        const session = await this.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found`);
+        }
+        let contextMessages = [];
+        let startCheckpoint;
+        if (options?.fullHistory) {
+            // Get ALL messages including archived ones (for full history view)
+            const MAX_SAFE_MESSAGES = Number.MAX_SAFE_INTEGER;
+            contextMessages = await this.store.getMessages(sessionId, 0, MAX_SAFE_MESSAGES, {
+                includeArchived: true,
+            });
+        }
+        else {
+            // Optimization: Start from latest checkpoint instead of reading all messages
+            // This avoids reading archived messages that have been compacted
+            const latestCheckpointId = session.metadata?.checkpoints?.latestCheckpointId;
+            if (latestCheckpointId) {
+                // Get checkpoint details to find messageIndex
+                startCheckpoint = await this.store.getCheckpoint(sessionId, latestCheckpointId);
+                if (startCheckpoint) {
+                    // Read messages from checkpoint position onwards
+                    const MAX_SAFE_MESSAGES = Number.MAX_SAFE_INTEGER;
+                    contextMessages = await this.store.getMessages(sessionId, startCheckpoint.messageIndex, MAX_SAFE_MESSAGES, { includeArchived: false });
+                }
+            }
+            // If no checkpoint found, read from beginning (first session)
+            if (contextMessages.length === 0) {
+                const MAX_SAFE_MESSAGES = Number.MAX_SAFE_INTEGER;
+                contextMessages = await this.store.getMessages(sessionId, 0, MAX_SAFE_MESSAGES, {
+                    includeArchived: false,
+                });
+            }
+        }
+        // Ensure starting from user message boundary (avoids tool_call/tool_result mismatch)
+        if (options?.minUserMessages && options.minUserMessages > 0) {
+            const userIndexes = [];
+            for (let i = 0; i < contextMessages.length; i++) {
+                if (contextMessages[i].role === "user") {
+                    userIndexes.push(i);
+                }
+            }
+            if (userIndexes.length > options.minUserMessages) {
+                const targetIndex = userIndexes[userIndexes.length - options.minUserMessages];
+                contextMessages = contextMessages.slice(targetIndex);
+            }
+        }
+        // Apply message limit (after minUserMessages processing)
+        if (options?.messageLimit) {
+            contextMessages = contextMessages.slice(-options.messageLimit);
+        }
+        // Extract checkpoint info
+        const checkpoints = contextMessages
+            .filter((m) => m.metadata?.isCheckpoint)
+            .map((m) => m.metadata.checkpointMeta);
+        // Estimate tokens
+        const estimatedTokens = contextMessages.reduce((sum, m) => sum + m.content.length * 0.25, 0);
+        return {
+            session,
+            checkpoints,
+            startCheckpoint: startCheckpoint ?? checkpoints[checkpoints.length - 1],
+            messages: contextMessages,
+            totalMessageCount: contextMessages.length,
+            activeMessageCount: contextMessages.filter((m) => !m.isArchived).length,
+            archivedMessageCount: contextMessages.filter((m) => m.isArchived).length,
+            estimatedTokens: Math.round(estimatedTokens),
+        };
+    }
+    /**
+     * Check if session needs compaction
+     */
+    async shouldCompact(sessionId) {
+        const session = await this.get(sessionId);
+        if (!session)
+            return false;
+        const preview = await this.previewCompact(sessionId);
+        return preview.wouldTrigger;
+    }
+    // ============ Search [new] ============
+    /**
+     * Search messages across sessions
+     *
+     * Searches all messages matching the query, aggregated by session.
+     * Supports SQLite FTS5 for fast full-text search.
+     */
+    async searchMessages(options) {
+        const { query, sessionId, limit = 10, maxResults = 100, beforeTime, afterTime, includeArchived = false, includeContext = false, contextLines = 2, } = options;
+        // Delegate to store for actual search
+        if (!this.store) {
+            return [];
+        }
+        // Get all sessions or specific session
+        let sessions;
+        if (sessionId) {
+            const session = await this.get(sessionId);
+            sessions = session ? [session] : [];
+        }
+        else {
+            sessions = await this.list({ limit: 1000 }); // Get all sessions
+        }
+        const results = [];
+        let totalMatches = 0;
+        for (const session of sessions) {
+            // Check time constraints
+            if (beforeTime && session.updatedAt > beforeTime)
+                continue;
+            if (afterTime && session.updatedAt < afterTime)
+                continue;
+            // Search messages in this session
+            const messages = await this.store.getMessages(session.id, 0, 1000, { includeArchived });
+            // Simple text search (case-insensitive, supports AND/OR/NOT)
+            const queryTerms = parseSearchQuery(query);
+            const matches = [];
+            for (const msg of messages) {
+                // Time constraints
+                if (beforeTime && msg.timestamp > beforeTime)
+                    continue;
+                if (afterTime && msg.timestamp < afterTime)
+                    continue;
+                // Check if message matches query
+                if (matchesQuery(msg.content, queryTerms)) {
+                    const match = {
+                        messageId: msg.id,
+                        sessionId: session.id,
+                        role: msg.role,
+                        content: msg.content,
+                        timestamp: msg.timestamp,
+                    };
+                    // Add context if requested
+                    if (includeContext) {
+                        const msgIndex = messages.indexOf(msg);
+                        const beforeMsgs = messages.slice(Math.max(0, msgIndex - contextLines), msgIndex);
+                        const afterMsgs = messages.slice(msgIndex + 1, msgIndex + 1 + contextLines);
+                        match.contextBefore = beforeMsgs.map(m => m.content).join("\n");
+                        match.contextAfter = afterMsgs.map(m => m.content).join("\n");
+                    }
+                    matches.push(match);
+                    if (matches.length >= limit)
+                        break;
+                }
+            }
+            if (matches.length > 0) {
+                results.push({
+                    sessionId: session.id,
+                    sessionTitle: session.title,
+                    sessionDirectory: session.directory,
+                    updatedAt: session.updatedAt,
+                    messageCount: session.messageCount,
+                    matches,
+                });
+                totalMatches += matches.length;
+                if (totalMatches >= maxResults)
+                    break;
+            }
+        }
+        return results;
+    }
+    // ============ Private Helper Methods [new] ============
+    /**
+     * Get latest checkpoint from session
+     */
+    getLatestCheckpoint(session) {
+        const latestId = session.metadata?.checkpoints?.latestCheckpointId;
+        if (!latestId)
+            return undefined;
+        return session.metadata?.checkpointDetails?.[latestId];
+    }
+    /**
+     * Create checkpoint message (user role)
+     *
+     * Generates a markdown-formatted checkpoint summary as a user message,
+     * allowing it to appear in the message list and provide context for
+     * subsequent LLM calls.
+     */
+    createCheckpointMessage(checkpoint) {
+        const lines = [
+            `# Checkpoint: ${checkpoint.title}`,
+            "",
+            "## Process Key Points",
+            ...checkpoint.processKeyPoints.map((p, i) => `${i + 1}. ${p}`),
+            "",
+            "## Current State",
+            checkpoint.currentState,
+            "",
+        ];
+        if (checkpoint.nextSteps?.length) {
+            lines.push("## Next Steps");
+            checkpoint.nextSteps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+            lines.push("");
+        }
+        lines.push("## Messages Compacted");
+        lines.push(`${checkpoint.messageCountBefore} messages compacted at ${new Date(checkpoint.createdAt).toISOString()}`);
+        const content = lines.join("\n");
+        return {
+            role: "user",
+            content,
+            parts: [{
+                    type: "checkpoint",
+                    checkpointId: checkpoint.id,
+                    content,
+                    title: checkpoint.title,
+                    processKeyPoints: checkpoint.processKeyPoints,
+                    currentState: checkpoint.currentState,
+                    nextSteps: checkpoint.nextSteps,
+                    messageCountBefore: checkpoint.messageCountBefore,
+                    createdAt: checkpoint.createdAt,
+                }],
+            metadata: {
+                isCheckpoint: true,
+                checkpointId: checkpoint.id,
+                checkpointMeta: checkpoint,
+            },
+        };
+    }
+}
+__decorate([
+    TracedAs("session.generateCompactHint"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], SessionComponent.prototype, "generateCompactHint", null);
+__decorate([
+    TracedAs("session.compact", { recordParams: true, recordResult: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], SessionComponent.prototype, "compact", null);
+__decorate([
+    TracedAs("session.extractRecentMessages"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array, Number]),
+    __metadata("design:returntype", Array)
+], SessionComponent.prototype, "extractRecentMessages", null);
+//# sourceMappingURL=session-component.js.map