@soleri/core 8.1.0 → 9.0.1

package/src/cognee/sync-manager.ts

@@ -1,389 +0,0 @@
-/**
- * CogneeSyncManager — queued, resilient sync between the Vault SQLite DB and Cognee.
- *
- * Maintains a persistent queue (`cognee_sync_queue`) so that ingestions, updates,
- * and deletions survive process restarts. Drain is idempotent and retry-safe.
- * Health-flip detection auto-drains when Cognee comes back online.
- *
- * Ported from Salvador MCP's battle-tested cognee-sync module.
- */
-
-import { createHash } from 'node:crypto';
-import type { PersistenceProvider } from '../persistence/types.js';
-import type { CogneeClient } from './client.js';
-import type { IntelligenceEntry } from '../intelligence/types.js';
-
-// ─── Types ──────────────────────────────────────────────────────────
-
-export type SyncOp = 'ingest' | 'update' | 'delete';
-export type SyncStatus = 'pending' | 'processing' | 'completed' | 'failed';
-
-export interface SyncQueueItem {
-  id: number;
-  op: SyncOp;
-  entryId: string;
-  dataset: string;
-  contentHash: string | null;
-  status: SyncStatus;
-  attempts: number;
-  error: string | null;
-  createdAt: number;
-  processedAt: number | null;
-}
-
-export interface SyncManagerStats {
-  pending: number;
-  processing: number;
-  completed: number;
-  failed: number;
-  queueSize: number;
-  lastDrainAt: number | null;
-}
-
-// ─── Constants ──────────────────────────────────────────────────────
-
-const MAX_BATCH = 10;
-const MAX_RETRIES = 3;
-
-// ─── CogneeSyncManager ─────────────────────────────────────────────
-
-export class CogneeSyncManager {
-  private db: PersistenceProvider;
-  private cognee: CogneeClient;
-  private dataset: string;
-  private lastDrainAt: number | null = null;
-  private drainTimer: ReturnType<typeof setInterval> | null = null;
-  private wasAvailable: boolean = false;
-
-  constructor(db: PersistenceProvider, cognee: CogneeClient, dataset: string) {
-    this.db = db;
-    this.cognee = cognee;
-    this.dataset = dataset;
-    this.initSchema();
-    this.wasAvailable = cognee.isAvailable;
-  }
-
-  // ─── Schema ────────────────────────────────────────────────────
-
-  private initSchema(): void {
-    this.db.execSql(`
-      CREATE TABLE IF NOT EXISTS cognee_sync_queue (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        op TEXT NOT NULL,
-        entry_id TEXT NOT NULL,
-        dataset TEXT NOT NULL,
-        content_hash TEXT,
-        status TEXT NOT NULL DEFAULT 'pending',
-        attempts INTEGER NOT NULL DEFAULT 0,
-        error TEXT,
-        created_at INTEGER NOT NULL DEFAULT (unixepoch()),
-        processed_at INTEGER
-      )
-    `);
-
-    // Add cognee_ingested_hash column to entries table for reconciliation.
-    // ALTER TABLE ... ADD COLUMN is a no-op error when the column already exists.
-    try {
-      this.db.run('ALTER TABLE entries ADD COLUMN cognee_ingested_hash TEXT');
-    } catch {
-      // Column already exists — expected on subsequent runs.
-    }
-  }
-
-  // ─── Content hashing ──────────────────────────────────────────
-
-  /**
-   * SHA-256 of the serialized entry fields, truncated to 16 hex characters.
-   * Deterministic for identical content — used to detect drift.
-   */
-  static contentHash(entry: IntelligenceEntry): string {
-    const payload = JSON.stringify({
-      id: entry.id,
-      type: entry.type,
-      domain: entry.domain,
-      title: entry.title,
-      severity: entry.severity,
-      description: entry.description,
-      context: entry.context ?? null,
-      example: entry.example ?? null,
-      counterExample: entry.counterExample ?? null,
-      why: entry.why ?? null,
-      tags: entry.tags,
-      appliesTo: entry.appliesTo ?? [],
-    });
-    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
-  }
-
-  // ─── Enqueue ──────────────────────────────────────────────────
-
-  /**
-   * Add an operation to the sync queue.
-   *
-   * @param op       The operation type (ingest | update | delete).
-   * @param entryId  The vault entry ID.
-   * @param entry    Optional entry for hash computation. If omitted, hash is null.
-   */
-  enqueue(op: SyncOp, entryId: string, entry?: IntelligenceEntry): void {
-    const contentHash = entry ? CogneeSyncManager.contentHash(entry) : null;
-    this.db.run(
-      `INSERT INTO cognee_sync_queue (op, entry_id, dataset, content_hash)
-       VALUES (@op, @entryId, @dataset, @contentHash)`,
-      {
-        op,
-        entryId,
-        dataset: this.dataset,
-        contentHash,
-      },
-    );
-  }
-
-  // ─── Drain ────────────────────────────────────────────────────
-
-  /**
-   * Process up to MAX_BATCH pending items from the queue.
-   * Returns the number of items successfully processed.
-   *
-   * If Cognee is not available, returns 0 without touching the queue.
-   */
-  async drain(): Promise<number> {
-    if (!this.cognee.isAvailable) return 0;
-
-    // Claim a batch: move pending → processing
-    const items = this.db.all<Record<string, unknown>>(
-      `SELECT * FROM cognee_sync_queue
-       WHERE status = 'pending' AND dataset = @dataset
-       ORDER BY created_at ASC
-       LIMIT @limit`,
-      { dataset: this.dataset, limit: MAX_BATCH },
-    );
-
-    if (items.length === 0) return 0;
-
-    let processed = 0;
-
-    for (const raw of items) {
-      const item = rowToQueueItem(raw);
-
-      // Mark as processing
-      this.db.run(
-        `UPDATE cognee_sync_queue SET status = 'processing', attempts = attempts + 1 WHERE id = @id`,
-        { id: item.id },
-      );
-
-      try {
-        if (item.op === 'ingest' || item.op === 'update') {
-          const entry = this.readEntry(item.entryId);
-          if (!entry) {
-            // Entry was deleted from vault before we could sync — mark completed
-            this.markCompleted(item.id);
-            processed++;
-            continue;
-          }
-
-          const result = await this.cognee.addEntries([entry]);
-          if (result.added === 0) {
-            throw new Error('Cognee addEntries returned 0 added');
-          }
-
-          // Update the ingested hash on the entries table
-          const hash = CogneeSyncManager.contentHash(entry);
-          this.db.run(`UPDATE entries SET cognee_ingested_hash = @hash WHERE id = @id`, {
-            hash,
-            id: item.entryId,
-          });
-
-          this.markCompleted(item.id);
-          processed++;
-        } else if (item.op === 'delete') {
-          // deleteEntries may not exist yet — graceful degradation
-          const client = this.cognee as unknown as Record<string, unknown>;
-          if (typeof client.deleteEntries === 'function') {
-            await (client.deleteEntries as (ids: string[]) => Promise<unknown>)([item.entryId]);
-          }
-          // Clear the ingested hash (entry may already be gone from entries table)
-          this.db.run(`UPDATE entries SET cognee_ingested_hash = NULL WHERE id = @id`, {
-            id: item.entryId,
-          });
-          this.markCompleted(item.id);
-          processed++;
-        }
-      } catch (err) {
-        const errorMsg = err instanceof Error ? err.message : String(err);
-        const attempts = item.attempts + 1; // Already incremented above
-        if (attempts >= MAX_RETRIES) {
-          this.db.run(
-            `UPDATE cognee_sync_queue SET status = 'failed', error = @error, processed_at = unixepoch() WHERE id = @id`,
-            { id: item.id, error: errorMsg },
-          );
-        } else {
-          // Back to pending for retry
-          this.db.run(
-            `UPDATE cognee_sync_queue SET status = 'pending', error = @error WHERE id = @id`,
-            { id: item.id, error: errorMsg },
-          );
-        }
-      }
-    }
-
-    this.lastDrainAt = Math.floor(Date.now() / 1000);
-    return processed;
-  }
-
-  // ─── Reconciliation ───────────────────────────────────────────
-
-  /**
-   * Find entries whose cognee_ingested_hash is NULL or doesn't match the
-   * current content hash. Enqueue dirty entries for re-ingestion.
-   *
-   * Returns the number of entries enqueued.
-   */
-  reconcile(): number {
-    // Get all entries that either have never been ingested or whose content changed
-    const rows = this.db.all<Record<string, unknown>>(
-      `SELECT * FROM entries WHERE cognee_ingested_hash IS NULL
-       UNION ALL
-       SELECT * FROM entries WHERE cognee_ingested_hash IS NOT NULL`,
-    );
-
-    let enqueued = 0;
-
-    for (const raw of rows) {
-      const entry = this.rowToEntry(raw);
-      const currentHash = CogneeSyncManager.contentHash(entry);
-      const ingestedHash = raw.cognee_ingested_hash as string | null;
-
-      if (ingestedHash === currentHash) continue;
-
-      // Determine op: null hash means never ingested, mismatched means update
-      const op: SyncOp = ingestedHash === null ? 'ingest' : 'update';
-
-      // Avoid duplicate pending items for the same entry
-      const existing = this.db.get<{ id: number }>(
-        `SELECT id FROM cognee_sync_queue
-         WHERE entry_id = @entryId AND dataset = @dataset AND status = 'pending'`,
-        { entryId: entry.id, dataset: this.dataset },
-      );
-
-      if (!existing) {
-        this.enqueue(op, entry.id, entry);
-        enqueued++;
-      }
-    }
-
-    return enqueued;
-  }
-
-  // ─── Stats ────────────────────────────────────────────────────
-
-  getStats(): SyncManagerStats {
-    const countByStatus = (status: SyncStatus): number => {
-      const row = this.db.get<{ count: number }>(
-        `SELECT COUNT(*) as count FROM cognee_sync_queue WHERE status = @status AND dataset = @dataset`,
-        { status, dataset: this.dataset },
-      );
-      return row?.count ?? 0;
-    };
-
-    const pending = countByStatus('pending');
-    const processing = countByStatus('processing');
-    const completed = countByStatus('completed');
-    const failed = countByStatus('failed');
-
-    return {
-      pending,
-      processing,
-      completed,
-      failed,
-      queueSize: pending + processing,
-      lastDrainAt: this.lastDrainAt,
-    };
-  }
-
-  // ─── Health-flip detection ────────────────────────────────────
-
-  /**
-   * Detects an unavailable-to-available transition on the Cognee client.
-   * When Cognee comes back online, automatically triggers a drain.
-   *
-   * Call this periodically (e.g. after each health check).
-   */
-  async checkHealthFlip(): Promise<void> {
-    const nowAvailable = this.cognee.isAvailable;
-    if (nowAvailable && !this.wasAvailable) {
-      // Cognee just came back online — drain the queue
-      await this.drain();
-    }
-    this.wasAvailable = nowAvailable;
-  }
-
-  // ─── Cleanup ──────────────────────────────────────────────────
-
-  /**
-   * Clear any periodic drain timer.
-   */
-  close(): void {
-    if (this.drainTimer) {
-      clearInterval(this.drainTimer);
-      this.drainTimer = null;
-    }
-  }
-
-  // ─── Private helpers ──────────────────────────────────────────
-
-  private markCompleted(id: number): void {
-    this.db.run(
-      `UPDATE cognee_sync_queue SET status = 'completed', processed_at = unixepoch() WHERE id = @id`,
-      { id },
-    );
-  }
-
-  /**
-   * Read an entry from the entries table by ID.
-   * Returns null if the entry doesn't exist.
-   */
-  private readEntry(id: string): IntelligenceEntry | null {
-    const row = this.db.get<Record<string, unknown>>('SELECT * FROM entries WHERE id = @id', {
-      id,
-    });
-    return row ? this.rowToEntry(row) : null;
-  }
-
-  /**
-   * Convert a raw DB row into an IntelligenceEntry.
-   */
-  private rowToEntry(row: Record<string, unknown>): IntelligenceEntry {
-    return {
-      id: row.id as string,
-      type: row.type as IntelligenceEntry['type'],
-      domain: row.domain as string,
-      title: row.title as string,
-      severity: row.severity as IntelligenceEntry['severity'],
-      description: row.description as string,
-      context: (row.context as string) ?? undefined,
-      example: (row.example as string) ?? undefined,
-      counterExample: (row.counter_example as string) ?? undefined,
-      why: (row.why as string) ?? undefined,
-      tags: JSON.parse((row.tags as string) || '[]'),
-      appliesTo: JSON.parse((row.applies_to as string) || '[]'),
-      validFrom: (row.valid_from as number) ?? undefined,
-      validUntil: (row.valid_until as number) ?? undefined,
-    };
-  }
-}
-
-// ─── Module-level helpers ─────────────────────────────────────────
-
-function rowToQueueItem(row: Record<string, unknown>): SyncQueueItem {
-  return {
-    id: row.id as number,
-    op: row.op as SyncOp,
-    entryId: row.entry_id as string,
-    dataset: row.dataset as string,
-    contentHash: (row.content_hash as string) ?? null,
-    status: row.status as SyncStatus,
-    attempts: row.attempts as number,
-    error: (row.error as string) ?? null,
-    createdAt: row.created_at as number,
-    processedAt: (row.processed_at as number) ?? null,
-  };
-}

