@miphamai/cli 0.32.6 → 0.33.0

package/src/core/error-signature-db.ts

@@ -0,0 +1,324 @@
+/**
+ * SIS (Self-Immune System) Phase 0: Error Signature Database
+ *
+ * Persistent storage for known error patterns. Each signature captures:
+ *   - What error occurred (pattern matching against command/error text)
+ *   - How to fix it (strategy + action)
+ *   - How reliable the fix is (success rate tracking)
+ *
+ * Storage: JSON file at ~/.mipham/sis/error-signatures.json
+ * Pattern: follows EffectivenessTracker's file-based persistence model
+ *
+ * Integration:
+ *   AutoMemoryEngine.feedCrsiPipeline() → ErrorSignatureDB.insert()
+ *   PreFlightChecker.check() → ErrorSignatureDB.match()
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { randomUUID } from 'node:crypto'
+
+// ── Types ──
+
+export interface ErrorSignature {
+  /** Unique identifier */
+  id: string
+  /** Substring or regex pattern to match against command/error text */
+  pattern: string
+  /** Failure category: timeout | tool-params | import | search | semantic */
+  category: string
+  /** Associated tool name (e.g. 'Bash', 'Write') */
+  toolName: string
+  /** How to fix: replace params, prepend to command, append, warn only, or block entirely */
+  fixStrategy: 'replace' | 'prepend' | 'append' | 'warn' | 'block'
+  /** The fix action (e.g. 'pnpm install' replaces 'npm install') */
+  fixAction: string
+  /** Human-readable explanation of the fix */
+  explanation: string
+  /** Number of times this error has been encountered */
+  occurrences: number
+  /** Number of times the fix was applied successfully */
+  successCount: number
+  /** ISO timestamp of first encounter */
+  firstSeen: string
+  /** ISO timestamp of most recent encounter */
+  lastSeen: string
+  /** Fix success rate (0.0-1.0) */
+  successRate: number
+  /** Current status */
+  status: 'active' | 'degraded' | 'retired'
+}
+
+export interface ErrorSignatureStats {
+  total: number
+  active: number
+  degraded: number
+  retired: number
+  avgSuccessRate: number
+  totalInterceptions: number
+}
+
+// ── Constants ──
+
+const DEFAULT_STORE_DIR = join(homedir(), '.mipham', 'sis')
+const STORE_FILE = 'error-signatures.json'
+const MIN_SUCCESS_RATE = 0.5 // below this → degraded
+const RETIREMENT_RATE = 0.2 // below this and > 90 days old → retired
+const RETENTION_DAYS = 90 // auto-clean retired signatures older than this
+
+// ── Database ──
+
+export class ErrorSignatureDB {
+  private signatures: Map<string, ErrorSignature> = new Map()
+  private storePath: string
+  private dirty = false
+
+  constructor(storeDir: string = DEFAULT_STORE_DIR) {
+    this.storePath = join(storeDir, STORE_FILE)
+    this.load()
+  }
+
+  // ── Persistence ──
+
+  /** Load signatures from disk. Non-existent file = clean slate. */
+  private load(): void {
+    try {
+      if (!existsSync(this.storePath)) return
+      const raw = readFileSync(this.storePath, 'utf-8')
+      const arr: ErrorSignature[] = JSON.parse(raw)
+      for (const sig of arr) {
+        this.signatures.set(sig.id, sig)
+      }
+    } catch {
+      // Corrupted or missing file — start fresh
+    }
+  }
+
+  /** Persist signatures to disk. Debounced: only writes if dirty. */
+  private save(): void {
+    if (!this.dirty) return
+    try {
+      mkdirSync(join(this.storePath, '..'), { recursive: true })
+      const arr = Array.from(this.signatures.values())
+      writeFileSync(this.storePath, JSON.stringify(arr, null, 2), 'utf-8')
+      this.dirty = false
+    } catch {
+      // Best-effort persistence — never crash on write failure
+    }
+  }
+
+  // ── CRUD ──
+
+  /**
+   * Insert a new error signature. If a signature with the same pattern +
+   * toolName + category already exists, increment its occurrence count instead.
+   */
+  insert(
+    sig: Omit<
+      ErrorSignature,
+      'id' | 'occurrences' | 'successCount' | 'successRate' | 'firstSeen' | 'lastSeen' | 'status'
+    >,
+  ): ErrorSignature {
+    // Dedup: same pattern + toolName + category → update existing
+    const existing = this.findByPattern(sig.pattern, sig.toolName, sig.category)
+    if (existing) {
+      existing.occurrences++
+      existing.lastSeen = new Date().toISOString()
+      existing.successRate =
+        existing.occurrences > 0 ? existing.successCount / existing.occurrences : 1.0
+      this.dirty = true
+      this.save()
+      return existing
+    }
+
+    const now = new Date().toISOString()
+    const id = `sis-${randomUUID().slice(0, 8)}`
+    const full: ErrorSignature = {
+      ...sig,
+      id,
+      occurrences: 1,
+      successCount: 0,
+      successRate: 0, // starts at 0 — must prove itself before auto-apply
+      firstSeen: now,
+      lastSeen: now,
+      status: 'active',
+    }
+
+    this.signatures.set(id, full)
+    this.dirty = true
+    this.save()
+    return full
+  }
+
+  /**
+   * Match a tool call against known error signatures.
+   * Returns the best-matching active signature, or null if no match.
+   *
+   * Matching strategy:
+   *   1. Exact toolName match
+   *   2. Pattern substring match in command/error text
+   *   3. Category match as tiebreaker
+   */
+  match(toolName: string, params: Record<string, unknown>): ErrorSignature | null {
+    const text = this.paramsToText(toolName, params)
+    let best: ErrorSignature | null = null
+    let bestScore = 0
+
+    for (const sig of this.signatures.values()) {
+      if (sig.status === 'retired') continue
+      if (sig.toolName !== toolName) continue
+
+      // Pattern must match — this is the primary filter
+      if (!text.toLowerCase().includes(sig.pattern.toLowerCase())) continue
+
+      // Score tiebreakers when multiple signatures match
+      let score = 10 // base score for pattern match
+      score += sig.successRate * 5
+      score += Math.min(sig.occurrences / 10, 1) * 2
+      if (sig.status === 'active') score += 1
+
+      if (score > bestScore) {
+        bestScore = score
+        best = sig
+      }
+    }
+
+    return best
+  }
+
+  /**
+   * Record the result of applying a fix for a given signature.
+   * Updates success rate and may auto-degrade/retire low-performing signatures.
+   */
+  recordResult(id: string, success: boolean): void {
+    const sig = this.signatures.get(id)
+    if (!sig) return
+
+    if (success) {
+      sig.successCount++
+    }
+    sig.successRate = sig.occurrences > 0 ? sig.successCount / sig.occurrences : 1.0
+
+    // Auto-degrade
+    if (sig.successRate < MIN_SUCCESS_RATE && sig.status === 'active') {
+      sig.status = 'degraded'
+    }
+    // Auto-retire
+    const ageDays = (Date.now() - new Date(sig.firstSeen).getTime()) / (1000 * 60 * 60 * 24)
+    if (sig.successRate < RETIREMENT_RATE && ageDays > 90 && sig.status === 'degraded') {
+      sig.status = 'retired'
+    }
+
+    this.dirty = true
+    this.save()
+  }
+
+  // ── Query ──
+
+  /** Get all active and degraded signatures (excludes retired). */
+  getActive(): ErrorSignature[] {
+    return Array.from(this.signatures.values())
+      .filter((s) => s.status !== 'retired')
+      .sort((a, b) => b.occurrences - a.occurrences)
+  }
+
+  /** Get a specific signature by ID. */
+  get(id: string): ErrorSignature | undefined {
+    return this.signatures.get(id)
+  }
+
+  /** Manually retire a signature. */
+  retire(id: string): boolean {
+    const sig = this.signatures.get(id)
+    if (!sig) return false
+    sig.status = 'retired'
+    this.dirty = true
+    this.save()
+    return true
+  }
+
+  /** Get aggregate statistics. */
+  getStats(): ErrorSignatureStats {
+    const all = Array.from(this.signatures.values())
+    const active = all.filter((s) => s.status === 'active')
+    const degraded = all.filter((s) => s.status === 'degraded')
+    const retired = all.filter((s) => s.status === 'retired')
+
+    const avgSuccessRate =
+      active.length > 0 ? active.reduce((sum, s) => sum + s.successRate, 0) / active.length : 0
+
+    return {
+      total: all.length,
+      active: active.length,
+      degraded: degraded.length,
+      retired: retired.length,
+      avgSuccessRate: Math.round(avgSuccessRate * 100) / 100,
+      totalInterceptions: all.reduce((sum, s) => sum + s.occurrences, 0),
+    }
+  }
+
+  /**
+   * Clean up old retired signatures and low-performing degraded ones.
+   * Called periodically (e.g. on daemon startup or via /sis cleanup).
+   */
+  cleanup(retentionDays: number = RETENTION_DAYS): number {
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000
+    let removed = 0
+
+    for (const [id, sig] of this.signatures) {
+      if (sig.status === 'retired' && new Date(sig.lastSeen).getTime() < cutoff) {
+        this.signatures.delete(id)
+        removed++
+      }
+    }
+
+    if (removed > 0) {
+      this.dirty = true
+      this.save()
+    }
+
+    return removed
+  }
+
+  /** Clear all signatures. Used for testing and manual reset. */
+  clear(): void {
+    this.signatures.clear()
+    this.dirty = true
+    this.save()
+  }
+
+  // ── Private Helpers ──
+
+  /** Find an existing signature by pattern + toolName + category. */
+  private findByPattern(
+    pattern: string,
+    toolName: string,
+    category: string,
+  ): ErrorSignature | undefined {
+    for (const sig of this.signatures.values()) {
+      if (sig.pattern === pattern && sig.toolName === toolName && sig.category === category) {
+        return sig
+      }
+    }
+    return undefined
+  }
+
+  /** Convert tool params to a searchable text blob for pattern matching. */
+  private paramsToText(toolName: string, params: Record<string, unknown>): string {
+    const parts: string[] = [toolName]
+    if (params.command && typeof params.command === 'string') {
+      parts.push(params.command)
+    }
+    if (params.file_path && typeof params.file_path === 'string') {
+      parts.push(params.file_path)
+    }
+    if (params.description && typeof params.description === 'string') {
+      parts.push(params.description)
+    }
+    if (params.error && typeof params.error === 'string') {
+      parts.push(params.error)
+    }
+    return parts.join(' ')
+  }
+}

