@soleri/core 2.10.0 → 2.12.0

package/src/agency/agency-manager.ts

@@ -0,0 +1,326 @@
+/**
+ * Agency Manager — proactive file watching, pattern surfacing, and warning detection.
+ *
+ * Orchestrates:
+ * 1. File watcher (fs.watch with debouncing)
+ * 2. Warning detectors (pluggable, domain-agnostic)
+ * 3. Pattern surfacer (vault search on file changes)
+ * 4. Clarifier (generate questions for ambiguous intent)
+ *
+ * Feature-flagged: disabled by default, opt-in via agency_enable.
+ * Uses Node.js fs.watch — no dependencies.
+ */
+
+import { watch, readFileSync, existsSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import type { FSWatcher } from 'node:fs';
+import type { Vault } from '../vault/vault.js';
+import type {
+  AgencyConfig,
+  AgencyStatus,
+  FileChange,
+  FileChangeListener,
+  Warning,
+  WarningDetector,
+  SurfacedPattern,
+  ClarificationQuestion,
+} from './types.js';
+
+// ─── Defaults ──────────────────────────────────────────────────────
+
+const DEFAULT_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.css', '.json'];
+const DEFAULT_IGNORE = [
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  'coverage',
+  '.turbo',
+  '.cache',
+];
+const DEFAULT_DEBOUNCE_MS = 300;
+const DEFAULT_COOLDOWN_MS = 300_000; // 5 minutes
+const DEFAULT_MIN_CONFIDENCE = 0.5;
+
+// ─── Class ──────────────────────────────────────────────────────────
+
+export class AgencyManager {
+  private vault: Vault;
+  private config: Required<AgencyConfig>;
+  private watchers: FSWatcher[] = [];
+  private detectors: WarningDetector[] = [];
+  private changeListeners: FileChangeListener[] = [];
+  private pendingWarnings: Warning[] = [];
+  private surfacedPatterns: SurfacedPattern[] = [];
+  private changesProcessed = 0;
+  private cooldownMap = new Map<string, number>();
+  private debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(vault: Vault, config?: AgencyConfig) {
+    this.vault = vault;
+    this.config = {
+      enabled: config?.enabled ?? false,
+      watchPaths: config?.watchPaths ?? ['.'],
+      ignorePatterns: config?.ignorePatterns ?? DEFAULT_IGNORE,
+      extensions: config?.extensions ?? DEFAULT_EXTENSIONS,
+      debounceMs: config?.debounceMs ?? DEFAULT_DEBOUNCE_MS,
+      minPatternConfidence: config?.minPatternConfidence ?? DEFAULT_MIN_CONFIDENCE,
+      cooldownMs: config?.cooldownMs ?? DEFAULT_COOLDOWN_MS,
+    };
+  }
+
+  // ─── Lifecycle ──────────────────────────────────────────────────
+
+  enable(projectPath?: string): void {
+    if (this.config.enabled) return;
+    this.config.enabled = true;
+    if (projectPath) this.startWatching(projectPath);
+  }
+
+  disable(): void {
+    this.config.enabled = false;
+    this.stopWatching();
+  }
+
+  getStatus(): AgencyStatus {
+    return {
+      enabled: this.config.enabled,
+      watching: this.watchers.length > 0,
+      watchPaths: this.config.watchPaths,
+      detectorCount: this.detectors.length,
+      pendingWarnings: this.pendingWarnings.length,
+      surfacedPatterns: this.surfacedPatterns.length,
+      fileChangesProcessed: this.changesProcessed,
+    };
+  }
+
+  updateConfig(config: Partial<AgencyConfig>): void {
+    Object.assign(this.config, config);
+  }
+
+  // ─── File Watching ──────────────────────────────────────────────
+
+  startWatching(projectPath: string): void {
+    this.stopWatching();
+    for (const watchPath of this.config.watchPaths) {
+      const fullPath = join(projectPath, watchPath);
+      if (!existsSync(fullPath)) continue;
+
+      try {
+        const watcher = watch(fullPath, { recursive: true }, (_event, filename) => {
+          if (!filename) return;
+          const filePath = join(fullPath, filename);
+          if (this.shouldIgnore(filePath)) return;
+          if (!this.hasValidExtension(filePath)) return;
+          this.debounceChange(filePath);
+        });
+        this.watchers.push(watcher);
+      } catch {
+        // Directory may not support watching — skip
+      }
+    }
+  }
+
+  stopWatching(): void {
+    for (const w of this.watchers) w.close();
+    this.watchers = [];
+    for (const timer of this.debounceTimers.values()) clearTimeout(timer);
+    this.debounceTimers.clear();
+  }
+
+  onFileChange(listener: FileChangeListener): void {
+    this.changeListeners.push(listener);
+  }
+
+  // ─── Warning Detection ──────────────────────────────────────────
+
+  registerDetector(detector: WarningDetector): void {
+    this.detectors.push(detector);
+  }
+
+  scanFile(filePath: string): Warning[] {
+    if (!existsSync(filePath)) return [];
+
+    const ext = extname(filePath);
+    const applicableDetectors = this.detectors.filter((d) => d.extensions.includes(ext));
+    if (applicableDetectors.length === 0) return [];
+
+    let content: string;
+    try {
+      content = readFileSync(filePath, 'utf-8');
+    } catch {
+      return [];
+    }
+
+    const warnings: Warning[] = [];
+    for (const detector of applicableDetectors) {
+      try {
+        warnings.push(...detector.detect(filePath, content));
+      } catch {
+        // Detector failure is non-critical
+      }
+    }
+
+    this.pendingWarnings.push(...warnings);
+    return warnings;
+  }
+
+  getPendingWarnings(): Warning[] {
+    return [...this.pendingWarnings];
+  }
+
+  clearWarnings(): void {
+    this.pendingWarnings = [];
+  }
+
+  // ─── Pattern Surfacing ──────────────────────────────────────────
+
+  surfacePatterns(filePath: string): SurfacedPattern[] {
+    const now = Date.now();
+    const lastSurfaced = this.cooldownMap.get(filePath);
+    if (lastSurfaced && now - lastSurfaced < this.config.cooldownMs) return [];
+
+    const ext = extname(filePath);
+    const filename = filePath.split('/').pop() ?? '';
+
+    // Build search query from file context
+    const terms: string[] = [];
+    if (ext === '.ts' || ext === '.tsx') terms.push('typescript');
+    if (ext === '.css') terms.push('css', 'styling');
+    if (ext === '.json') terms.push('configuration');
+    if (filename.includes('test')) terms.push('testing');
+    if (filename.includes('component')) terms.push('component');
+
+    if (terms.length === 0) return [];
+
+    const query = terms.join(' ');
+    try {
+      const results = this.vault.search(query, { limit: 5 });
+      const patterns: SurfacedPattern[] = [];
+
+      for (const r of results) {
+        const relevance = r.score > 0 ? Math.min(1, r.score / (results[0]?.score || 1)) : 0;
+        if (relevance < this.config.minPatternConfidence) continue;
+
+        patterns.push({
+          entryId: r.entry.id,
+          title: r.entry.title,
+          domain: r.entry.domain,
+          relevance,
+          trigger: filePath,
+        });
+      }
+
+      if (patterns.length > 0) {
+        this.cooldownMap.set(filePath, now);
+        this.surfacedPatterns.push(...patterns);
+      }
+
+      return patterns;
+    } catch {
+      return [];
+    }
+  }
+
+  getSurfacedPatterns(): SurfacedPattern[] {
+    return [...this.surfacedPatterns];
+  }
+
+  clearSurfacedPatterns(): void {
+    this.surfacedPatterns = [];
+  }
+
+  // ─── Clarification ──────────────────────────────────────────────
+
+  generateClarification(prompt: string, confidence: number): ClarificationQuestion | null {
+    if (confidence >= 0.7) return null; // High confidence — no need to clarify
+
+    const words = prompt.toLowerCase().split(/\s+/);
+    const hasAction = words.some((w) =>
+      ['create', 'fix', 'build', 'add', 'remove', 'update', 'improve', 'deploy'].includes(w),
+    );
+    const hasTarget = words.length > 3;
+
+    if (!hasAction && !hasTarget) {
+      return {
+        question: 'Could you clarify what you would like me to do? I need an action and a target.',
+        reason: 'No clear action or target detected in the prompt.',
+        options: [
+          'Create something new',
+          'Fix an existing issue',
+          'Review or validate code',
+          'Explore the codebase',
+        ],
+      };
+    }
+
+    if (!hasAction) {
+      return {
+        question: 'What action would you like me to take?',
+        reason: 'The prompt describes a target but no clear action.',
+        options: ['Build', 'Fix', 'Review', 'Improve', 'Deploy'],
+      };
+    }
+
+    if (confidence < 0.3) {
+      return {
+        question: 'Could you provide more context about what you need?',
+        reason: 'The prompt is too brief to determine intent reliably.',
+      };
+    }
+
+    return null;
+  }
+
+  // ─── Private Helpers ────────────────────────────────────────────
+
+  private debounceChange(filePath: string): void {
+    const existing = this.debounceTimers.get(filePath);
+    if (existing) clearTimeout(existing);
+
+    this.debounceTimers.set(
+      filePath,
+      setTimeout(() => {
+        this.debounceTimers.delete(filePath);
+        this.processChange(filePath);
+      }, this.config.debounceMs),
+    );
+  }
+
+  private processChange(filePath: string): void {
+    this.changesProcessed++;
+
+    const change: FileChange = {
+      path: filePath,
+      type: existsSync(filePath) ? 'modify' : 'delete',
+      timestamp: Date.now(),
+    };
+
+    // Notify listeners
+    for (const listener of this.changeListeners) {
+      try {
+        listener(change);
+      } catch {
+        // Listener failure is non-critical
+      }
+    }
+
+    // Auto-scan for warnings if detectors are registered
+    if (this.detectors.length > 0 && change.type !== 'delete') {
+      this.scanFile(filePath);
+    }
+
+    // Auto-surface patterns
+    this.surfacePatterns(filePath);
+  }
+
+  private shouldIgnore(filePath: string): boolean {
+    return this.config.ignorePatterns.some((pattern) => filePath.includes(pattern));
+  }
+
+  private hasValidExtension(filePath: string): boolean {
+    const ext = extname(filePath);
+    return this.config.extensions.includes(ext);
+  }
+}

package/src/agency/index.ts

@@ -0,0 +1,13 @@
+export { AgencyManager } from './agency-manager.js';
+export type {
+  ChangeType,
+  FileChange,
+  FileChangeListener,
+  WarningSeverity,
+  Warning,
+  WarningDetector,
+  SurfacedPattern,
+  ClarificationQuestion,
+  AgencyConfig,
+  AgencyStatus,
+} from './types.js';

package/src/agency/types.ts

@@ -0,0 +1,88 @@
+/**
+ * Agency mode types — proactive file watching, pattern surfacing, warning detection.
+ */
+
+// ─── File Watching ──────────────────────────────────────────────────
+
+export type ChangeType = 'create' | 'modify' | 'delete';
+
+export interface FileChange {
+  path: string;
+  type: ChangeType;
+  timestamp: number;
+}
+
+export type FileChangeListener = (change: FileChange) => void;
+
+// ─── Warning Detection ──────────────────────────────────────────────
+
+export type WarningSeverity = 'critical' | 'warning' | 'info';
+
+export interface Warning {
+  id: string;
+  file: string;
+  line?: number;
+  severity: WarningSeverity;
+  category: string;
+  message: string;
+  suggestion?: string;
+}
+
+/**
+ * Pluggable warning detector. Agents define their own domain-specific detectors.
+ */
+export interface WarningDetector {
+  /** Unique name for this detector. */
+  name: string;
+  /** File extensions this detector applies to (e.g., ['.ts', '.tsx']). */
+  extensions: string[];
+  /** Detect warnings in file content. */
+  detect(filePath: string, content: string): Warning[];
+}
+
+// ─── Pattern Surfacing ──────────────────────────────────────────────
+
+export interface SurfacedPattern {
+  entryId: string;
+  title: string;
+  domain: string;
+  relevance: number;
+  trigger: string;
+}
+
+// ─── Clarification ──────────────────────────────────────────────────
+
+export interface ClarificationQuestion {
+  question: string;
+  reason: string;
+  options?: string[];
+}
+
+// ─── Agency Config ──────────────────────────────────────────────────
+
+export interface AgencyConfig {
+  /** Enable/disable agency mode. Default: false. */
+  enabled?: boolean;
+  /** Directories to watch (relative to project root). Default: ['.'] */
+  watchPaths?: string[];
+  /** Glob patterns to ignore. Default: common ignores. */
+  ignorePatterns?: string[];
+  /** File extensions to watch. Default: ['.ts', '.tsx', '.js', '.jsx', '.css', '.json'] */
+  extensions?: string[];
+  /** Debounce interval in ms for file change batching. Default: 300. */
+  debounceMs?: number;
+  /** Minimum confidence to surface a pattern. Default: 0.5. */
+  minPatternConfidence?: number;
+  /** Cooldown per file path (ms) before re-surfacing. Default: 300000 (5 min). */
+  cooldownMs?: number;
+}
+
+export interface AgencyStatus {
+  enabled: boolean;
+  watching: boolean;
+  watchPaths: string[];
+  detectorCount: number;
+  pendingWarnings: number;
+  surfacedPatterns: number;
+  fileChangesProcessed: number;
+}

package/src/brain/brain.ts

@@ -1,6 +1,7 @@
 import type { Vault } from '../vault/vault.js';
 import type { SearchResult } from '../vault/vault.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
+import { computeContentHash } from '../vault/content-hash.js';
 import {
   tokenize,
   calculateTf,
@@ -22,17 +23,6 @@ import type {
   FeedbackStats,
 } from './types.js';
 
-// Re-export types for backward compatibility
-export type {
-  ScoringWeights,
-  ScoreBreakdown,
-  RankedResult,
-  SearchOptions,
-  CaptureResult,
-  BrainStats,
-  QueryContext,
-} from './types.js';
-
 // ─── Severity scoring ──────────────────────────────────────────────
 
 const SEVERITY_SCORES: Record<string, number> = {
@@ -182,6 +172,7 @@ export class Brain {
 
     if (rawResults.length === 0) return [];
 
+    const seedCount = rawResults.length;
     const queryTokens = tokenize(query);
     const queryTags = options?.tags ?? [];
     const queryDomain = options?.domain;
@@ -207,6 +198,17 @@ export class Brain {
     });
 
     ranked.sort((a, b) => b.score - a.score);
+
+    // Small corpus guard: when the FTS seed is small (< 50 entries), TF-IDF scoring
+    // becomes too aggressive and filters out relevant results. If filtering to `limit`
+    // would discard more than half the seed, return all seed results sorted by score.
+    if (seedCount < 50 && limit < seedCount && ranked.length > limit) {
+      const wouldKeep = limit;
+      if (wouldKeep < seedCount / 2) {
+        return ranked.slice(0, seedCount);
+      }
+    }
+
     return ranked.slice(0, limit);
   }
 
@@ -248,8 +250,22 @@ export class Brain {
       why: entry.why,
       tags: mergedTags,
       appliesTo: entry.appliesTo,
+      tier: entry.tier,
     };
 
+    // Content-hash dedup: check after enrichment so tags match the stored hash
+    const contentHash = computeContentHash(fullEntry);
+    const existingByHash = this.vault.findByContentHash(contentHash);
+    if (existingByHash && existingByHash !== entry.id) {
+      return {
+        captured: false,
+        id: entry.id,
+        autoTags,
+        duplicate: { id: existingByHash, similarity: 1.0 },
+        blocked: true,
+      };
+    }
+
     this.vault.add(fullEntry);
     this.updateVocabularyIncremental(fullEntry);
 

package/src/brain/intelligence.ts

@@ -15,6 +15,9 @@ import type {
   StrengthsQuery,
   BrainSession,
   SessionLifecycleInput,
+  SessionListQuery,
+  SessionQuality,
+  SessionReplay,
   KnowledgeProposal,
   ExtractionResult,
   GlobalPattern,
@@ -240,6 +243,106 @@ export class BrainIntelligence {
     return { archived: result.changes };
   }
 
+  // ─── Session Query & Quality ─────────────────────────────────────
+
+  getSessionById(id: string): BrainSession | null {
+    return this.getSession(id);
+  }
+
+  listSessions(query?: SessionListQuery): BrainSession[] {
+    const conditions: string[] = [];
+    const values: unknown[] = [];
+
+    if (query?.domain) {
+      conditions.push('domain = ?');
+      values.push(query.domain);
+    }
+    if (query?.active === true) {
+      conditions.push('ended_at IS NULL');
+    } else if (query?.active === false) {
+      conditions.push('ended_at IS NOT NULL');
+    }
+    if (query?.extracted === true) {
+      conditions.push('extracted_at IS NOT NULL');
+    } else if (query?.extracted === false) {
+      conditions.push('extracted_at IS NULL');
+    }
+
+    const where = conditions.length > 0 ? 'WHERE ' + conditions.join(' AND ') : '';
+    const limit = query?.limit ?? 50;
+    const offset = query?.offset ?? 0;
+    values.push(limit, offset);
+
+    const rows = this.provider.all<{
+      id: string;
+      started_at: string;
+      ended_at: string | null;
+      domain: string | null;
+      context: string | null;
+      tools_used: string;
+      files_modified: string;
+      plan_id: string | null;
+      plan_outcome: string | null;
+      extracted_at: string | null;
+    }>(`SELECT * FROM brain_sessions ${where} ORDER BY started_at DESC LIMIT ? OFFSET ?`, values);
+
+    return rows.map((r) => this.rowToSession(r));
+  }
+
+  computeSessionQuality(sessionId: string): SessionQuality {
+    const session = this.getSession(sessionId);
+    if (!session) throw new Error('Session not found: ' + sessionId);
+
+    // Completeness (0-25): session ended + has context + has domain
+    let completeness = 0;
+    if (session.endedAt) completeness += 10;
+    if (session.context) completeness += 8;
+    if (session.domain) completeness += 7;
+
+    // Artifact density (0-25): files modified
+    const fileCount = session.filesModified.length;
+    const artifactDensity = Math.min(25, fileCount * 5);
+
+    // Tool engagement (0-25): unique tools used
+    const uniqueTools = new Set(session.toolsUsed).size;
+    const toolEngagement = Math.min(25, uniqueTools * 5);
+
+    // Outcome clarity (0-25): plan outcome + extraction status
+    let outcomeClarity = 0;
+    if (session.planId) outcomeClarity += 8;
+    if (session.planOutcome === 'completed') outcomeClarity += 10;
+    else if (session.planOutcome === 'abandoned') outcomeClarity += 5;
+    else if (session.planOutcome) outcomeClarity += 7;
+    if (session.extractedAt) outcomeClarity += 7;
+
+    const overall = completeness + artifactDensity + toolEngagement + outcomeClarity;
+
+    return {
+      sessionId,
+      overall,
+      completeness,
+      artifactDensity,
+      toolEngagement,
+      outcomeClarity,
+    };
+  }
+
+  replaySession(sessionId: string): SessionReplay {
+    const session = this.getSession(sessionId);
+    if (!session) throw new Error('Session not found: ' + sessionId);
+
+    const quality = this.computeSessionQuality(sessionId);
+    const proposals = this.getProposals({ sessionId });
+
+    let durationMinutes: number | null = null;
+    if (session.startedAt && session.endedAt) {
+      const ms = new Date(session.endedAt).getTime() - new Date(session.startedAt).getTime();
+      durationMinutes = Math.round(ms / 60000);
+    }
+
+    return { session, quality, proposals, durationMinutes };
+  }
+
   // ─── Strength Scoring ─────────────────────────────────────────────
 
   computeStrengths(): PatternStrength[] {

package/src/brain/types.ts

@@ -212,3 +212,29 @@ export interface BrainImportResult {
     domainProfiles: number;
   };
 }
+
+// ─── Session Management Types ─────────────────────────────────────
+
+export interface SessionListQuery {
+  domain?: string;
+  active?: boolean;
+  extracted?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export interface SessionQuality {
+  sessionId: string;
+  overall: number;
+  completeness: number;
+  artifactDensity: number;
+  toolEngagement: number;
+  outcomeClarity: number;
+}
+
+export interface SessionReplay {
+  session: BrainSession;
+  quality: SessionQuality;
+  proposals: KnowledgeProposal[];
+  durationMinutes: number | null;
+}