@ai-setting/roy-agent-core 1.3.10 → 1.3.14

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

@@ -1,1249 +0,0 @@
-/**
- * @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,
-      },
-    };
-  }
-}