claude-brain 0.30.2 → 0.30.3

package/src/routing/handlers/shared.ts

@@ -0,0 +1,515 @@
+/**
+ * Shared Handler Utilities
+ * Task 3.1: Helper functions extracted from BrainRouter for use by domain handlers
+ */
+
+import type { HandlerContext, RecentDecision, BrainExtractedEntities, BrainResponse, TierResults, FilterableResult } from './types'
+import { DEFAULT_PROJECT, RECENT_DECISION_WINDOW_MS } from './types'
+import {
+  getMemoryService,
+  getVaultService,
+  getEpisodeService,
+  getCodeLinker,
+  getCodeQuery
+} from '@/server/services'
+
+/** Return a "services not ready" BrainResponse */
+export function servicesNotReady(): BrainResponse {
+  return {
+    action: 'none',
+    summary: 'Services not initialized',
+    content: 'Claude Brain services are not ready. The server may still be starting up.',
+    relevantItems: 0
+  }
+}
+
+/** Write decision to vault (fire-and-forget) */
+export async function writeToVault(
+  project: string,
+  decision: string,
+  reasoning: string,
+  context: string,
+  alternatives?: string
+): Promise<void> {
+  try {
+    const vault = getVaultService()
+    const projectPaths = vault.getProjectPaths(project)
+    const date = new Date().toISOString().split('T')[0]
+    const entry = `### Decision: ${decision.slice(0, 100)}\n\n**Date:** ${date}\n**Context:** ${context}\n**Decision:** ${decision}\n**Reasoning:** ${reasoning}\n${alternatives ? `**Alternatives:** ${alternatives}\n` : ''}\n---\n\n`
+    await vault.writer.appendContent(projectPaths.decisions, entry, '\n')
+  } catch {
+    // Vault write failed
+  }
+}
+
+/** Link a stored decision/pattern/correction to the active episode */
+export function linkToActiveEpisode(project: string, id: string, type: 'decision' | 'pattern' | 'correction'): void {
+  try {
+    const episodeManager = getEpisodeService()
+    if (!episodeManager) return
+    const activeEpisode = episodeManager.getActiveEpisode(project)
+    if (!activeEpisode) return
+
+    if (type === 'decision') episodeManager.linkDecision(activeEpisode.id, id)
+    else if (type === 'pattern') episodeManager.linkPattern(activeEpisode.id, id)
+    else if (type === 'correction') episodeManager.linkCorrection(activeEpisode.id, id)
+  } catch {
+    // Episode manager not available
+  }
+}
+
+/** Link a stored observation to code files (non-blocking, fire-and-forget) */
+export function linkToCodeFiles(ctx: HandlerContext, observationId: string, content: string, project: string): void {
+  try {
+    const linker = getCodeLinker()
+    if (linker) {
+      linker.linkObservation(observationId, content, project).catch(err => {
+        ctx.logger.debug({ err }, 'Code linkage failed (non-fatal)')
+      })
+    }
+  } catch {
+    // Linker not available
+  }
+}
+
+/** Register a message with the episode manager */
+export function registerEpisodeMessage(ctx: HandlerContext, message: string, project?: string, role: string = 'user'): void {
+  try {
+    const episodeManager = getEpisodeService()
+    if (!episodeManager) return
+    episodeManager.processMessage(
+      { role: role as 'user' | 'assistant' | 'system', content: message, timestamp: new Date().toISOString() },
+      project
+    ).catch((error) => {
+      ctx.logger.warn({ error }, 'Background episode message processing failed')
+    })
+  } catch {
+    // Episode manager not available
+  }
+}
+
+/** Store as a new decision (fallback for update when no match found) */
+export async function storeAsNew(
+  ctx: HandlerContext,
+  memory: import('@/memory').MemoryManager,
+  project: string,
+  message: string,
+  topic: string,
+  entities: BrainExtractedEntities,
+  reason: string
+): Promise<BrainResponse> {
+  const decisionId = await memory.rememberDecision(
+    project,
+    topic.slice(0, 200),
+    message,
+    entities.reasoning || '',
+    { tags: entities.technologies.length > 0 ? entities.technologies : ['updated'] }
+  )
+
+  ctx.setLastStored(decisionId, project)
+  ctx.searchEngine.invalidateCache(project)
+
+  return {
+    action: 'stored',
+    summary: `Stored as new (${reason})`,
+    content: `Stored as new decision (ID: ${decisionId})\n\n**Project:** ${project}\n**Content:** ${message}`,
+    relevantItems: 1
+  }
+}
+
+/** Look up a single observation by ID (FTS5 first, then ChromaDB) */
+export async function lookupById(id: string): Promise<Record<string, unknown> | null> {
+  const memory = getMemoryService()
+
+  // Try FTS5 first (fast, direct lookup)
+  if (memory.fts5) {
+    const result = memory.fts5.getById(id)
+    if (result) return result
+  }
+
+  // Fallback: search ChromaDB by ID if available
+  if (memory.isChromaDBEnabled()) {
+    try {
+      const collections = memory.chroma.collections
+      // Try decisions collection
+      const decisions = await collections.getDecisions()
+      if (decisions) {
+        try {
+          const result = await decisions.get({ ids: [id] })
+          if (result?.documents?.[0]) {
+            const meta = (result.metadatas?.[0] || {}) as Record<string, unknown>
+            return {
+              id,
+              content: result.documents[0],
+              metadata: meta,
+              category: 'decision',
+              project: (meta.project as string) || '',
+              created_at: (meta.created_at as string) || '',
+              reasoning: (meta.reasoning as string) || null,
+              tags: [],
+              confidence: 0.8
+            }
+          }
+        } catch { /* ID not in this collection */ }
+      }
+    } catch {
+      // ChromaDB lookup failed
+    }
+  }
+
+  return null
+}
+
+/** Increment access count for an observation */
+export function incrementAccess(id: string): void {
+  try {
+    const memory = getMemoryService()
+    if (memory.fts5) {
+      memory.fts5.recordAccess(id)
+    }
+  } catch {
+    // Non-critical
+  }
+}
+
+/** Fetch recent observations in a date range */
+export async function fetchRecentObservations(
+  project: string | undefined,
+  start: Date,
+  end: Date
+): Promise<Record<string, unknown>[]> {
+  const memory = getMemoryService()
+
+  // Try FTS5 first (efficient SQL-level date filtering)
+  if (memory.fts5 && project) {
+    return memory.fts5.fetchByTimeRange(project, start, end)
+  }
+
+  // Also try FTS5 without project filter
+  if (memory.fts5 && !project) {
+    // FTS5 fetchByTimeRange requires project, use fetchAll with date filtering
+    try {
+      const all = memory.fts5.search('*', undefined, 100)
+      return all.filter(r => {
+        const date = new Date(r.created_at)
+        if (isNaN(date.getTime())) return false
+        return date >= start && date <= end
+      }).sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())
+    } catch {
+      // FTS5 search failed, fall through
+    }
+  }
+
+  // Fallback: use memory fetchAll with date filtering
+  try {
+    const allDecisions = await memory.fetchAllDecisions(project)
+    const allPatterns = await memory.fetchAllPatterns(project)
+    const allCorrections = await memory.fetchAllCorrections(project)
+
+    const allItems = [
+      ...allDecisions.map((d: Record<string, unknown>) => ({
+        id: d.id || d.decision_id,
+        content: d.decision || d.document || d.content || '',
+        category: 'decision',
+        project: d.project || project || DEFAULT_PROJECT,
+        created_at: d.created_at || d.date || '',
+      })),
+      ...allPatterns.map((p: Record<string, unknown>) => ({
+        id: p.id,
+        content: p.description || p.document || p.content || '',
+        category: p.pattern_type || 'pattern',
+        project: p.project || project || DEFAULT_PROJECT,
+        created_at: p.created_at || '',
+      })),
+      ...allCorrections.map((c: Record<string, unknown>) => ({
+        id: c.id,
+        content: c.original || c.document || c.content || '',
+        category: 'correction',
+        project: c.project || project || DEFAULT_PROJECT,
+        created_at: c.created_at || '',
+      })),
+    ]
+
+    return allItems.filter(item => {
+      if (!item.created_at) return true // include items without dates
+      const date = new Date(item.created_at)
+      if (isNaN(date.getTime())) return true
+      return date >= start && date <= end
+    }).sort((a, b) => {
+      const dateA = new Date(a.created_at || 0).getTime()
+      const dateB = new Date(b.created_at || 0).getTime()
+      return dateB - dateA
+    })
+  } catch {
+    return []
+  }
+}
+
+/** Query code intelligence for symbols and files matching a query */
+export function queryCodeIntelligence(ctx: HandlerContext, query: string, project: string | undefined): TierResults | null {
+  try {
+    const codeQuery = getCodeQuery()
+    if (!codeQuery) return null
+
+    // Extract meaningful keywords from query for code search
+    const keywords = extractCodeKeywords(query)
+    if (keywords.length === 0) return null
+
+    const results: FilterableResult[] = []
+
+    for (const keyword of keywords) {
+      // Search symbols across all indexed projects (project may not match code index project name)
+      const symbolResults = codeQuery.findSymbols(keyword, project || '', 5)
+
+      // If no results with project filter, try without (code index may use path-based project names)
+      const symbols = symbolResults.length > 0
+        ? symbolResults
+        : codeQuery.findSymbols(keyword, '', 5)
+
+      for (const sym of symbols.slice(0, 3)) {
+        const location = sym.lineEnd
+          ? `${sym.filePath}:${sym.lineStart}-${sym.lineEnd}`
+          : `${sym.filePath}:${sym.lineStart}`
+        const sigPart = sym.signature ? ` — \`${sym.signature}\`` : ''
+        results.push({
+          content: `**${sym.symbol}** (${sym.type}) at \`${location}\`${sigPart}`,
+          score: sym.confidence * 0.6, // Scale down so memories rank higher
+          source: 'Code Index',
+          metadata: {
+            filePath: sym.filePath,
+            lineStart: sym.lineStart,
+            lineEnd: sym.lineEnd,
+            symbolType: sym.type,
+          }
+        })
+      }
+
+      // Also search files by name/summary
+      const fileResults = codeQuery.findFiles(keyword, project || '')
+      const files = fileResults.length > 0
+        ? fileResults
+        : codeQuery.findFiles(keyword, '')
+
+      for (const file of files.slice(0, 3)) {
+        // Skip if we already have symbol results from this file
+        if (results.some(r => (r.metadata as Record<string, unknown> | undefined)?.filePath === file.filePath)) continue
+        const summaryPart = file.summary ? ` — ${file.summary}` : ''
+        results.push({
+          content: `**${file.filePath}** (${file.language || 'unknown'}, ${file.symbolCount} symbols, ${file.lineCount} lines)${summaryPart}`,
+          score: 0.4, // File matches are lower confidence
+          source: 'Code Index',
+          metadata: {
+            filePath: file.filePath,
+            symbolCount: file.symbolCount,
+          }
+        })
+      }
+    }
+
+    // Deduplicate by filePath
+    const seen = new Set<string>()
+    const deduped = results.filter(r => {
+      const fp = (r.metadata as Record<string, unknown> | undefined)?.filePath
+      if (fp && seen.has(fp)) return false
+      if (fp) seen.add(fp)
+      return true
+    })
+
+    if (deduped.length === 0) return null
+
+    return {
+      label: 'Code Intelligence',
+      results: deduped.slice(0, 5)
+    }
+  } catch (error) {
+    ctx.logger.debug({ error }, 'Code intelligence query failed (non-fatal)')
+    return null
+  }
+}
+
+/** Extract meaningful keywords from a natural language query for code search */
+export function extractCodeKeywords(query: string): string[] {
+  const STOP_WORDS = new Set([
+    'how', 'what', 'where', 'when', 'why', 'who', 'which', 'are', 'is', 'was',
+    'were', 'been', 'being', 'have', 'has', 'had', 'having', 'do', 'does', 'did',
+    'doing', 'will', 'would', 'could', 'should', 'shall', 'can', 'may', 'might',
+    'must', 'the', 'a', 'an', 'and', 'but', 'or', 'nor', 'for', 'yet', 'so',
+    'in', 'on', 'at', 'to', 'from', 'by', 'with', 'about', 'into', 'through',
+    'during', 'before', 'after', 'above', 'below', 'between', 'out', 'off', 'over',
+    'under', 'again', 'further', 'then', 'once', 'here', 'there', 'all', 'each',
+    'every', 'both', 'few', 'more', 'most', 'other', 'some', 'such', 'only', 'own',
+    'same', 'than', 'too', 'very', 'just', 'because', 'not', 'this', 'that', 'these',
+    'those', 'its', 'our', 'their', 'your', 'my', 'me', 'we', 'you', 'they', 'them',
+    'know', 'tell', 'show', 'find', 'get', 'make', 'use', 'using', 'used', 'managing',
+    'managed', 'handle', 'handling', 'handled', 'work', 'working', 'works', 'implement',
+    'implementing', 'implemented', 'doing', 'done', 'project', 'code', 'file', 'function',
+  ])
+
+  const words = query.toLowerCase()
+    .replace(/[^a-z0-9\s-_]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 2 && !STOP_WORDS.has(w))
+
+  // Also try multi-word phrases (camelCase/kebab-case patterns the user might reference)
+  const phrases: string[] = []
+  for (let i = 0; i < words.length - 1; i++) {
+    // Create camelCase combo: "brain router" -> "brainRouter"
+    const w1 = words[i]!
+    const w2 = words[i + 1]!
+    phrases.push(w1 + w2.charAt(0).toUpperCase() + w2.slice(1))
+  }
+
+  // Return unique keywords, single words first then phrases
+  return [...new Set([...words, ...phrases])].slice(0, 5)
+}
+
+/** Check if a delete/update message has descriptive content beyond just the command words */
+export function hasDescriptiveContent(message: string): boolean {
+  const COMMAND_WORDS = [
+    'forget', 'delete', 'remove', 'discard', 'erase', 'undo', 'clear', 'drop',
+    'actually', 'correction', 'update', 'change', 'replace', 'modify', 'revise',
+    'amend', 'override', 'scratch', 'no', 'wait', 'instead',
+    'that', 'this', 'the', 'it', 'about', 'memory', 'decision', 'to', 'a', 'an'
+  ]
+  const words = message.toLowerCase().split(/[\s,;:.!?]+/).filter(w => w.length > 1)
+  const meaningfulWords = words.filter(w => !COMMAND_WORDS.includes(w))
+  return meaningfulWords.length >= 2
+}
+
+/** Detect session recall queries */
+export function isSessionRecallQuery(message: string): boolean {
+  const lower = message.toLowerCase()
+  const SESSION_RECALL_PHRASES = [
+    'what have we discussed',
+    'what did we discuss',
+    'what have we talked about',
+    'what did we talk about',
+    'this session',
+    'current session',
+    'session so far',
+    'what have we done',
+    'what did we do',
+    'session summary',
+    'summarize this session',
+    'recap this session',
+    'what happened this session',
+    'what have we covered'
+  ]
+  return SESSION_RECALL_PHRASES.some(p => lower.includes(p))
+}
+
+/** Detect complex multi-part questions */
+export function isComplexQuestion(message: string): boolean {
+  // Multiple question marks
+  const questionMarks = (message.match(/\?/g) || []).length
+  if (questionMarks >= 2) return true
+  // Very long question (likely multi-part)
+  if (message.length > 200 && message.includes('?')) return true
+  // Multiple clauses with "and" or "also"
+  if (message.includes(' and ') && message.includes('?') && message.length > 100) return true
+  return false
+}
+
+/** Detect category-based intent from question messages */
+export function detectCategoryIntent(message: string): 'decision' | 'pattern' | 'correction' | null {
+  const lower = message.toLowerCase()
+
+  // Decision-oriented queries
+  if (
+    lower.includes('what decisions') || lower.includes('my decisions') ||
+    lower.includes('what have i decided') || lower.includes('what did i decide') ||
+    lower.includes('what choices') || lower.includes('decisions i') ||
+    lower.includes('list decisions') || lower.includes('show decisions') ||
+    lower.includes('all decisions') || lower.includes('what did i choose')
+  ) {
+    return 'decision'
+  }
+
+  // Pattern-oriented queries
+  if (
+    lower.includes('what patterns') || lower.includes('my patterns') ||
+    lower.includes('best practices') || lower.includes('conventions') ||
+    lower.includes('list patterns') || lower.includes('show patterns') ||
+    lower.includes('all patterns')
+  ) {
+    return 'pattern'
+  }
+
+  // Correction-oriented queries
+  if (
+    lower.includes('what mistakes') || lower.includes('my mistakes') ||
+    lower.includes('what bugs') || lower.includes('lessons learned') ||
+    lower.includes('what corrections') || lower.includes('my corrections') ||
+    lower.includes('list corrections') || lower.includes('show corrections') ||
+    lower.includes('all corrections') || lower.includes('what have i fixed') ||
+    lower.includes('what did i fix')
+  ) {
+    return 'correction'
+  }
+
+  return null
+}
+
+/** Generate a task ID from a title string */
+export function generateTaskId(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 50)
+}
+
+/** Optionally compress content before storing */
+export async function maybeCompress(
+  ctx: HandlerContext,
+  content: string,
+  category: string
+): Promise<{ content: string; rawContent?: string }> {
+  if (!ctx.compressor) return { content }
+  try {
+    const result = await ctx.compressor.compress(content, category)
+    if (result.compressed) {
+      return { content: result.summary, rawContent: result.original }
+    }
+  } catch {
+    // Compression failed, use original
+  }
+  return { content }
+}
+
+/** Find recent decisions matching a query by keyword overlap */
+export function findRecentDecisions(ctx: HandlerContext, query: string, project?: string): RecentDecision[] {
+  const now = Date.now()
+  // Prune expired
+  ctx.recentDecisions = ctx.recentDecisions.filter(
+    d => now - d.storedAt < RECENT_DECISION_WINDOW_MS
+  )
+
+  const queryWords = new Set(
+    query.toLowerCase().split(/\s+/).filter(w => w.length > 2)
+  )
+  if (queryWords.size === 0) return []
+
+  const matches: RecentDecision[] = []
+  for (const d of ctx.recentDecisions) {
+    // Project filter: skip if searching a specific project and it doesn't match
+    if (project && d.project !== project) continue
+    const contentWords = new Set(d.content.toLowerCase().split(/\s+/).filter(w => w.length > 2))
+    const overlap = [...queryWords].filter(w => contentWords.has(w)).length
+    if (overlap >= 1) {
+      const overlapScore = overlap / queryWords.size
+      matches.push({ ...d, overlapScore })
+    }
+  }
+  return matches
+}
+
+/** Track a recently stored decision for recency fast path */
+export function trackRecentDecision(ctx: HandlerContext, content: string, project: string): void {
+  const now = Date.now()
+  // Prune expired entries
+  ctx.recentDecisions = ctx.recentDecisions.filter(
+    d => now - d.storedAt < RECENT_DECISION_WINDOW_MS
+  )
+  ctx.recentDecisions.push({ content, project, storedAt: now })
+}

