@soleri/core 2.1.0 → 2.5.0

package/src/control/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Types for Identity Management and Intent Routing.
+ *
+ * Two separate concerns:
+ * - Identity: agent persona CRUD with versioning and guidelines
+ * - Intent Routing: keyword-based intent classification and operational modes
+ */
+
+// ─── Identity Types ──────────────────────────────────────────────────
+
+export type GuidelineCategory = 'behavior' | 'preference' | 'restriction' | 'style';
+
+export interface Guideline {
+  id: string;
+  category: GuidelineCategory;
+  text: string;
+  priority: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AgentIdentity {
+  agentId: string;
+  name: string;
+  role: string;
+  description: string;
+  personality: string[];
+  guidelines: Guideline[];
+  version: number;
+  updatedAt: string;
+}
+
+export interface IdentityVersion {
+  version: number;
+  snapshot: string;
+  changedBy: string;
+  changeReason: string;
+  createdAt: string;
+}
+
+export interface IdentityUpdateInput {
+  name?: string;
+  role?: string;
+  description?: string;
+  personality?: string[];
+  changedBy?: string;
+  changeReason?: string;
+}
+
+export interface GuidelineInput {
+  category: GuidelineCategory;
+  text: string;
+  priority?: number;
+}
+
+// ─── Intent Routing Types ────────────────────────────────────────────
+
+export type IntentType =
+  | 'build'
+  | 'fix'
+  | 'validate'
+  | 'design'
+  | 'improve'
+  | 'deliver'
+  | 'explore'
+  | 'plan'
+  | 'review'
+  | 'general';
+
+export type OperationalMode =
+  | 'BUILD-MODE'
+  | 'FIX-MODE'
+  | 'VALIDATE-MODE'
+  | 'DESIGN-MODE'
+  | 'IMPROVE-MODE'
+  | 'DELIVER-MODE'
+  | 'EXPLORE-MODE'
+  | 'PLAN-MODE'
+  | 'REVIEW-MODE'
+  | 'GENERAL-MODE';
+
+export interface IntentClassification {
+  intent: IntentType;
+  mode: OperationalMode;
+  confidence: number;
+  method: 'keyword';
+  matchedKeywords: string[];
+}
+
+export interface ModeConfig {
+  mode: OperationalMode;
+  intent: IntentType;
+  description: string;
+  behaviorRules: string[];
+  keywords: string[];
+}
+
+export interface MorphResult {
+  previousMode: OperationalMode;
+  currentMode: OperationalMode;
+  behaviorRules: string[];
+}

package/src/curator/curator.ts

@@ -1,5 +1,6 @@
 import type { Vault } from '../vault/vault.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
+import type { CogneeClient } from '../cognee/client.js';
 import {
   tokenize,
   calculateTfIdf,
@@ -49,9 +50,11 @@ const DEFAULT_TAG_ALIASES: Array<[string, string]> = [
 
 export class Curator {
   private vault: Vault;
+  private cognee: CogneeClient | undefined;
 
-  constructor(vault: Vault) {
+  constructor(vault: Vault, cognee?: CogneeClient) {
     this.vault = vault;
+    this.cognee = cognee;
     this.initializeTables();
     this.seedDefaultAliases();
   }
@@ -93,6 +96,15 @@ export class Curator {
         created_at INTEGER NOT NULL DEFAULT (unixepoch())
       );
 
+      CREATE TABLE IF NOT EXISTS curator_entry_history (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        entry_id TEXT NOT NULL,
+        snapshot TEXT NOT NULL,
+        changed_by TEXT DEFAULT 'system',
+        change_reason TEXT,
+        created_at INTEGER NOT NULL DEFAULT (unixepoch())
+      );
+
       CREATE TABLE IF NOT EXISTS curator_contradictions (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         pattern_id TEXT NOT NULL,
@@ -369,6 +381,85 @@ export class Curator {
     return row ? this.rowToContradiction(row) : null;
   }
 
+  async detectContradictionsHybrid(threshold?: number): Promise<{
+    contradictions: Contradiction[];
+    cogneeAvailable: boolean;
+    method: 'hybrid' | 'tfidf-only';
+  }> {
+    const effectiveThreshold = threshold ?? DEFAULT_CONTRADICTION_THRESHOLD;
+    const entries = this.vault.list({ limit: 100000 });
+    const antipatterns = entries.filter((e) => e.type === 'anti-pattern');
+    const patterns = entries.filter((e) => e.type === 'pattern');
+
+    if (antipatterns.length === 0 || patterns.length === 0) {
+      return { contradictions: [], cogneeAvailable: false, method: 'tfidf-only' };
+    }
+
+    const vocabulary = this.buildVocabulary(entries);
+    const db = this.vault.getDb();
+    const detected: Contradiction[] = [];
+
+    const insertStmt = db.prepare(
+      `INSERT OR IGNORE INTO curator_contradictions (pattern_id, antipattern_id, similarity)
+       VALUES (?, ?, ?)`,
+    );
+
+    const cogneeAvailable = this.cognee?.isAvailable ?? false;
+
+    for (const ap of antipatterns) {
+      let candidates: IntelligenceEntry[];
+      try {
+        const searchResults = this.vault.search(ap.title, { type: 'pattern', limit: 20 });
+        candidates = searchResults.length > 0 ? searchResults.map((r) => r.entry) : patterns;
+      } catch {
+        candidates = patterns;
+      }
+
+      const apText = [ap.title, ap.description, ap.context ?? ''].join(' ');
+      const apVec = calculateTfIdf(tokenize(apText), vocabulary);
+
+      for (const pattern of candidates) {
+        const pText = [pattern.title, pattern.description, pattern.context ?? ''].join(' ');
+        const pVec = calculateTfIdf(tokenize(pText), vocabulary);
+        const tfidfScore = cosineSimilarity(apVec, pVec);
+
+        let finalScore = tfidfScore;
+        if (cogneeAvailable && this.cognee) {
+          try {
+            const cogneeResults = await this.cognee.search(`${ap.title} ${pattern.title}`, {
+              limit: 5,
+            });
+            const cogneeScore =
+              cogneeResults.length > 0
+                ? cogneeResults.reduce((sum, r) => sum + r.score, 0) / cogneeResults.length
+                : 0;
+            finalScore = 0.6 * tfidfScore + 0.4 * cogneeScore;
+          } catch {
+            finalScore = tfidfScore;
+          }
+        }
+
+        if (finalScore >= effectiveThreshold) {
+          const result = insertStmt.run(pattern.id, ap.id, finalScore);
+          if (result.changes > 0) {
+            const row = db
+              .prepare(
+                'SELECT * FROM curator_contradictions WHERE pattern_id = ? AND antipattern_id = ?',
+              )
+              .get(pattern.id, ap.id) as Record<string, unknown>;
+            detected.push(this.rowToContradiction(row));
+          }
+        }
+      }
+    }
+
+    return {
+      contradictions: detected,
+      cogneeAvailable,
+      method: cogneeAvailable ? 'hybrid' : 'tfidf-only',
+    };
+  }
+
   // ─── Grooming ───────────────────────────────────────────────────
 
   groomEntry(entryId: string): GroomResult | null {
@@ -638,6 +729,209 @@ export class Curator {
     };
   }
 
+  // ─── Entry History (Version Snapshots) ─────────────────────────
+
+  recordSnapshot(
+    entryId: string,
+    changedBy?: string,
+    changeReason?: string,
+  ): { recorded: boolean; historyId: number } {
+    const entry = this.vault.get(entryId);
+    if (!entry) return { recorded: false, historyId: -1 };
+
+    const db = this.vault.getDb();
+    const result = db
+      .prepare(
+        'INSERT INTO curator_entry_history (entry_id, snapshot, changed_by, change_reason, created_at) VALUES (?, ?, ?, ?, unixepoch())',
+      )
+      .run(entryId, JSON.stringify(entry), changedBy ?? 'system', changeReason ?? null);
+
+    return { recorded: true, historyId: Number(result.lastInsertRowid) };
+  }
+
+  getVersionHistory(entryId: string): Array<{
+    historyId: number;
+    entryId: string;
+    snapshot: IntelligenceEntry;
+    changedBy: string;
+    changeReason: string | null;
+    createdAt: number;
+  }> {
+    const db = this.vault.getDb();
+    const rows = db
+      .prepare(
+        'SELECT * FROM curator_entry_history WHERE entry_id = ? ORDER BY created_at ASC, id ASC',
+      )
+      .all(entryId) as Array<Record<string, unknown>>;
+
+    return rows.map((row) => ({
+      historyId: row.id as number,
+      entryId: row.entry_id as string,
+      snapshot: JSON.parse(row.snapshot as string) as IntelligenceEntry,
+      changedBy: row.changed_by as string,
+      changeReason: (row.change_reason as string) ?? null,
+      createdAt: row.created_at as number,
+    }));
+  }
+
+  // ─── Queue Stats ──────────────────────────────────────────────
+
+  getQueueStats(): {
+    totalEntries: number;
+    groomedEntries: number;
+    ungroomedEntries: number;
+    staleEntries: number;
+    freshEntries: number;
+    avgDaysSinceGroom: number;
+  } {
+    const db = this.vault.getDb();
+    const totalEntries = (
+      db.prepare('SELECT COUNT(*) as count FROM entries').get() as { count: number }
+    ).count;
+
+    const groomedEntries = (
+      db
+        .prepare(
+          'SELECT COUNT(*) as count FROM curator_entry_state WHERE last_groomed_at IS NOT NULL',
+        )
+        .get() as { count: number }
+    ).count;
+
+    const ungroomedEntries = totalEntries - groomedEntries;
+
+    const now = Math.floor(Date.now() / 1000);
+    const staleThreshold = now - 30 * 86400;
+    const freshThreshold = now - 7 * 86400;
+
+    const staleEntries = (
+      db
+        .prepare(
+          'SELECT COUNT(*) as count FROM curator_entry_state WHERE last_groomed_at IS NOT NULL AND last_groomed_at < ?',
+        )
+        .get(staleThreshold) as { count: number }
+    ).count;
+
+    const freshEntries = (
+      db
+        .prepare(
+          'SELECT COUNT(*) as count FROM curator_entry_state WHERE last_groomed_at IS NOT NULL AND last_groomed_at >= ?',
+        )
+        .get(freshThreshold) as { count: number }
+    ).count;
+
+    let avgDaysSinceGroom = 0;
+    if (groomedEntries > 0) {
+      const sumRow = db
+        .prepare(
+          'SELECT SUM(? - last_groomed_at) as total FROM curator_entry_state WHERE last_groomed_at IS NOT NULL',
+        )
+        .get(now) as { total: number | null };
+      const totalSeconds = sumRow.total ?? 0;
+      avgDaysSinceGroom = Math.round((totalSeconds / groomedEntries / 86400) * 100) / 100;
+    }
+
+    return {
+      totalEntries,
+      groomedEntries,
+      ungroomedEntries,
+      staleEntries,
+      freshEntries,
+      avgDaysSinceGroom,
+    };
+  }
+
+  // ─── Metadata Enrichment ──────────────────────────────────────
+
+  enrichMetadata(entryId: string): {
+    enriched: boolean;
+    changes: Array<{ field: string; before: string; after: string }>;
+  } {
+    const entry = this.vault.get(entryId);
+    if (!entry) return { enriched: false, changes: [] };
+
+    const changes: Array<{ field: string; before: string; after: string }> = [];
+    const updates: Partial<
+      Pick<IntelligenceEntry, 'title' | 'description' | 'tags' | 'severity' | 'type'>
+    > = {};
+
+    // Auto-capitalize title
+    if (entry.title.length > 0 && entry.title[0] !== entry.title[0].toUpperCase()) {
+      const capitalized = entry.title[0].toUpperCase() + entry.title.slice(1);
+      changes.push({ field: 'title', before: entry.title, after: capitalized });
+      updates.title = capitalized;
+    }
+
+    // Normalize tags: lowercase, trim, dedup
+    const normalizedTags = [...new Set(entry.tags.map((t) => t.toLowerCase().trim()))];
+    const tagsChanged =
+      normalizedTags.length !== entry.tags.length ||
+      normalizedTags.some((t, i) => t !== entry.tags[i]);
+    if (tagsChanged) {
+      changes.push({
+        field: 'tags',
+        before: JSON.stringify(entry.tags),
+        after: JSON.stringify(normalizedTags),
+      });
+      updates.tags = normalizedTags;
+    }
+
+    // Infer severity from keywords if currently 'suggestion'
+    if (entry.severity === 'suggestion') {
+      const text = (entry.title + ' ' + entry.description).toLowerCase();
+      const criticalKeywords = ['never', 'must not', 'critical', 'security', 'vulnerability'];
+      const warningKeywords = ['avoid', 'should not', 'deprecated', 'careful', 'warning'];
+      if (criticalKeywords.some((k) => text.includes(k))) {
+        changes.push({ field: 'severity', before: entry.severity, after: 'critical' });
+        updates.severity = 'critical';
+      } else if (warningKeywords.some((k) => text.includes(k))) {
+        changes.push({ field: 'severity', before: entry.severity, after: 'warning' });
+        updates.severity = 'warning';
+      }
+    }
+
+    // Infer type from title patterns
+    if (entry.type === 'pattern') {
+      const titleLower = entry.title.toLowerCase();
+      if (
+        titleLower.startsWith('avoid') ||
+        titleLower.startsWith('never') ||
+        titleLower.startsWith("don't") ||
+        titleLower.startsWith('do not')
+      ) {
+        changes.push({ field: 'type', before: entry.type, after: 'anti-pattern' });
+        updates.type = 'anti-pattern';
+      }
+    }
+
+    // Trim whitespace from description
+    const trimmed = entry.description.trim();
+    if (trimmed !== entry.description) {
+      changes.push({ field: 'description', before: entry.description, after: trimmed });
+      updates.description = trimmed;
+    }
+
+    if (changes.length === 0) {
+      return { enriched: false, changes: [] };
+    }
+
+    // Apply updates
+    this.vault.update(entryId, updates);
+
+    // Record snapshot
+    this.recordSnapshot(entryId, 'curator', 'Metadata enrichment');
+
+    // Log change
+    this.logChange(
+      'enrich_metadata',
+      entryId,
+      JSON.stringify(changes.map((c) => c.field)),
+      JSON.stringify(changes.map((c) => c.after)),
+      'Rule-based metadata enrichment',
+    );
+
+    return { enriched: true, changes };
+  }
+
   // ─── Private Helpers ────────────────────────────────────────────
 
   private buildVocabulary(entries: IntelligenceEntry[]): Map<string, number> {

package/src/errors/classify.ts

@@ -0,0 +1,102 @@
+/**
+ * Error classifier — converts any thrown value into a typed SoleriError.
+ *
+ * Maps HTTP status codes, network error codes, and message patterns
+ * to the appropriate SoleriErrorCode.
+ */
+
+import { SoleriError, SoleriErrorCode } from './types.js';
+
+interface ErrorLike {
+  message?: string;
+  status?: number;
+  statusCode?: number;
+  code?: string;
+  cause?: unknown;
+}
+
+function toErrorLike(error: unknown): ErrorLike {
+  if (error instanceof SoleriError) return error;
+  if (error instanceof Error) return error as unknown as ErrorLike;
+  if (typeof error === 'object' && error !== null) return error as ErrorLike;
+  return { message: String(error) };
+}
+
+function getHttpStatus(e: ErrorLike): number | undefined {
+  return e.status ?? e.statusCode;
+}
+
+function classifyByHttpStatus(status: number): SoleriErrorCode | undefined {
+  if (status === 401 || status === 403) return SoleriErrorCode.AUTH;
+  if (status === 404) return SoleriErrorCode.RESOURCE_NOT_FOUND;
+  if (status === 408) return SoleriErrorCode.TIMEOUT;
+  if (status === 429) return SoleriErrorCode.RATE_LIMIT;
+  if (status === 422) return SoleriErrorCode.VALIDATION;
+  if (status >= 500 && status < 600) return SoleriErrorCode.INTERNAL;
+  return undefined;
+}
+
+const NETWORK_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'ECONNRESET', 'EPIPE', 'EHOSTUNREACH']);
+const TIMEOUT_CODES = new Set(['ETIMEDOUT', 'ESOCKETTIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT']);
+
+function classifyByErrorCode(code: string | undefined): SoleriErrorCode | undefined {
+  if (!code) return undefined;
+  if (NETWORK_CODES.has(code)) return SoleriErrorCode.NETWORK;
+  if (TIMEOUT_CODES.has(code)) return SoleriErrorCode.TIMEOUT;
+  return undefined;
+}
+
+const MESSAGE_PATTERNS: Array<[RegExp, SoleriErrorCode]> = [
+  [/overloaded|capacity|model.*busy/i, SoleriErrorCode.LLM_OVERLOAD],
+  [/timeout|timed?\s*out/i, SoleriErrorCode.TIMEOUT],
+  [/vault|database|sqlite/i, SoleriErrorCode.VAULT_UNREACHABLE],
+  [/invalid|validation|schema/i, SoleriErrorCode.VALIDATION],
+  [/config(uration)?|missing.*key|env/i, SoleriErrorCode.CONFIG_ERROR],
+  [/auth(entication|orization)?|forbidden|denied|unauthorized/i, SoleriErrorCode.AUTH],
+  [/not\s*found|404|no\s+such/i, SoleriErrorCode.RESOURCE_NOT_FOUND],
+  [/rate\s*limit|too\s+many\s+requests|throttl/i, SoleriErrorCode.RATE_LIMIT],
+  [/network|connect|socket|dns/i, SoleriErrorCode.NETWORK],
+];
+
+function classifyByMessage(message: string | undefined): SoleriErrorCode | undefined {
+  if (!message) return undefined;
+  for (const [pattern, code] of MESSAGE_PATTERNS) {
+    if (pattern.test(message)) return code;
+  }
+  return undefined;
+}
+
+/**
+ * Classify any thrown value into a SoleriError.
+ * If the value is already a SoleriError, returns it as-is.
+ */
+export function classifyError(error: unknown): SoleriError {
+  if (error instanceof SoleriError) return error;
+
+  const e = toErrorLike(error);
+  const originalError = error instanceof Error ? error : undefined;
+  const message = e.message ?? 'Unknown error';
+
+  // 1. HTTP status code
+  const httpStatus = getHttpStatus(e);
+  if (httpStatus !== undefined) {
+    const code = classifyByHttpStatus(httpStatus);
+    if (code)
+      return new SoleriError(message, code, { cause: originalError, context: { httpStatus } });
+  }
+
+  // 2. Node.js error code
+  const errCode = classifyByErrorCode(e.code);
+  if (errCode)
+    return new SoleriError(message, errCode, {
+      cause: originalError,
+      context: { errorCode: e.code },
+    });
+
+  // 3. Message pattern matching
+  const msgCode = classifyByMessage(message);
+  if (msgCode) return new SoleriError(message, msgCode, { cause: originalError });
+
+  // 4. Default: permanent INTERNAL
+  return new SoleriError(message, SoleriErrorCode.INTERNAL, { cause: originalError });
+}

package/src/errors/index.ts

@@ -0,0 +1,5 @@
+export { SoleriErrorCode, SoleriError, ok, err, isOk, isErr } from './types.js';
+export type { ErrorClassification, Result, SoleriErrorOptions } from './types.js';
+export { classifyError } from './classify.js';
+export { retryWithPreset, shouldRetry, getRetryDelay, RETRY_PRESETS } from './retry.js';
+export type { RetryPreset, RetryConfig, RetryOptions } from './retry.js';

package/src/errors/retry.ts

@@ -0,0 +1,132 @@
+/**
+ * Retry presets with exponential backoff + jitter.
+ *
+ * Three presets map to different execution contexts:
+ * - fast:    quick API calls, 3 attempts, short waits
+ * - normal:  standard operations, 10 attempts, moderate waits
+ * - patient: batch/pipeline work, 25 attempts, long waits
+ */
+
+import { classifyError } from './classify.js';
+import { SoleriError, type Result, ok, err } from './types.js';
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+export type RetryPreset = 'fast' | 'normal' | 'patient';
+
+export interface RetryConfig {
+  initialIntervalMs: number;
+  maxIntervalMs: number;
+  maxAttempts: number;
+  backoffMultiplier: number;
+}
+
+export interface RetryOptions {
+  onRetry?: (error: SoleriError, attempt: number, delayMs: number) => void;
+  signal?: AbortSignal;
+}
+
+// ─── Presets ───────────────────────────────────────────────────────────
+
+export const RETRY_PRESETS: Record<RetryPreset, RetryConfig> = {
+  fast: { initialIntervalMs: 1_000, maxIntervalMs: 10_000, maxAttempts: 3, backoffMultiplier: 2 },
+  normal: {
+    initialIntervalMs: 10_000,
+    maxIntervalMs: 120_000,
+    maxAttempts: 10,
+    backoffMultiplier: 2,
+  },
+  patient: {
+    initialIntervalMs: 60_000,
+    maxIntervalMs: 900_000,
+    maxAttempts: 25,
+    backoffMultiplier: 1.5,
+  },
+};
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Check if a classified error should be retried at the given attempt.
+ */
+export function shouldRetry(error: SoleriError, attempt: number, preset: RetryPreset): boolean {
+  if (!error.retryable) return false;
+  return attempt < RETRY_PRESETS[preset].maxAttempts;
+}
+
+/**
+ * Calculate retry delay with exponential backoff + jitter.
+ * Jitter adds ±25% to prevent thundering herd.
+ */
+export function getRetryDelay(attempt: number, preset: RetryPreset): number {
+  const config = RETRY_PRESETS[preset];
+  const base = config.initialIntervalMs * Math.pow(config.backoffMultiplier, attempt);
+  const capped = Math.min(base, config.maxIntervalMs);
+  // ±25% jitter
+  const jitter = capped * 0.25 * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(capped + jitter));
+}
+
+// ─── Retry Loop ────────────────────────────────────────────────────────
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error('Aborted'));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason ?? new Error('Aborted'));
+      },
+      { once: true },
+    );
+  });
+}
+
+/**
+ * Retry an async operation with a named preset.
+ *
+ * - On success: returns ok(result)
+ * - On permanent/fixable error: returns err() immediately
+ * - On retryable error: retries up to maxAttempts with backoff
+ * - On exhaustion: returns err() with last error
+ */
+export async function retryWithPreset<T>(
+  fn: () => Promise<T>,
+  preset: RetryPreset,
+  options?: RetryOptions,
+): Promise<Result<T>> {
+  let lastError: SoleriError | undefined;
+
+  for (let attempt = 0; attempt < RETRY_PRESETS[preset].maxAttempts; attempt++) {
+    try {
+      const value = await fn();
+      return ok(value);
+    } catch (thrown: unknown) {
+      lastError = classifyError(thrown);
+
+      if (!shouldRetry(lastError, attempt + 1, preset)) {
+        return err(lastError);
+      }
+
+      const delay = getRetryDelay(attempt, preset);
+      options?.onRetry?.(lastError, attempt + 1, delay);
+
+      try {
+        await sleep(delay, options?.signal);
+      } catch {
+        // Aborted during sleep
+        return err(lastError);
+      }
+    }
+  }
+
+  return err(lastError ?? new SoleriError('Max retries exceeded', SoleriErrorCode.INTERNAL));
+}
+
+// Re-import for the err fallback
+import { SoleriErrorCode } from './types.js';