prjct-cli 0.11.4 → 0.12.0

package/core/agentic/loop-detector/loop-detector.ts

@@ -0,0 +1,222 @@
+/**
+ * Loop Detector Class
+ * Core loop detection and user escalation functionality
+ */
+
+import type { AttemptRecord, EscalationInfo, AttemptResult, AttemptInfo, OutputAnalysis } from './types'
+import { isSimilarError, analyzeErrorPattern, generateEscalationMessage, generateSuggestion } from './error-analysis'
+import { detectHallucination } from './hallucination'
+
+export class LoopDetector {
+  private _attempts: Map<string, AttemptRecord>
+  private _errorPatterns: Map<string, unknown>
+  maxAttempts: number
+  sessionTimeout: number
+
+  constructor() {
+    // Track attempts per command session
+    this._attempts = new Map()
+
+    // Track error patterns
+    this._errorPatterns = new Map()
+
+    // Configuration
+    this.maxAttempts = 3
+    this.sessionTimeout = 5 * 60 * 1000 // 5 minutes
+  }
+
+  /**
+   * Generate a unique key for tracking attempts
+   */
+  private _getKey(command: string, context: string = ''): string {
+    return `${command}:${context}`.toLowerCase()
+  }
+
+  /**
+   * Record an attempt for a command
+   */
+  recordAttempt(command: string, context: string = '', result: AttemptResult = {}): AttemptInfo {
+    const key = this._getKey(command, context)
+    const now = Date.now()
+
+    // Get or create attempt record
+    let record = this._attempts.get(key)
+
+    if (!record || now - record.lastAttempt > this.sessionTimeout) {
+      // New session or timed out
+      record = {
+        command,
+        context,
+        attempts: 0,
+        errors: [],
+        firstAttempt: now,
+        lastAttempt: now,
+        success: false,
+      }
+    }
+
+    // Update record
+    record.attempts++
+    record.lastAttempt = now
+    record.success = result.success || false
+
+    if (result.error) {
+      record.errors.push({
+        message: result.error,
+        timestamp: now,
+      })
+    }
+
+    this._attempts.set(key, record)
+
+    return {
+      attemptNumber: record.attempts,
+      isLooping: this.isLooping(command, context),
+      shouldEscalate: this.shouldEscalate(command, context),
+    }
+  }
+
+  /**
+   * Check if a command is in a loop (repeated failures)
+   */
+  isLooping(command: string, context: string = ''): boolean {
+    const key = this._getKey(command, context)
+    const record = this._attempts.get(key)
+
+    if (!record) return false
+
+    // Check if multiple failures with same error
+    if (record.attempts >= 2 && !record.success) {
+      const recentErrors = record.errors.slice(-3)
+      if (recentErrors.length >= 2) {
+        // Check if errors are similar
+        const firstError = recentErrors[0]?.message || ''
+        const sameError = recentErrors.every((e) => isSimilarError(e.message, firstError))
+        return sameError
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * Check if we should escalate to user
+   */
+  shouldEscalate(command: string, context: string = ''): boolean {
+    const key = this._getKey(command, context)
+    const record = this._attempts.get(key)
+
+    if (!record) return false
+
+    // Escalate after max attempts without success
+    return record.attempts >= this.maxAttempts && !record.success
+  }
+
+  /**
+   * Get escalation message for user
+   */
+  getEscalationInfo(command: string, context: string = ''): EscalationInfo | null {
+    const key = this._getKey(command, context)
+    const record = this._attempts.get(key)
+
+    if (!record) {
+      return null
+    }
+
+    // Analyze error pattern
+    const errorPattern = analyzeErrorPattern(record.errors)
+
+    return {
+      status: 'BLOCKED',
+      command,
+      context,
+      attempts: record.attempts,
+      duration: record.lastAttempt - record.firstAttempt,
+      errorPattern,
+      message: generateEscalationMessage(command, errorPattern, this.maxAttempts),
+      suggestion: generateSuggestion(errorPattern),
+      lastError: record.errors[record.errors.length - 1]?.message || null,
+    }
+  }
+
+  /**
+   * Mark a command as successful (resets tracking)
+   */
+  recordSuccess(command: string, context: string = ''): void {
+    const key = this._getKey(command, context)
+    const record = this._attempts.get(key)
+
+    if (record) {
+      record.success = true
+      record.attempts = 0
+      record.errors = []
+      this._attempts.set(key, record)
+    }
+  }
+
+  /**
+   * Clear all tracking for a command
+   */
+  clearTracking(command: string, context: string = ''): void {
+    const key = this._getKey(command, context)
+    this._attempts.delete(key)
+  }
+
+  /**
+   * Clear all tracking data
+   */
+  clearAll(): void {
+    this._attempts.clear()
+    this._errorPatterns.clear()
+  }
+
+  /**
+   * Get statistics for debugging
+   */
+  getStats(): { activeTracking: number; commands: Record<string, unknown> } {
+    const stats: { activeTracking: number; commands: Record<string, unknown> } = {
+      activeTracking: this._attempts.size,
+      commands: {},
+    }
+
+    for (const [key, record] of this._attempts) {
+      stats.commands[key] = {
+        attempts: record.attempts,
+        success: record.success,
+        errorCount: record.errors.length,
+      }
+    }
+
+    return stats
+  }
+
+  /**
+   * ANTI-HALLUCINATION: Detect potential hallucination patterns in output
+   */
+  detectHallucination(output: string) {
+    return detectHallucination(output)
+  }
+
+  /**
+   * Analyze output and record if hallucination detected
+   */
+  analyzeOutput(command: string, output: string): OutputAnalysis {
+    const hallucination = this.detectHallucination(output)
+
+    if (hallucination.detected) {
+      // Record as a special type of error
+      this.recordAttempt(command, 'hallucination', {
+        success: false,
+        error: `HALLUCINATION: ${hallucination.description}`,
+      })
+
+      return {
+        ...hallucination,
+        shouldBlock: true,
+        action: 'VERIFY_STATE',
+      }
+    }
+
+    return { detected: false, shouldBlock: false }
+  }
+}

package/core/agentic/loop-detector/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Loop Detector Types
+ */
+
+export interface ErrorEntry {
+  message: string
+  timestamp: number
+}
+
+export interface AttemptRecord {
+  command: string
+  context: string
+  attempts: number
+  errors: ErrorEntry[]
+  firstAttempt: number
+  lastAttempt: number
+  success: boolean
+}
+
+export interface ErrorPattern {
+  type: string
+  description: string
+}
+
+export interface EscalationInfo {
+  status: string
+  command: string
+  context: string
+  attempts: number
+  duration: number
+  errorPattern: ErrorPattern
+  message: string
+  suggestion: string
+  lastError: string | null
+}
+
+export interface AttemptResult {
+  success?: boolean
+  error?: string
+}
+
+export interface AttemptInfo {
+  attemptNumber: number
+  isLooping: boolean
+  shouldEscalate: boolean
+}
+
+export interface HallucinationPattern {
+  pattern: RegExp
+  type: string
+  description: string
+}
+
+export interface HallucinationResult {
+  detected: boolean
+  type?: string
+  pattern?: string
+  description?: string
+  message?: string
+  suggestion?: string
+}
+
+export interface OutputAnalysis extends HallucinationResult {
+  shouldBlock: boolean
+  action?: string
+}

package/core/agentic/loop-detector.ts

@@ -0,0 +1,8 @@
+/**
+ * Loop Detection & User Escalation
+ * Re-exports from loop-detector/index.ts for backwards compatibility.
+ */
+
+import loopDetector from './loop-detector/index'
+export * from './loop-detector/index'
+export default loopDetector

package/core/agentic/memory-system/history.ts

@@ -0,0 +1,53 @@
+/**
+ * History - Tier 3
+ * Append-only JSONL audit log.
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import pathManager from '../../infrastructure/path-manager'
+import type { HistoryEntry } from './types'
+
+export class HistoryStore {
+  private _getSessionPath(projectId: string): string {
+    const now = new Date()
+    const yearMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`
+    const day = now.toISOString().split('T')[0]
+
+    return path.join(pathManager.getGlobalProjectPath(projectId), 'memory', 'sessions', yearMonth, `${day}.jsonl`)
+  }
+
+  async appendHistory(projectId: string, entry: Record<string, unknown>): Promise<void> {
+    const sessionPath = this._getSessionPath(projectId)
+    await fs.mkdir(path.dirname(sessionPath), { recursive: true })
+
+    const logEntry: HistoryEntry = {
+      ts: new Date().toISOString(),
+      type: entry.type as string,
+      ...entry,
+    }
+
+    await fs.appendFile(sessionPath, JSON.stringify(logEntry) + '\n', 'utf-8')
+  }
+
+  async getRecentHistory(projectId: string, limit: number = 20): Promise<HistoryEntry[]> {
+    try {
+      const sessionPath = this._getSessionPath(projectId)
+      const content = await fs.readFile(sessionPath, 'utf-8')
+      const lines = content.trim().split('\n').filter(Boolean)
+
+      return lines
+        .slice(-limit)
+        .map((line) => {
+          try {
+            return JSON.parse(line)
+          } catch {
+            return null
+          }
+        })
+        .filter((entry): entry is HistoryEntry => entry !== null)
+    } catch {
+      return []
+    }
+  }
+}

package/core/agentic/memory-system/index.ts

@@ -0,0 +1,192 @@
+/**
+ * Layered Memory System
+ * Three-tier memory for learning user patterns and preferences.
+ *
+ * @module agentic/memory-system
+ * @version 3.3
+ */
+
+import { SemanticMemories } from './semantic-memories'
+import { PatternStore } from './patterns'
+import { HistoryStore } from './history'
+import { SessionStore } from './session'
+import type { Memory, Context, Workflow } from './types'
+export { MEMORY_TAGS } from './types'
+
+/**
+ * Three-tier memory system for learning user patterns.
+ * Tier 1: Session (ephemeral), Tier 2: Patterns (persistent), Tier 3: History (JSONL)
+ */
+class MemorySystem {
+  private _semanticMemories: SemanticMemories
+  private _patternStore: PatternStore
+  private _historyStore: HistoryStore
+  private _sessionStore: SessionStore
+
+  constructor() {
+    this._semanticMemories = new SemanticMemories()
+    this._patternStore = new PatternStore()
+    this._historyStore = new HistoryStore()
+    this._sessionStore = new SessionStore()
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // P3.3: SEMANTIC MEMORIES
+  // ═══════════════════════════════════════════════════════════
+
+  loadMemories(projectId: string) {
+    return this._semanticMemories.loadMemories(projectId)
+  }
+
+  saveMemories(projectId: string) {
+    return this._semanticMemories.saveMemories(projectId)
+  }
+
+  createMemory(
+    projectId: string,
+    options: { title: string; content: string; tags?: string[]; userTriggered?: boolean }
+  ): Promise<string> {
+    return this._semanticMemories.createMemory(projectId, options)
+  }
+
+  updateMemory(
+    projectId: string,
+    memoryId: string,
+    updates: { title?: string; content?: string; tags?: string[] }
+  ): Promise<boolean> {
+    return this._semanticMemories.updateMemory(projectId, memoryId, updates)
+  }
+
+  deleteMemory(projectId: string, memoryId: string): Promise<boolean> {
+    return this._semanticMemories.deleteMemory(projectId, memoryId)
+  }
+
+  findByTags(projectId: string, tags: string[], matchAll?: boolean): Promise<Memory[]> {
+    return this._semanticMemories.findByTags(projectId, tags, matchAll)
+  }
+
+  searchMemories(projectId: string, query: string): Promise<Memory[]> {
+    return this._semanticMemories.searchMemories(projectId, query)
+  }
+
+  getRelevantMemories(projectId: string, context: Context, limit?: number): Promise<Memory[]> {
+    return this._semanticMemories.getRelevantMemories(projectId, context, limit)
+  }
+
+  autoRemember(projectId: string, decisionType: string, value: string, context?: string): Promise<void> {
+    return this._semanticMemories.autoRemember(projectId, decisionType, value, context)
+  }
+
+  getAllMemories(projectId: string): Promise<Memory[]> {
+    return this._semanticMemories.getAllMemories(projectId)
+  }
+
+  getMemoryStats(projectId: string) {
+    return this._semanticMemories.getMemoryStats(projectId)
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // TIER 1: Session Memory
+  // ═══════════════════════════════════════════════════════════
+
+  setSession(key: string, value: unknown): void {
+    this._sessionStore.setSession(key, value)
+  }
+
+  getSession(key: string): unknown {
+    return this._sessionStore.getSession(key)
+  }
+
+  clearSession(): void {
+    this._sessionStore.clearSession()
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // TIER 2: Patterns
+  // ═══════════════════════════════════════════════════════════
+
+  loadPatterns(projectId: string) {
+    return this._patternStore.loadPatterns(projectId)
+  }
+
+  savePatterns(projectId: string) {
+    return this._patternStore.savePatterns(projectId)
+  }
+
+  recordDecision(projectId: string, key: string, value: string, context?: string): Promise<void> {
+    return this._patternStore.recordDecision(projectId, key, value, context)
+  }
+
+  getDecision(projectId: string, key: string): Promise<{ value: string; confidence: string } | null> {
+    return this._patternStore.getDecision(projectId, key)
+  }
+
+  hasPattern(projectId: string, key: string): Promise<boolean> {
+    return this._patternStore.hasPattern(projectId, key)
+  }
+
+  recordWorkflow(projectId: string, workflowName: string, pattern: Record<string, unknown>): Promise<void> {
+    return this._patternStore.recordWorkflow(projectId, workflowName, pattern)
+  }
+
+  getWorkflow(projectId: string, workflowName: string): Promise<Workflow | null> {
+    return this._patternStore.getWorkflow(projectId, workflowName)
+  }
+
+  setPreference(projectId: string, key: string, value: unknown): Promise<void> {
+    return this._patternStore.setPreference(projectId, key, value)
+  }
+
+  getPreference(projectId: string, key: string, defaultValue?: unknown): Promise<unknown> {
+    return this._patternStore.getPreference(projectId, key, defaultValue)
+  }
+
+  getPatternsSummary(projectId: string) {
+    return this._patternStore.getPatternsSummary(projectId)
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // TIER 3: History
+  // ═══════════════════════════════════════════════════════════
+
+  appendHistory(projectId: string, entry: Record<string, unknown>): Promise<void> {
+    return this._historyStore.appendHistory(projectId, entry)
+  }
+
+  getRecentHistory(projectId: string, limit?: number) {
+    return this._historyStore.getRecentHistory(projectId, limit)
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // CONVENIENCE: Combined operations
+  // ═══════════════════════════════════════════════════════════
+
+  async getSmartDecision(projectId: string, key: string): Promise<string | null> {
+    const sessionValue = this.getSession(`decision:${key}`)
+    if (sessionValue !== undefined) return sessionValue as string
+
+    const pattern = await this.getDecision(projectId, key)
+    if (pattern) return pattern.value
+
+    return null
+  }
+
+  async learnDecision(projectId: string, key: string, value: string, context: string = ''): Promise<void> {
+    this.setSession(`decision:${key}`, value)
+    await this.recordDecision(projectId, key, value, context)
+    await this.appendHistory(projectId, { type: 'decision', key, value, context })
+  }
+
+  /**
+   * Reset internal state (for testing)
+   */
+  resetState(): void {
+    this._sessionStore.clearSession()
+    this._semanticMemories.reset()
+    this._patternStore.reset()
+  }
+}
+
+const memorySystem = new MemorySystem()
+export default memorySystem
+export { MemorySystem }

package/core/agentic/memory-system/patterns.ts

@@ -0,0 +1,156 @@
+/**
+ * Patterns - Tier 2
+ * Persistent learned preferences and decisions.
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import pathManager from '../../infrastructure/path-manager'
+import type { Patterns, Decision, Workflow } from './types'
+
+export class PatternStore {
+  private _patterns: Patterns | null = null
+  private _patternsLoaded: boolean = false
+
+  private _getPatternsPath(projectId: string): string {
+    return path.join(pathManager.getGlobalProjectPath(projectId), 'memory', 'patterns.json')
+  }
+
+  async loadPatterns(projectId: string): Promise<Patterns> {
+    if (this._patternsLoaded && this._patterns) {
+      return this._patterns
+    }
+
+    try {
+      const patternsPath = this._getPatternsPath(projectId)
+      const content = await fs.readFile(patternsPath, 'utf-8')
+      this._patterns = JSON.parse(content)
+      this._patternsLoaded = true
+      return this._patterns!
+    } catch {
+      this._patterns = {
+        version: 1,
+        decisions: {},
+        preferences: {},
+        workflows: {},
+        counters: {},
+      }
+      this._patternsLoaded = true
+      return this._patterns
+    }
+  }
+
+  async savePatterns(projectId: string): Promise<void> {
+    if (!this._patterns) return
+
+    const patternsPath = this._getPatternsPath(projectId)
+    await fs.mkdir(path.dirname(patternsPath), { recursive: true })
+    await fs.writeFile(patternsPath, JSON.stringify(this._patterns, null, 2), 'utf-8')
+  }
+
+  async recordDecision(projectId: string, key: string, value: string, context: string = ''): Promise<void> {
+    const patterns = await this.loadPatterns(projectId)
+
+    if (!patterns.decisions[key]) {
+      patterns.decisions[key] = {
+        value,
+        count: 1,
+        firstSeen: new Date().toISOString(),
+        lastSeen: new Date().toISOString(),
+        confidence: 'low',
+        contexts: [context].filter(Boolean),
+      }
+    } else {
+      const decision = patterns.decisions[key]
+
+      if (decision.value === value) {
+        decision.count++
+        decision.lastSeen = new Date().toISOString()
+        if (context && !decision.contexts.includes(context)) {
+          decision.contexts.push(context)
+        }
+
+        if (decision.count >= 5) {
+          decision.confidence = 'high'
+        } else if (decision.count >= 3) {
+          decision.confidence = 'medium'
+        }
+      } else {
+        decision.value = value
+        decision.count = 1
+        decision.lastSeen = new Date().toISOString()
+        decision.confidence = 'low'
+      }
+    }
+
+    await this.savePatterns(projectId)
+  }
+
+  async getDecision(projectId: string, key: string): Promise<{ value: string; confidence: string } | null> {
+    const patterns = await this.loadPatterns(projectId)
+    const decision = patterns.decisions[key]
+
+    if (!decision) return null
+    if (decision.confidence === 'low') return null
+
+    return { value: decision.value, confidence: decision.confidence }
+  }
+
+  async hasPattern(projectId: string, key: string): Promise<boolean> {
+    const decision = await this.getDecision(projectId, key)
+    return decision !== null
+  }
+
+  async recordWorkflow(projectId: string, workflowName: string, pattern: Record<string, unknown>): Promise<void> {
+    const patterns = await this.loadPatterns(projectId)
+
+    if (!patterns.workflows[workflowName]) {
+      patterns.workflows[workflowName] = {
+        ...pattern,
+        count: 1,
+        firstSeen: new Date().toISOString(),
+        lastSeen: new Date().toISOString(),
+      }
+    } else {
+      patterns.workflows[workflowName].count++
+      patterns.workflows[workflowName].lastSeen = new Date().toISOString()
+    }
+
+    await this.savePatterns(projectId)
+  }
+
+  async getWorkflow(projectId: string, workflowName: string): Promise<Workflow | null> {
+    const patterns = await this.loadPatterns(projectId)
+    const workflow = patterns.workflows[workflowName]
+
+    if (!workflow || workflow.count < 3) return null
+    return workflow
+  }
+
+  async setPreference(projectId: string, key: string, value: unknown): Promise<void> {
+    const patterns = await this.loadPatterns(projectId)
+    patterns.preferences[key] = { value, updatedAt: new Date().toISOString() }
+    await this.savePatterns(projectId)
+  }
+
+  async getPreference(projectId: string, key: string, defaultValue: unknown = null): Promise<unknown> {
+    const patterns = await this.loadPatterns(projectId)
+    return patterns.preferences[key]?.value ?? defaultValue
+  }
+
+  async getPatternsSummary(projectId: string) {
+    const patterns = await this.loadPatterns(projectId)
+
+    return {
+      decisions: Object.keys(patterns.decisions).length,
+      learnedDecisions: Object.values(patterns.decisions).filter((d) => d.confidence !== 'low').length,
+      workflows: Object.keys(patterns.workflows).length,
+      preferences: Object.keys(patterns.preferences).length,
+    }
+  }
+
+  reset(): void {
+    this._patterns = null
+    this._patternsLoaded = false
+  }
+}