package/src/routing/handlers/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Handler Types
+ * Task 3.1: Shared types for domain handler modules
+ */
+
+import type { Logger } from 'pino'
+import type { BrainExtractedEntities } from '../entity-extractor'
+import type { ClassificationResult, IntentClassifier } from '../intent-classifier'
+import type { BrainResponse } from '../response-filter'
+import type { SearchEngine } from '../search-engine'
+import type { ObservationCompressor } from '@/memory/compression'
+
+export interface HandlerContext {
+  logger: Logger
+  searchEngine: SearchEngine
+  classifier: IntentClassifier
+  compressor: ObservationCompressor | null
+  lastStoredId: string | null
+  lastStoredProject: string | null
+  recentDecisions: RecentDecision[]
+  setLastStored(id: string, project: string): void
+  trackRecentDecision(content: string, project: string): void
+}
+
+export interface RecentDecision {
+  content: string
+  project: string
+  storedAt: number
+  /** Keyword overlap ratio with query (0-1), computed by findRecentDecisions */
+  overlapScore?: number
+}
+
+export const DEFAULT_PROJECT = 'general'
+export const DELETE_MIN_SIMILARITY = 0.3
+export const UPDATE_MIN_SIMILARITY = 0.3
+export const RECENT_DECISION_WINDOW_MS = 60_000
+
+export type IntentHandler = (
+  message: string,
+  project: string | undefined,
+  entities: BrainExtractedEntities,
+  classification?: ClassificationResult
+) => Promise<BrainResponse>
+
+// Re-export types used by handlers for convenience
+export type { BrainExtractedEntities } from '../entity-extractor'
+export type { ClassificationResult } from '../intent-classifier'
+export type { BrainResponse, TierResults, FilterableResult } from '../response-filter'