package/src/core/immune-memory-gc.ts

@@ -0,0 +1,187 @@
+/**
+ * SIS Phase 2: Immune Memory Garbage Collection
+ *
+ * Periodic cleanup of the error signature database:
+ *   - Removes retired signatures older than retention period
+ *   - Merges near-duplicate signatures (same tool + category, similar pattern)
+ *   - Auto-retires signatures with consistently zero success rate
+ *
+ * Designed to be called:
+ *   - On daemon startup
+ *   - Periodically (e.g. every 24h via ScheduleManager)
+ *   - Manually via `/sis cleanup`
+ */
+
+import type { ErrorSignatureDB, ErrorSignature } from './error-signature-db.js'
+
+// ── Constants ──
+
+/** Default retention period for retired signatures (days) */
+const DEFAULT_RETENTION_DAYS = 90
+
+/** Signatures with this many occurrences and 0 successes → auto-retire */
+const ZERO_SUCCESS_THRESHOLD = 10
+
+/** Levenshtein distance threshold for near-duplicate detection */
+const SIMILARITY_THRESHOLD = 0.8
+
+// ── Types ──
+
+export interface GCReport {
+  /** Number of retired signatures removed */
+  retiredRemoved: number
+  /** Number of zero-success signatures auto-retired */
+  zeroSuccessRetired: number
+  /** Number of near-duplicate signatures merged */
+  duplicatesMerged: number
+  /** Total signatures before cleanup */
+  before: number
+  /** Total signatures after cleanup */
+  after: number
+}
+
+// ── GC Engine ──
+
+export class ImmuneMemoryGC {
+  private errorDB: ErrorSignatureDB
+
+  constructor(errorDB: ErrorSignatureDB) {
+    this.errorDB = errorDB
+  }
+
+  /**
+   * Run a full garbage collection cycle.
+   *
+   * @param retentionDays — days to retain retired signatures (default 90)
+   * @returns GCReport with cleanup statistics
+   */
+  collect(retentionDays: number = DEFAULT_RETENTION_DAYS): GCReport {
+    const before = this.errorDB.getStats().total
+
+    // Phase 1: Remove old retired signatures
+    const retiredRemoved = this.errorDB.cleanup(retentionDays)
+
+    // Phase 2: Auto-retire zero-success signatures
+    const zeroSuccessRetired = this.retireZeroSuccess()
+
+    // Phase 3: Merge near-duplicates
+    const duplicatesMerged = this.mergeDuplicates()
+
+    const after = this.errorDB.getStats().total
+
+    return {
+      retiredRemoved,
+      zeroSuccessRetired,
+      duplicatesMerged,
+      before,
+      after,
+    }
+  }
+
+  // ── Private ──
+
+  /**
+   * Auto-retire signatures that have been tried many times
+   * but never succeeded. These are likely bad or outdated fixes.
+   */
+  private retireZeroSuccess(): number {
+    let count = 0
+    const active = this.errorDB.getActive()
+
+    for (const sig of active) {
+      if (
+        sig.occurrences >= ZERO_SUCCESS_THRESHOLD &&
+        sig.successCount === 0 &&
+        sig.status === 'active'
+      ) {
+        this.errorDB.retire(sig.id)
+        count++
+      }
+    }
+
+    return count
+  }
+
+  /**
+   * Merge near-duplicate signatures.
+   * Two signatures are duplicates if they share the same toolName + category
+   * and their patterns are textually similar (high substring overlap).
+   *
+   * The older signature absorbs the newer one's occurrence count.
+   */
+  private mergeDuplicates(): number {
+    let count = 0
+    const active = this.errorDB.getActive()
+    const merged = new Set<string>()
+
+    for (let i = 0; i < active.length; i++) {
+      const sigI = active[i]!
+      if (merged.has(sigI.id)) continue
+
+      for (let j = i + 1; j < active.length; j++) {
+        const sigJ = active[j]!
+        if (merged.has(sigJ.id)) continue
+
+        if (this.areSimilar(sigI, sigJ)) {
+          // Merge j into i (keep the older, more established one)
+          this.merge(sigI, sigJ)
+          merged.add(sigJ.id)
+          count++
+        }
+      }
+    }
+
+    return count
+  }
+
+  /** Check if two signatures are similar enough to be merged. */
+  private areSimilar(a: ErrorSignature, b: ErrorSignature): boolean {
+    // Must share toolName and category
+    if (a.toolName !== b.toolName) return false
+    if (a.category !== b.category) return false
+
+    // Check pattern similarity via substring containment
+    const shorter = a.pattern.length < b.pattern.length ? a.pattern : b.pattern
+    const longer = a.pattern.length < b.pattern.length ? b.pattern : a.pattern
+
+    if (longer.includes(shorter)) return true
+
+    // Check Levenshtein-like similarity
+    const similarity = this.jaccardSimilarity(shorter, longer)
+    return similarity >= SIMILARITY_THRESHOLD
+  }
+
+  /** Jaccard similarity on word tokens (simple and fast). */
+  private jaccardSimilarity(a: string, b: string): number {
+    const tokensA = new Set(a.toLowerCase().split(/\s+/))
+    const tokensB = new Set(b.toLowerCase().split(/\s+/))
+
+    let intersection = 0
+    for (const t of tokensA) {
+      if (tokensB.has(t)) intersection++
+    }
+
+    const union = tokensA.size + tokensB.size - intersection
+    return union > 0 ? intersection / union : 0
+  }
+
+  /** Merge signature `from` into `to`. Retire `from`. */
+  private merge(to: ErrorSignature, from: ErrorSignature): void {
+    // Transfer occurrences
+    to.occurrences += from.occurrences
+    to.successCount += from.successCount
+    to.successRate = to.occurrences > 0 ? to.successCount / to.occurrences : 1.0
+
+    // Keep the earlier firstSeen
+    if (from.firstSeen < to.firstSeen) {
+      to.firstSeen = from.firstSeen
+    }
+    // Keep the later lastSeen
+    if (from.lastSeen > to.lastSeen) {
+      to.lastSeen = from.lastSeen
+    }
+
+    // Retire the absorbed signature
+    this.errorDB.retire(from.id)
+  }
+}

package/src/core/instructions.ts

@@ -139,6 +139,20 @@ When a workflow completes successfully, offer to save it:
 Script format: export const meta = { name, description, phases: [...] }
 // script body using primitives...`)
 
+    // Inject code search conventions — prefer dedicated tools over raw Bash
+    parts.push(`## Code Search Conventions
+
+- Prefer the **Grep** tool for file-content search — it runs ripgrep (rg),
+  10× faster than grep, with automatic fallback to grep if rg is unavailable
+- Use the **Glob** tool to find files by name pattern, then Grep to search
+  their contents — narrow scope before full-text search
+- Use **Bash** with grep/rg/find ONLY for complex multi-step pipelines
+  (e.g., pipe to sort | uniq -c | sort -rn, or chained find + xargs)
+- Grep tool handles rg→grep fallback automatically; no need to
+  pre-check for rg availability or manually fall back
+- When you need to search AND read results: Glob → Grep → Read
+  (find files, search contents, then read the matching files)`)
+
     return parts.join('\n\n---\n\n')
   }