package/src/cognee/types.ts

@@ -1,62 +0,0 @@
-// ─── Cognee Integration Types ──────────────────────────────────────
-
-export interface CogneeConfig {
-  /** Base URL of the Cognee API (default: http://localhost:8000) */
-  baseUrl: string;
-  /** Dataset name for this agent's vault entries */
-  dataset: string;
-  /** Bearer token for Cognee API authentication (auto-acquired if not set) */
-  apiToken?: string;
-  /** Service account email for auto-login (default: soleri-agent@cognee.dev) */
-  serviceEmail?: string;
-  /** Service account password for auto-login */
-  servicePassword?: string;
-  /** Default request timeout in milliseconds (default: 30000) */
-  timeoutMs: number;
-  /** Search timeout in milliseconds — Ollama cold start can take 90s (default: 120000) */
-  searchTimeoutMs: number;
-  /** Health check timeout in milliseconds (default: 5000) */
-  healthTimeoutMs: number;
-  /** Health check cache TTL in milliseconds (default: 60000) */
-  healthCacheTtlMs: number;
-  /** Cognify debounce window in milliseconds (default: 30000) */
-  cognifyDebounceMs: number;
-}
-
-export interface CogneeSearchResult {
-  /** Vault entry ID (cross-reference key) */
-  id: string;
-  /** Relevance score (0–1). Position-based when Cognee omits scores. */
-  score: number;
-  /** Text content from Cognee */
-  text: string;
-  /** Cognee search type that produced this result */
-  searchType: CogneeSearchType;
-}
-
-export type CogneeSearchType =
-  | 'SUMMARIES'
-  | 'CHUNKS'
-  | 'RAG_COMPLETION'
-  | 'TRIPLET_COMPLETION'
-  | 'GRAPH_COMPLETION'
-  | 'GRAPH_SUMMARY_COMPLETION'
-  | 'NATURAL_LANGUAGE'
-  | 'GRAPH_COMPLETION_COT'
-  | 'FEELING_LUCKY'
-  | 'CHUNKS_LEXICAL';
-
-export interface CogneeStatus {
-  available: boolean;
-  url: string;
-  latencyMs: number;
-  error?: string;
-}
-
-export interface CogneeAddResult {
-  added: number;
-}
-
-export interface CogneeCognifyResult {
-  status: string;
-}

