@ai-setting/roy-agent-core 1.0.0

package/src/env/session/session-component.ts

@@ -0,0 +1,1249 @@
+/**
+ * @fileoverview Session Component
+ * 
+ * Component for managing session lifecycle
+ */
+
+import { BaseComponent, type ComponentConfig } from "../component";
+import {
+  type SessionConfig, 
+  type Session, 
+  type CreateSessionOptions, 
+  type UpdateSessionOptions, 
+  type ListSessionsOptions, 
+  type SessionMessage, 
+  type AddMessageOptions,
+  type SessionCheckpoint,           // (new)
+  type CompactOptions,             // (new)
+  type CompactResult,             // (new)
+  type CompactPreview,            // (new)
+  type GetContextOptions,         // (new)
+  type GetContextResult,          // (new)
+  type SearchMessagesOptions,     // (new)
+  type SearchResult,              // (new)
+  type MessageMatch,              // (new)
+} from "./types";
+import type { SessionHookContext } from "../types";
+import type { SessionStore } from "./session-store";
+import { MemorySessionStore, SQLiteSessionStore } from "./storage";
+import { createLogger } from "../log-trace/logger";
+import type { ConfigComponent } from "../../config/config-component";
+import { envKeyToConfigKey } from "../../config/env-key";
+import { TracedAs } from "../log-trace/decorator";
+import { SummaryAgent } from "../agent/summary-agent";  // (new)
+import { SESSION_CONFIG_REGISTRATION, SESSION_DEFAULTS } from "./session-config-registration";
+import { parseSearchQuery, matchesQuery } from "./search-query-parser";
+import path from "path";
+
+// Re-export for convenience
+export type { 
+  SessionConfig, 
+  Session, 
+  SessionMessage, 
+  CreateSessionOptions, 
+  UpdateSessionOptions, 
+  ListSessionsOptions, 
+  AddMessageOptions,
+  SessionCheckpoint,              // (new)
+  CompactOptions,                // (new)
+  CompactResult,                 // (new)
+  CompactPreview,                // (new)
+  GetContextOptions,            // (new)
+  GetContextResult,             // (new)
+  SearchMessagesOptions,         // (new) Search
+  SearchResult,                  // (new) Search
+  MessageMatch,                  // (new) Search
+} from "./types";
+
+// Create logger for session component
+const logger = createLogger("session");
+
+// ============================================================================
+// SessionComponentOptions (统一配置机制)
+// ============================================================================
+
+/**
+ * SessionComponent 配置选项（通过 options 传递）
+ * 
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface SessionComponentOptions {
+  /** ConfigComponent 实例（必填） */
+  configComponent: ConfigComponent;
+  
+  /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+  configPath?: string;
+  
+  /** 环境变量前缀（可选，默认 "SESSION"） */
+  envPrefix?: string;
+  
+  /** 直接传入的配置对象（可选，优先级最高） */
+  config?: Partial<SessionConfig>;
+}
+
+/**
+ * Session component hooks configuration
+ */
+interface SessionComponentHooks {
+  "before.session.create"?: import("./types").SessionHook[];
+  "after.session.create"?: import("./types").SessionHook[];
+  "before.session.get"?: import("./types").SessionHook[];
+  "after.session.get"?: import("./types").SessionHook[];
+  "before.session.list"?: import("./types").SessionHook[];
+  "after.session.list"?: import("./types").SessionHook[];
+  "before.session.update"?: import("./types").SessionHook[];
+  "after.session.update"?: import("./types").SessionHook[];
+  "before.session.delete"?: import("./types").SessionHook[];
+  "after.session.delete"?: import("./types").SessionHook[];
+}
+
+/**
+ * SessionComponent
+ * 
+ * Manages session lifecycle including:
+ * - Session CRUD operations
+ * - Message management
+ * - Active session tracking
+ */
+export class SessionComponent extends BaseComponent {
+  readonly name = "session";
+  readonly version = "1.1.0";  // (new)
+
+  private config?: SessionConfig;
+  private store?: SessionStore;
+  private activeSessionId?: string;
+  private hooksConfig: SessionComponentHooks = {};
+  
+  /** ConfigComponent 用于配置管理 */
+  private configComponent?: ConfigComponent;
+  
+  /** 配置变更 watcher 清理函数 */
+  private configWatcher?: () => void;
+  
+  /** Summary Agent for checkpoint generation [new] */
+  private summaryAgent?: SummaryAgent;
+  
+  /** PromptComponent reference for SummaryAgent */
+  private promptComponent?: any;
+  
+  /** LLMComponent reference for SummaryAgent */
+  private llmComponent?: any;
+
+  constructor() {
+    super();
+  }
+
+  /**
+   * Initialize the component
+   * 
+   * 配置加载优先级（从高到低）：
+   * 1. Object - 直接传入的 config 对象
+   * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+   * 3. File - 配置文件（通过 configPath 指定）
+   */
+  async init(config?: ComponentConfig): Promise<void> {
+    // 调用基类 init，注入 env
+    await super.init(config);
+
+    // 从 options 获取 ConfigComponent
+    const options = config?.options as unknown as SessionComponentOptions | undefined;
+    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 数据库路径
+   */
+  private getDefaultSessionDbPath(): string {
+    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 对象 - 直接传入的配置（最高）
+   */
+  private async registerConfig(options: SessionComponentOptions): Promise<void> {
+    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);
+  }
+
+  /**
+   * 构建最终配置对象
+   */
+  private buildConfig(configComponent: ConfigComponent): SessionConfig {
+    return {
+      defaultDirectory: configComponent.get("session.defaultDirectory") as string,
+      defaultTitleTemplate: configComponent.get("session.defaultTitleTemplate") as string,
+      maxMessages: configComponent.get("session.maxMessages") as number,
+      compactionThreshold: configComponent.get("session.compactionThreshold") as number,
+      autoCompact: configComponent.get("session.autoCompact") as boolean,
+      storage: {
+        type: configComponent.get("session.storage.type") as "memory" | "sqlite",
+        dbPath: configComponent.get("session.storage.dbPath") as string | undefined,
+      },
+    };
+  }
+
+  /**
+   * 将配置对象展平为点号路径
+   */
+  private flattenConfig(
+    obj: Record<string, unknown>,
+    prefix = "session"
+  ): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    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 as Record<string, unknown>, fullKey)
+        );
+      } else {
+        result[fullKey] = value;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 注册配置热更新监听
+   */
+  private registerConfigWatcher(configComponent: ConfigComponent): void {
+    if (typeof configComponent.watch !== "function") {
+      return;
+    }
+    
+    this.configWatcher = configComponent.watch("session.*", (event) => {
+      this.onConfigChange(event);
+    });
+  }
+
+  /**
+   * 处理配置变更
+   */
+  protected onConfigChange(event: { key: string; oldValue?: unknown; newValue?: unknown }): void {
+    logger.info(`Session config changed: ${event.key}`, {
+      oldValue: event.oldValue,
+      newValue: event.newValue
+    });
+  }
+
+  /**
+   * Start the component
+   */
+  async onStart(): Promise<void> {
+    logger.info("[SessionComponent] Started");
+  }
+
+  /**
+   * Stop the component
+   */
+  async onStop(): Promise<void> {
+    // 清理配置 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: CreateSessionOptions = {}): Promise<Session> {
+    // 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: string): Promise<Session | undefined> {
+    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: string): Promise<{ sessionId: string; title: string; messages: any[] } | null> {
+    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: string,
+    options?: { session_id?: string; limit?: number }
+  ): Promise<Array<{ sessionId: string; title: string; preview: string; timestamp: number }>> {
+    const limit = options?.limit ?? 20;
+    type SearchResult = { sessionId: string; title: string; preview: string; timestamp: number };
+    
+    // 如果指定了 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: SearchResult[] = [];
+    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?: ListSessionsOptions): Promise<Session[]> {
+    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(): Promise<number> {
+    return (await this.store?.getCount()) ?? 0;
+  }
+
+  /**
+   * Update a session
+   */
+  async update(id: string, updates: UpdateSessionOptions): Promise<boolean> {
+    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: string): Promise<boolean> {
+    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(): Session | undefined {
+    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(): string | undefined {
+    return this.activeSessionId;
+  }
+
+  /**
+   * Set the active session
+   */
+  async setActiveSession(id: string): Promise<boolean> {
+    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: string, message: AddMessageOptions): Promise<string | undefined> {
+    // 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: string, options?: { offset?: number; limit?: number }): Promise<SessionMessage[]> {
+    const messages = await this.store?.getMessages(
+      sessionId,
+      options?.offset,
+      options?.limit
+    );
+    return messages ?? [];
+  }
+
+  /**
+   * Get message count for a session
+   */
+  async getMessageCount(sessionId: string, includeArchived?: boolean): Promise<number> {
+    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: string, role: string): Promise<number[]> {
+    return this.store?.getMessageIndexes(sessionId, role) ?? [];
+  }
+
+  // ============ Hooks ============
+
+  private async executeBeforeHooks(
+    operation: string,
+    context: Record<string, unknown>
+  ): Promise<void> {
+    // operation is like "create", so key should be "before.session.create"
+    const hookKey = `before.session.${operation}` as keyof SessionComponentHooks;
+    const hooks = this.hooksConfig[hookKey] ?? [];
+    const hookContext = context as unknown as SessionHookContext;
+    
+    // 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 as CreateSessionOptions | undefined;
+    if (options?.hooks) {
+      // options.hooks has keys like "before.session.create"
+      const hookArray = (options.hooks as Record<string, unknown>)[hookKey] as SessionComponentHooks[typeof hookKey] ?? [];
+      for (const hook of hookArray) {
+        if (hook.before) {
+          await hook.before(hookContext);
+        }
+      }
+    }
+  }
+
+  private async executeAfterHooks(
+    operation: string,
+    context: Record<string, unknown>
+  ): Promise<void> {
+    const hookKey = `after.session.${operation}` as keyof SessionComponentHooks;
+    const hooks = this.hooksConfig[hookKey] ?? [];
+    const hookContext = context as unknown as SessionHookContext;
+    
+    // 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 as CreateSessionOptions | undefined;
+    if (options?.hooks) {
+      // options.hooks has keys like "after.session.create"
+      const hookArray = (options.hooks as Record<string, unknown>)[hookKey] as SessionComponentHooks[typeof hookKey] ?? [];
+      for (const hook of hookArray) {
+        if (hook.after) {
+          await hook.after(hookContext);
+        }
+      }
+    }
+  }
+
+  // ============ Helper Methods ============
+
+  private generateTitle(): string {
+    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: any, llmComponent: any): void {
+    this.promptComponent = promptComponent;
+    this.llmComponent = llmComponent;
+    this.summaryAgent = new SummaryAgent(promptComponent, llmComponent);
+  }
+
+  /**
+   * 初始化 SummaryAgent（如未初始化）
+   */
+  private ensureSummaryAgent(): void {
+    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 生成的场景化提示
+   */
+  @TracedAs("session.generateCompactHint")
+  async generateCompactHint(sessionId: string): Promise<string> {
+    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 参数，用于指导不同场景下的压缩重点提取
+   */
+  @TracedAs("session.compact", { recordParams: true, recordResult: true })
+  async compact(sessionId: string, options?: CompactOptions): Promise<CompactResult> {
+    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: SessionCheckpoint = {
+      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 }
+   */
+  @TracedAs("session.extractRecentMessages")
+  private extractRecentMessages(
+    messages: SessionMessage[], 
+    turnCount: number = 2
+  ): { role: string; content: string }[] {
+    const recentMessages: { role: string; content: string }[] = [];
+    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: string): Promise<CompactPreview> {
+    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: string): Promise<SessionCheckpoint[]> {
+    return await this.store!.getCheckpoints(sessionId);
+  }
+
+  /**
+   * Get a specific checkpoint
+   */
+  async getCheckpoint(sessionId: string, checkpointId: string): Promise<SessionCheckpoint | undefined> {
+    return await this.store!.getCheckpoint(sessionId, checkpointId);
+  }
+
+  /**
+   * Delete a checkpoint and restore archived messages
+   */
+  async deleteCheckpoint(sessionId: string, checkpointId: string): Promise<boolean> {
+    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: string, options?: GetContextOptions): Promise<GetContextResult> {
+    const session = await this.get(sessionId);
+    if (!session) {
+      throw new Error(`Session not found`);
+    }
+
+    let contextMessages: SessionMessage[] = [];
+    let startCheckpoint: SessionCheckpoint | undefined;
+
+    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: number[] = [];
+      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 as SessionCheckpoint);
+
+    // 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: string): Promise<boolean> {
+    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: SearchMessagesOptions): Promise<SearchResult[]> {
+    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: Session[];
+    if (sessionId) {
+      const session = await this.get(sessionId);
+      sessions = session ? [session] : [];
+    } else {
+      sessions = await this.list({ limit: 1000 }); // Get all sessions
+    }
+
+    const results: SearchResult[] = [];
+    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: MessageMatch[] = [];
+
+      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: MessageMatch = {
+            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
+   */
+  private getLatestCheckpoint(session: Session): SessionCheckpoint | undefined {
+    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.
+   */
+  private createCheckpointMessage(checkpoint: SessionCheckpoint): AddMessageOptions {
+    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" as const,
+        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,
+      },
+    };
+  }
+}