claude-brain 0.15.2 → 0.17.0

package/src/hooks/session-tracker.ts

@@ -1,275 +1,312 @@
-/**
- * Phase 17: Session Tracker
- * Server-side session tracking that maintains state across hook invocations.
- * Buffers CapturedKnowledge items and generates session summaries on idle/stop.
- */
-
-import type { Logger } from 'pino'
-import type { EpisodeManager } from '@/memory/episodic/manager'
-import type { MemoryManager } from '@/memory'
-import { ExtractiveSummarizer } from '@/memory/episodic/summarizer'
-import type { CapturedKnowledge } from './types'
-import type { HooksConfig } from '@/config/schema'
-
-interface SessionState {
-  sessionId: string
-  project?: string
-  items: CapturedKnowledge[]
-  startedAt: string
-  lastActivityAt: string
-  episodeId?: string
-}
-
-export class HookSessionTracker {
-  private logger: Logger
-  private episodeManager: EpisodeManager | null
-  private memoryManager: MemoryManager | null
-  private summarizer: ExtractiveSummarizer
-  private sessions: Map<string, SessionState> = new Map()
-  private idleTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
-  private idleTimeoutMs: number
-  private minEventsForSummary: number
-
-  constructor(
-    logger: Logger,
-    episodeManager: EpisodeManager | null,
-    config?: HooksConfig['sessions'],
-    memoryManager?: MemoryManager | null
-  ) {
-    this.logger = logger.child({ component: 'hook-session-tracker' })
-    this.episodeManager = episodeManager
-    this.memoryManager = memoryManager ?? null
-    this.summarizer = new ExtractiveSummarizer()
-    this.idleTimeoutMs = (config?.idleTimeoutMinutes ?? 30) * 60 * 1000
-    this.minEventsForSummary = config?.minEventsForSummary ?? 3
-  }
-
-  /**
-   * Track a captured knowledge item within a session.
-   */
-  async track(sessionId: string, knowledge: CapturedKnowledge): Promise<void> {
-    let session = this.sessions.get(sessionId)
-
-    if (!session) {
-      session = {
-        sessionId,
-        project: knowledge.project,
-        items: [],
-        startedAt: new Date().toISOString(),
-        lastActivityAt: new Date().toISOString(),
-      }
-      this.sessions.set(sessionId, session)
-
-      // Start episode if manager available
-      if (this.episodeManager) {
-        try {
-          const episode = await this.episodeManager.startEpisode(knowledge.project)
-          session.episodeId = episode.id
-        } catch (err) {
-          this.logger.warn({ err }, 'Failed to start episode for session')
-        }
-      }
-    }
-
-    session.items.push(knowledge)
-    session.lastActivityAt = new Date().toISOString()
-
-    // Reset idle timer
-    this.resetIdleTimer(sessionId)
-  }
-
-  /**
-   * End a session immediately (triggered by Stop hook event).
-   */
-  async endSession(sessionId: string): Promise<void> {
-    const session = this.sessions.get(sessionId)
-    if (!session) return
-
-    this.clearIdleTimer(sessionId)
-    await this.summarizeAndPersist(session)
-    this.sessions.delete(sessionId)
-  }
-
-  /**
-   * End all active sessions (for server shutdown).
-   */
-  async endAllSessions(): Promise<void> {
-    const sessionIds = Array.from(this.sessions.keys())
-    for (const id of sessionIds) {
-      await this.endSession(id)
-    }
-  }
-
-  /**
-   * Get stats about tracked sessions.
-   */
-  getStats(): { activeSessions: number; totalItems: number } {
-    let totalItems = 0
-    for (const session of this.sessions.values()) {
-      totalItems += session.items.length
-    }
-    return { activeSessions: this.sessions.size, totalItems }
-  }
-
-  private resetIdleTimer(sessionId: string): void {
-    this.clearIdleTimer(sessionId)
-    const timer = setTimeout(() => {
-      this.onIdle(sessionId)
-    }, this.idleTimeoutMs)
-    this.idleTimers.set(sessionId, timer)
-  }
-
-  private clearIdleTimer(sessionId: string): void {
-    const existing = this.idleTimers.get(sessionId)
-    if (existing) {
-      clearTimeout(existing)
-      this.idleTimers.delete(sessionId)
-    }
-  }
-
-  private async onIdle(sessionId: string): Promise<void> {
-    this.logger.debug({ sessionId }, 'Session idle timeout, summarizing')
-    await this.endSession(sessionId)
-  }
-
-  /**
-   * Build a structured summary from session items.
-   * Format: "Did: ...; Decided: ...; Files: ..."
-   */
-  private buildStructuredSummary(session: SessionState): string {
-    const actions: string[] = []
-    const decisions: string[] = []
-    const files = new Set<string>()
-
-    for (const item of session.items) {
-      // Extract file paths from metadata
-      if (item.metadata?.file_path) {
-        files.add(item.metadata.file_path)
-      }
-      if (item.metadata?.files) {
-        for (const f of Array.isArray(item.metadata.files) ? item.metadata.files : [item.metadata.files]) {
-          files.add(f)
-        }
-      }
-
-      if (item.type === 'decision') {
-        decisions.push(item.content.slice(0, 80))
-      } else if (item.type === 'progress') {
-        actions.push(item.content.slice(0, 80))
-      } else if (item.type === 'pattern' || item.type === 'correction') {
-        actions.push(`[${item.type}] ${item.content.slice(0, 60)}`)
-      }
-    }
-
-    const parts: string[] = []
-    if (actions.length > 0) {
-      parts.push(`Did: ${actions.slice(0, 5).join('; ')}`)
-    }
-    if (decisions.length > 0) {
-      parts.push(`Decided: ${decisions.slice(0, 3).join('; ')}`)
-    }
-    if (files.size > 0) {
-      const fileList = [...files].slice(0, 8)
-      parts.push(`Files: ${fileList.join(', ')}`)
-    }
-
-    return parts.join('. ') || `Session with ${session.items.length} events`
-  }
-
-  private async summarizeAndPersist(session: SessionState): Promise<void> {
-    if (session.items.length < this.minEventsForSummary) {
-      this.logger.debug(
-        { sessionId: session.sessionId, items: session.items.length },
-        'Too few items for summary, skipping'
-      )
-      // Still end the episode if started
-      if (session.episodeId && this.episodeManager) {
-        try {
-          await this.episodeManager.endEpisode(session.episodeId)
-        } catch {}
-      }
-      return
-    }
-
-    this.logger.info(
-      { sessionId: session.sessionId, items: session.items.length, project: session.project },
-      'Summarizing session'
-    )
-
-    // Build a synthetic episode for the summarizer
-    const messages = session.items.map((item) => ({
-      role: 'assistant' as const,
-      content: `[${item.type}] ${item.content}`,
-      timestamp: item.timestamp,
-      token_estimate: Math.ceil(item.content.length / 4),
-    }))
-
-    const syntheticEpisode = {
-      id: session.sessionId,
-      project: session.project,
-      status: 'completed' as const,
-      started_at: session.startedAt,
-      ended_at: new Date().toISOString(),
-      messages,
-      related_decisions: session.items
-        .filter(i => i.type === 'decision')
-        .map((_, idx) => `hook-decision-${idx}`),
-      related_patterns: session.items
-        .filter(i => i.type === 'pattern')
-        .map((_, idx) => `hook-pattern-${idx}`),
-      related_corrections: session.items
-        .filter(i => i.type === 'correction')
-        .map((_, idx) => `hook-correction-${idx}`),
-      token_count: messages.reduce((sum, m) => sum + (m.token_estimate || 0), 0),
-      message_count: messages.length,
-    }
-
-    const extractiveSummary = this.summarizer.summarize(syntheticEpisode)
-
-    // Phase 21: Build structured summary alongside extractive
-    const structuredSummary = this.buildStructuredSummary(session)
-
-    // End the episode with summary attached
-    if (session.episodeId && this.episodeManager) {
-      try {
-        // Add messages to episode before ending
-        for (const msg of messages) {
-          await this.episodeManager.addMessage(session.episodeId, msg)
-        }
-        await this.episodeManager.endEpisode(session.episodeId)
-      } catch (err) {
-        this.logger.warn({ err, sessionId: session.sessionId }, 'Failed to end episode')
-      }
-    }
-
-    // Phase 20+21: Store session summary as a searchable decision
-    // Uses structured summary for better auto-context readability
-    if (this.memoryManager && (extractiveSummary.brief || structuredSummary)) {
-      try {
-        const project = session.project || 'general'
-        const technologies = [...new Set(session.items.flatMap(i => i.technologies))]
-        const summaryContent = `Session summary: ${structuredSummary}${extractiveSummary.key_topics.length > 0 ? ` (Topics: ${extractiveSummary.key_topics.join(', ')})` : ''}`
-
-        await this.memoryManager.rememberDecision(
-          project,
-          'Auto-captured session summary',
-          summaryContent,
-          'Session ended — auto-summarized by passive hooks',
-          { tags: ['session-summary', ...technologies] }
-        )
-
-        this.logger.info(
-          { sessionId: session.sessionId, project },
-          'Session summary stored as searchable memory'
-        )
-      } catch (err) {
-        this.logger.warn({ err, sessionId: session.sessionId }, 'Failed to store session summary')
-      }
-    }
-
-    this.logger.info(
-      { sessionId: session.sessionId, summary: structuredSummary },
-      'Session summarized'
-    )
-  }
-}
+/**
+ * Phase 17: Session Tracker
+ * Server-side session tracking that maintains state across hook invocations.
+ * Buffers CapturedKnowledge items and generates session summaries on idle/stop.
+ */
+
+import type { Logger } from 'pino'
+import type { EpisodeManager } from '@/memory/episodic/manager'
+import type { MemoryManager } from '@/memory'
+import { ExtractiveSummarizer } from '@/memory/episodic/summarizer'
+import type { CapturedKnowledge } from './types'
+import type { HooksConfig } from '@/config/schema'
+
+interface SessionState {
+  sessionId: string
+  project?: string
+  items: CapturedKnowledge[]
+  startedAt: string
+  lastActivityAt: string
+  episodeId?: string
+}
+
+export class HookSessionTracker {
+  private logger: Logger
+  private episodeManager: EpisodeManager | null
+  private memoryManager: MemoryManager | null
+  private summarizer: ExtractiveSummarizer
+  private sessions: Map<string, SessionState> = new Map()
+  private idleTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
+  private idleTimeoutMs: number
+  private minEventsForSummary: number
+
+  constructor(
+    logger: Logger,
+    episodeManager: EpisodeManager | null,
+    config?: HooksConfig['sessions'],
+    memoryManager?: MemoryManager | null
+  ) {
+    this.logger = logger.child({ component: 'hook-session-tracker' })
+    this.episodeManager = episodeManager
+    this.memoryManager = memoryManager ?? null
+    this.summarizer = new ExtractiveSummarizer()
+    this.idleTimeoutMs = (config?.idleTimeoutMinutes ?? 30) * 60 * 1000
+    this.minEventsForSummary = config?.minEventsForSummary ?? 3
+  }
+
+  /**
+   * Track a captured knowledge item within a session.
+   */
+  async track(sessionId: string, knowledge: CapturedKnowledge): Promise<void> {
+    let session = this.sessions.get(sessionId)
+
+    if (!session) {
+      session = {
+        sessionId,
+        project: knowledge.project,
+        items: [],
+        startedAt: new Date().toISOString(),
+        lastActivityAt: new Date().toISOString(),
+      }
+      this.sessions.set(sessionId, session)
+
+      // Start episode if manager available
+      if (this.episodeManager) {
+        try {
+          const episode = await this.episodeManager.startEpisode(knowledge.project)
+          session.episodeId = episode.id
+        } catch (err) {
+          this.logger.warn({ err }, 'Failed to start episode for session')
+        }
+      }
+    }
+
+    session.items.push(knowledge)
+    session.lastActivityAt = new Date().toISOString()
+
+    // Reset idle timer
+    this.resetIdleTimer(sessionId)
+  }
+
+  /**
+   * End a session immediately (triggered by Stop hook event).
+   */
+  async endSession(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return
+
+    this.clearIdleTimer(sessionId)
+    await this.summarizeAndPersist(session)
+    this.sessions.delete(sessionId)
+  }
+
+  /**
+   * End all active sessions (for server shutdown).
+   */
+  async endAllSessions(): Promise<void> {
+    const sessionIds = Array.from(this.sessions.keys())
+    for (const id of sessionIds) {
+      await this.endSession(id)
+    }
+  }
+
+  /**
+   * Get stats about tracked sessions.
+   */
+  getStats(): { activeSessions: number; totalItems: number } {
+    let totalItems = 0
+    for (const session of this.sessions.values()) {
+      totalItems += session.items.length
+    }
+    return { activeSessions: this.sessions.size, totalItems }
+  }
+
+  private resetIdleTimer(sessionId: string): void {
+    this.clearIdleTimer(sessionId)
+    const timer = setTimeout(() => {
+      this.onIdle(sessionId)
+    }, this.idleTimeoutMs)
+    this.idleTimers.set(sessionId, timer)
+  }
+
+  private clearIdleTimer(sessionId: string): void {
+    const existing = this.idleTimers.get(sessionId)
+    if (existing) {
+      clearTimeout(existing)
+      this.idleTimers.delete(sessionId)
+    }
+  }
+
+  private async onIdle(sessionId: string): Promise<void> {
+    this.logger.debug({ sessionId }, 'Session idle timeout, summarizing')
+    await this.endSession(sessionId)
+  }
+
+  /**
+   * Build a structured summary from session items.
+   * Phase 25: Natural sentence format with project context, deduplication, noise filtering.
+   */
+  private buildStructuredSummary(session: SessionState): string {
+    const decisions = session.items.filter(i => i.type === 'decision')
+    const corrections = session.items.filter(i => i.type === 'correction')
+    const progress = session.items.filter(i => i.type === 'progress')
+
+    // Extract unique technologies across all items
+    const techs = new Set<string>()
+    for (const item of session.items) {
+      for (const t of item.technologies) techs.add(t)
+    }
+
+    // Extract unique files touched
+    const files = new Set<string>()
+    for (const item of session.items) {
+      const filePath = item.metadata?.filePath || item.metadata?.file_path
+      if (filePath) files.add(filePath as string)
+      if (item.metadata?.files) {
+        for (const f of Array.isArray(item.metadata.files) ? item.metadata.files : [item.metadata.files]) {
+          files.add(f as string)
+        }
+      }
+    }
+
+    const parts: string[] = []
+
+    // Project and tech context
+    const project = session.project || 'unknown project'
+    if (techs.size > 0) {
+      parts.push(`Worked on ${project} using ${Array.from(techs).slice(0, 5).join(', ')}`)
+    } else {
+      parts.push(`Worked on ${project}`)
+    }
+
+    // Key decisions (deduplicated, max 3)
+    if (decisions.length > 0) {
+      const uniqueDecisions = this.deduplicateByPrefix(decisions.map(d => d.content), 3)
+      parts.push(`Decisions: ${uniqueDecisions.join('. ')}`)
+    }
+
+    // What was done (git commits and installs only — skip file creation noise)
+    const meaningfulProgress = progress.filter(p =>
+      p.metadata?.action === 'git' || p.metadata?.action === 'install' ||
+      (p.metadata?.action === 'build' && p.metadata?.failed)
+    )
+    if (meaningfulProgress.length > 0) {
+      const uniqueProgress = this.deduplicateByPrefix(meaningfulProgress.map(p => p.content), 3)
+      parts.push(`Progress: ${uniqueProgress.join('. ')}`)
+    }
+
+    // Lessons learned (always valuable, keep all)
+    if (corrections.length > 0) {
+      parts.push(`Lessons: ${corrections.map(c => c.content).join('. ')}`)
+    }
+
+    // File count (not full list — just a signal of scope)
+    if (files.size > 0) {
+      parts.push(`Touched ${files.size} file${files.size > 1 ? 's' : ''}`)
+    }
+
+    return parts.join('. ') || 'Session with no significant events captured.'
+  }
+
+  /** Deduplicate strings by checking if one starts with the first 30 chars of another */
+  private deduplicateByPrefix(items: string[], max: number): string[] {
+    const seen = new Set<string>()
+    const result: string[] = []
+    for (const item of items) {
+      const prefix = item.slice(0, 30).toLowerCase()
+      if (!seen.has(prefix)) {
+        seen.add(prefix)
+        result.push(item)
+        if (result.length >= max) break
+      }
+    }
+    return result
+  }
+
+  private async summarizeAndPersist(session: SessionState): Promise<void> {
+    if (session.items.length < this.minEventsForSummary) {
+      this.logger.debug(
+        { sessionId: session.sessionId, items: session.items.length },
+        'Too few items for summary, skipping'
+      )
+      // Still end the episode if started
+      if (session.episodeId && this.episodeManager) {
+        try {
+          await this.episodeManager.endEpisode(session.episodeId)
+        } catch {}
+      }
+      return
+    }
+
+    this.logger.info(
+      { sessionId: session.sessionId, items: session.items.length, project: session.project },
+      'Summarizing session'
+    )
+
+    // Build a synthetic episode for the summarizer
+    const messages = session.items.map((item) => ({
+      role: 'assistant' as const,
+      content: `[${item.type}] ${item.content}`,
+      timestamp: item.timestamp,
+      token_estimate: Math.ceil(item.content.length / 4),
+    }))
+
+    const syntheticEpisode = {
+      id: session.sessionId,
+      project: session.project,
+      status: 'completed' as const,
+      started_at: session.startedAt,
+      ended_at: new Date().toISOString(),
+      messages,
+      related_decisions: session.items
+        .filter(i => i.type === 'decision')
+        .map((_, idx) => `hook-decision-${idx}`),
+      related_patterns: session.items
+        .filter(i => i.type === 'pattern')
+        .map((_, idx) => `hook-pattern-${idx}`),
+      related_corrections: session.items
+        .filter(i => i.type === 'correction')
+        .map((_, idx) => `hook-correction-${idx}`),
+      token_count: messages.reduce((sum, m) => sum + (m.token_estimate || 0), 0),
+      message_count: messages.length,
+    }
+
+    const extractiveSummary = this.summarizer.summarize(syntheticEpisode)
+
+    // Phase 21: Build structured summary alongside extractive
+    const structuredSummary = this.buildStructuredSummary(session)
+
+    // End the episode with summary attached
+    if (session.episodeId && this.episodeManager) {
+      try {
+        // Add messages to episode before ending
+        for (const msg of messages) {
+          await this.episodeManager.addMessage(session.episodeId, msg)
+        }
+        await this.episodeManager.endEpisode(session.episodeId)
+      } catch (err) {
+        this.logger.warn({ err, sessionId: session.sessionId }, 'Failed to end episode')
+      }
+    }
+
+    // Phase 20+21: Store session summary as a searchable decision
+    // Uses structured summary for better auto-context readability
+    if (this.memoryManager && (extractiveSummary.brief || structuredSummary)) {
+      try {
+        const project = session.project || 'general'
+        const technologies = [...new Set(session.items.flatMap(i => i.technologies))]
+        const summaryContent = `Session summary: ${structuredSummary}${extractiveSummary.key_topics.length > 0 ? ` (Topics: ${extractiveSummary.key_topics.join(', ')})` : ''}`
+
+        await this.memoryManager.rememberDecision(
+          project,
+          'Auto-captured session summary',
+          summaryContent,
+          'Session ended — auto-summarized by passive hooks',
+          { tags: ['session-summary', ...technologies] }
+        )
+
+        this.logger.info(
+          { sessionId: session.sessionId, project },
+          'Session summary stored as searchable memory'
+        )
+      } catch (err) {
+        this.logger.warn({ err, sessionId: session.sessionId }, 'Failed to store session summary')
+      }
+    }
+
+    this.logger.info(
+      { sessionId: session.sessionId, summary: structuredSummary },
+      'Session summarized'
+    )
+  }
+}