package/src/runtime/cognee-sync-ops.ts

@@ -1,63 +0,0 @@
-/**
- * Cognee sync operations — 3 ops for queue visibility and control.
- */
-
-import { z } from 'zod';
-import type { OpDefinition } from '../facades/types.js';
-import type { CogneeSyncManager } from '../cognee/sync-manager.js';
-
-/**
- * Create the 3 cognee-sync operations.
- *
- * The sync manager is optional — when null, all ops return a graceful error.
- */
-export function createCogneeSyncOps(syncManager: CogneeSyncManager | null): OpDefinition[] {
-  return [
-    // ─── Status ──────────────────────────────────────────────────
-    {
-      name: 'cognee_sync_status',
-      description:
-        'Get current cognee sync queue stats — pending, processing, completed, failed counts.',
-      auth: 'read',
-      schema: z.object({}),
-      handler: async () => {
-        if (!syncManager) {
-          return { error: 'Sync manager not configured' };
-        }
-        return syncManager.getStats();
-      },
-    },
-
-    // ─── Drain ───────────────────────────────────────────────────
-    {
-      name: 'cognee_sync_drain',
-      description:
-        'Process pending items in the cognee sync queue. Returns count of processed items and updated stats.',
-      auth: 'write',
-      schema: z.object({}),
-      handler: async () => {
-        if (!syncManager) {
-          return { error: 'Sync manager not configured' };
-        }
-        const processed = await syncManager.drain();
-        return { processed, stats: syncManager.getStats() };
-      },
-    },
-
-    // ─── Reconcile ───────────────────────────────────────────────
-    {
-      name: 'cognee_sync_reconcile',
-      description:
-        'Find vault entries with stale or missing cognee ingestion and enqueue them for sync.',
-      auth: 'write',
-      schema: z.object({}),
-      handler: async () => {
-        if (!syncManager) {
-          return { error: 'Sync manager not configured' };
-        }
-        const enqueued = syncManager.reconcile();
-        return { enqueued, stats: syncManager.getStats() };
-      },
-    },
-  ];
-}

package/src/runtime/facades/cognee-facade.ts

@@ -1,164 +0,0 @@
-/**
- * Cognee facade — knowledge graph ops.
- * Cognee search, sync, export, graph stats.
- */
-
-import { z } from 'zod';
-import type { OpDefinition } from '../../facades/types.js';
-import type { IntelligenceEntry } from '../../intelligence/types.js';
-import type { AgentRuntime } from '../types.js';
-import type { CogneeSearchType } from '../../cognee/types.js';
-import { createCogneeSyncOps } from '../cognee-sync-ops.js';
-
-export function createCogneeFacadeOps(runtime: AgentRuntime): OpDefinition[] {
-  // Only called when runtime.cognee is non-null (guarded in createSemanticFacades)
-  const cognee = runtime.cognee!;
-  const { vault, syncManager } = runtime;
-
-  return [
-    // ─── Cognee (inline from core-ops.ts) ───────────────────────
-    {
-      name: 'cognee_status',
-      description:
-        'Cognee vector search health — availability, URL, latency. Checks the Cognee API endpoint.',
-      auth: 'read',
-      handler: async () => {
-        return cognee.healthCheck();
-      },
-    },
-    {
-      name: 'cognee_search',
-      description:
-        'Vector similarity search via Cognee. Complements TF-IDF vault search with semantic understanding.',
-      auth: 'read',
-      schema: z.object({
-        query: z.string(),
-        searchType: z
-          .enum([
-            'SUMMARIES',
-            'CHUNKS',
-            'RAG_COMPLETION',
-            'TRIPLET_COMPLETION',
-            'GRAPH_COMPLETION',
-            'GRAPH_SUMMARY_COMPLETION',
-            'NATURAL_LANGUAGE',
-            'GRAPH_COMPLETION_COT',
-            'FEELING_LUCKY',
-            'CHUNKS_LEXICAL',
-          ])
-          .optional()
-          .describe('Cognee search type. Default CHUNKS (pure vector similarity).'),
-        limit: z.number().optional(),
-      }),
-      handler: async (params) => {
-        return cognee.search(params.query as string, {
-          searchType: params.searchType as CogneeSearchType | undefined,
-          limit: (params.limit as number) ?? 10,
-        });
-      },
-    },
-    {
-      name: 'cognee_add',
-      description:
-        'Ingest vault entries into Cognee for vector indexing. Auto-schedules cognify after ingest.',
-      auth: 'write',
-      schema: z.object({
-        entryIds: z.array(z.string()).describe('Vault entry IDs to ingest into Cognee.'),
-      }),
-      handler: async (params) => {
-        const ids = params.entryIds as string[];
-        const entries = ids
-          .map((id) => vault.get(id))
-          .filter((e): e is IntelligenceEntry => e !== null && e !== undefined);
-        if (entries.length === 0) return { added: 0, error: 'No matching vault entries found' };
-        return cognee.addEntries(entries);
-      },
-    },
-    {
-      name: 'cognee_cognify',
-      description:
-        'Trigger Cognee knowledge graph processing on the vault dataset. Usually auto-scheduled after add.',
-      auth: 'write',
-      handler: async () => {
-        return cognee.cognify();
-      },
-    },
-    {
-      name: 'cognee_config',
-      description: 'Get current Cognee client configuration and cached health status.',
-      auth: 'read',
-      handler: async () => {
-        return { config: cognee.getConfig(), cachedStatus: cognee.getStatus() };
-      },
-    },
-    // ─── Cognee Graph ────────────────────────────────────────────
-    {
-      name: 'cognee_get_node',
-      description: 'Get a specific Cognee graph node by UUID with all properties and connections.',
-      auth: 'read',
-      schema: z.object({
-        nodeId: z.string().describe('UUID of the graph node'),
-      }),
-      handler: async (params) => {
-        try {
-          const results = await cognee.search(params.nodeId as string, {
-            searchType: 'GRAPH_COMPLETION' as CogneeSearchType,
-            limit: 1,
-          });
-          if (!results || (Array.isArray(results) && results.length === 0)) {
-            return { found: false, nodeId: params.nodeId };
-          }
-          return {
-            found: true,
-            nodeId: params.nodeId,
-            node: Array.isArray(results) ? results[0] : results,
-          };
-        } catch (err) {
-          return { error: (err as Error).message };
-        }
-      },
-    },
-    {
-      name: 'cognee_graph_stats',
-      description:
-        'Cognee graph statistics — availability, endpoint, latency from last health check.',
-      auth: 'read',
-      handler: async () => {
-        try {
-          const status = cognee.getStatus();
-          const health = await cognee.healthCheck();
-          return {
-            available: status?.available ?? false,
-            url: status?.url ?? cognee.getConfig().baseUrl,
-            latencyMs: status?.latencyMs ?? health.latencyMs ?? null,
-            error: status?.error ?? health.error ?? null,
-          };
-        } catch (err) {
-          return { error: (err as Error).message };
-        }
-      },
-    },
-    {
-      name: 'cognee_export_status',
-      description: 'Check Cognee dataset and processing status — availability, pending operations.',
-      auth: 'read',
-      handler: async () => {
-        try {
-          const status = cognee.getStatus();
-          const config = cognee.getConfig();
-          return {
-            available: status?.available ?? false,
-            dataset: config.dataset ?? 'default',
-            pendingCognify: false,
-            url: status?.url ?? config.baseUrl,
-          };
-        } catch (err) {
-          return { error: (err as Error).message };
-        }
-      },
-    },
-
-    // ─── Satellite ops ───────────────────────────────────────────
-    ...createCogneeSyncOps(syncManager),
-  ];
-}