zouroboros-core 2.0.0

package/dist/instincts.js

@@ -0,0 +1,428 @@
+/**
+ * ECC-004: Instincts — Pattern Auto-Extraction
+ *
+ * Automatic extraction of behavioral patterns from sessions.
+ * Detects recurring patterns, scores confidence, and extracts
+ * hot-loadable instinct files for future sessions.
+ * Persists to disk (JSON file) matching selfheal persistence pattern.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+const CONFIDENCE_THRESHOLD = 0.6;
+const MIN_EVIDENCE_FOR_ACTIVE = 3;
+export class InstinctEngine {
+    instincts = new Map();
+    evidence = new Map();
+    lastFired = new Map();
+    dataFile = null;
+    hooks = null;
+    pendingObservations = [];
+    constructor(dataDir) {
+        if (dataDir) {
+            mkdirSync(dataDir, { recursive: true });
+            this.dataFile = join(dataDir, 'instincts.json');
+            this.load();
+        }
+    }
+    wireHooks(hooks) {
+        this.hooks = hooks;
+        // Auto-extract from task failures
+        hooks.on('task.fail', (payload) => {
+            const context = String(payload.data.error || payload.data.detail || '');
+            if (context.length > 0) {
+                this.recordObservation({
+                    context,
+                    outcome: String(payload.data.resolution || 'task failed'),
+                    timestamp: payload.timestamp,
+                    sessionId: String(payload.data.sessionId || ''),
+                });
+            }
+        }, { priority: 50, description: 'Instinct auto-extraction from task failures' });
+        // Auto-extract from error recovery
+        hooks.on('error.recovery', (payload) => {
+            const context = String(payload.data.error || '');
+            const outcome = String(payload.data.recovery || 'recovered');
+            if (context.length > 0) {
+                this.recordObservation({ context, outcome, timestamp: payload.timestamp });
+            }
+        }, { priority: 50, description: 'Instinct auto-extraction from error recovery' });
+    }
+    /** Record a single observation for later batch extraction */
+    recordObservation(obs) {
+        this.pendingObservations.push(obs);
+        // Auto-extract when enough observations accumulate
+        if (this.pendingObservations.length >= 5) {
+            this.extract(this.pendingObservations.splice(0));
+        }
+    }
+    register(instinct) {
+        this.instincts.set(instinct.id, instinct);
+        if (!this.evidence.has(instinct.id)) {
+            this.evidence.set(instinct.id, []);
+        }
+        this.save();
+    }
+    get(id) {
+        return this.instincts.get(id) || null;
+    }
+    list(filter) {
+        let results = [...this.instincts.values()];
+        if (filter?.status) {
+            results = results.filter(i => i.status === filter.status);
+        }
+        if (filter?.minConfidence !== undefined) {
+            results = results.filter(i => i.confidence >= filter.minConfidence);
+        }
+        if (filter?.tag) {
+            results = results.filter(i => i.tags.includes(filter.tag));
+        }
+        return results.sort((a, b) => b.confidence - a.confidence);
+    }
+    addEvidence(instinctId, ev) {
+        const instinct = this.instincts.get(instinctId);
+        if (!instinct)
+            return false;
+        const evidenceList = this.evidence.get(instinctId) || [];
+        evidenceList.push(ev);
+        // Keep last 100 evidence items
+        if (evidenceList.length > 100) {
+            evidenceList.splice(0, evidenceList.length - 100);
+        }
+        this.evidence.set(instinctId, evidenceList);
+        // Update instinct
+        instinct.evidenceCount = evidenceList.length;
+        instinct.lastSeen = ev.timestamp;
+        instinct.pattern.frequency = evidenceList.length;
+        // Recalculate confidence
+        instinct.confidence = this.calculateConfidence(evidenceList);
+        // Auto-promote to active if enough evidence
+        if (instinct.status === 'candidate' &&
+            instinct.confidence >= CONFIDENCE_THRESHOLD &&
+            instinct.evidenceCount >= MIN_EVIDENCE_FOR_ACTIVE) {
+            instinct.status = 'active';
+        }
+        this.save();
+        return true;
+    }
+    /** Record a negative match — the instinct fired but was wrong */
+    rejectMatch(instinctId) {
+        const instinct = this.instincts.get(instinctId);
+        if (!instinct)
+            return false;
+        this.addEvidence(instinctId, {
+            timestamp: new Date().toISOString(),
+            context: 'rejected by user',
+            matchStrength: -0.5,
+        });
+        // Auto-suspend if confidence drops too low
+        if (instinct.confidence < 0.3 && instinct.status === 'active') {
+            instinct.status = 'suspended';
+        }
+        this.save();
+        return true;
+    }
+    match(context, event) {
+        const matches = [];
+        for (const instinct of this.instincts.values()) {
+            if (instinct.status !== 'active')
+                continue;
+            // Check cooldown
+            const lastFired = this.lastFired.get(instinct.id) || 0;
+            if (Date.now() - lastFired < instinct.trigger.cooldownMs)
+                continue;
+            // Check event match
+            if (event && instinct.trigger.event !== '*' && instinct.trigger.event !== event)
+                continue;
+            // Check pattern signature match
+            const matchStrength = this.computeMatch(instinct, context);
+            if (matchStrength > 0.3) {
+                const evidence = this.evidence.get(instinct.id) || [];
+                matches.push({
+                    instinct,
+                    confidence: matchStrength * instinct.confidence,
+                    evidence: evidence.slice(-3),
+                });
+            }
+        }
+        return matches.sort((a, b) => b.confidence - a.confidence);
+    }
+    fire(instinctId) {
+        const instinct = this.instincts.get(instinctId);
+        if (!instinct || instinct.status !== 'active')
+            return false;
+        this.lastFired.set(instinctId, Date.now());
+        // Emit hook event
+        if (this.hooks) {
+            this.hooks.emit('instinct.fired', {
+                instinctId,
+                name: instinct.name,
+                confidence: instinct.confidence,
+                resolution: instinct.resolution,
+            }, 'instinct-engine').catch(() => { });
+        }
+        return true;
+    }
+    extract(observations) {
+        const result = {
+            patternsDetected: 0,
+            instinctsCreated: 0,
+            instinctsUpdated: 0,
+            details: [],
+        };
+        // Group by context similarity using Jaccard index
+        const groups = this.groupByContextSimilarity(observations);
+        result.patternsDetected = groups.length;
+        for (const group of groups) {
+            if (group.items.length < 2) {
+                result.details.push({ id: '', action: 'skipped', reason: 'insufficient observations' });
+                continue;
+            }
+            const signature = this.generateSignature(group.items);
+            const existingId = this.findBySignature(signature);
+            if (existingId) {
+                for (const item of group.items) {
+                    this.addEvidence(existingId, {
+                        timestamp: item.timestamp,
+                        sessionId: item.sessionId,
+                        context: item.context.slice(0, 200),
+                        matchStrength: 0.8,
+                    });
+                }
+                result.instinctsUpdated++;
+                result.details.push({ id: existingId, action: 'updated' });
+            }
+            else {
+                const id = `instinct-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+                const instinct = {
+                    id,
+                    name: `Auto: ${signature.slice(0, 40)}`,
+                    description: `Pattern detected from ${group.items.length} observations`,
+                    confidence: group.items.length >= MIN_EVIDENCE_FOR_ACTIVE ? 0.7 : 0.4,
+                    pattern: {
+                        type: 'custom',
+                        signature,
+                        frequency: group.items.length,
+                        windowSize: group.items.length,
+                    },
+                    trigger: {
+                        event: '*',
+                        condition: signature,
+                        cooldownMs: 60000,
+                    },
+                    resolution: group.items[0].outcome,
+                    evidenceCount: group.items.length,
+                    lastSeen: group.items[group.items.length - 1].timestamp,
+                    createdAt: new Date().toISOString(),
+                    status: group.items.length >= MIN_EVIDENCE_FOR_ACTIVE ? 'active' : 'candidate',
+                    tags: ['auto-extracted'],
+                };
+                this.instincts.set(id, instinct);
+                this.evidence.set(id, []);
+                for (const item of group.items) {
+                    this.addEvidence(id, {
+                        timestamp: item.timestamp,
+                        sessionId: item.sessionId,
+                        context: item.context.slice(0, 200),
+                        matchStrength: 0.8,
+                    });
+                }
+                result.instinctsCreated++;
+                result.details.push({ id, action: 'created' });
+            }
+        }
+        this.save();
+        return result;
+    }
+    suspend(id) {
+        const instinct = this.instincts.get(id);
+        if (!instinct)
+            return false;
+        instinct.status = 'suspended';
+        this.save();
+        return true;
+    }
+    activate(id) {
+        const instinct = this.instincts.get(id);
+        if (!instinct)
+            return false;
+        instinct.status = 'active';
+        this.save();
+        return true;
+    }
+    retire(id) {
+        const instinct = this.instincts.get(id);
+        if (!instinct)
+            return false;
+        instinct.status = 'retired';
+        this.save();
+        return true;
+    }
+    remove(id) {
+        this.evidence.delete(id);
+        this.lastFired.delete(id);
+        const deleted = this.instincts.delete(id);
+        if (deleted)
+            this.save();
+        return deleted;
+    }
+    getStats() {
+        const all = [...this.instincts.values()];
+        const byStatus = { candidate: 0, active: 0, suspended: 0, retired: 0 };
+        let totalConfidence = 0;
+        let totalEvidence = 0;
+        for (const inst of all) {
+            byStatus[inst.status] = (byStatus[inst.status] || 0) + 1;
+            totalConfidence += inst.confidence;
+            totalEvidence += inst.evidenceCount;
+        }
+        return {
+            total: all.length,
+            byStatus: byStatus,
+            avgConfidence: all.length > 0 ? totalConfidence / all.length : 0,
+            totalEvidence,
+        };
+    }
+    exportInstinct(id) {
+        const instinct = this.instincts.get(id);
+        if (!instinct)
+            return null;
+        return {
+            ...instinct,
+            evidence: this.evidence.get(id) || [],
+        };
+    }
+    importInstinct(data) {
+        const { evidence: evidenceData, ...instinct } = data;
+        this.instincts.set(instinct.id, instinct);
+        if (evidenceData) {
+            this.evidence.set(instinct.id, evidenceData);
+        }
+        if (!this.evidence.has(instinct.id)) {
+            this.evidence.set(instinct.id, []);
+        }
+        this.save();
+    }
+    calculateConfidence(evidenceList) {
+        if (evidenceList.length === 0)
+            return 0;
+        const now = Date.now();
+        let weightedSum = 0;
+        let totalWeight = 0;
+        for (const ev of evidenceList) {
+            const age = now - new Date(ev.timestamp).getTime();
+            const recencyWeight = Math.exp(-age / (7 * 24 * 3600 * 1000)); // 7-day half-life
+            const weight = recencyWeight + 0.1;
+            weightedSum += ev.matchStrength * weight;
+            totalWeight += weight;
+        }
+        const avgStrength = weightedSum / totalWeight;
+        const countFactor = Math.min(evidenceList.length / 10, 1);
+        return Math.max(Math.min(avgStrength * (0.5 + 0.5 * countFactor), 1.0), 0);
+    }
+    computeMatch(instinct, context) {
+        const sigWords = instinct.pattern.signature.toLowerCase().split(/\s+/).filter(w => w.length >= 3);
+        const contextLower = context.toLowerCase();
+        if (sigWords.length === 0)
+            return 0;
+        // Use substring matching for better accuracy
+        let matches = 0;
+        for (const word of sigWords) {
+            if (contextLower.includes(word))
+                matches++;
+        }
+        return matches / sigWords.length;
+    }
+    /**
+     * Group observations by context similarity using Jaccard index on word sets.
+     */
+    groupByContextSimilarity(observations) {
+        if (observations.length === 0)
+            return [];
+        const wordSets = observations.map(obs => new Set(obs.context.toLowerCase().split(/\s+/).filter(w => w.length >= 3)));
+        const assigned = new Array(observations.length).fill(false);
+        const groups = [];
+        for (let i = 0; i < observations.length; i++) {
+            if (assigned[i])
+                continue;
+            assigned[i] = true;
+            const group = [observations[i]];
+            for (let j = i + 1; j < observations.length; j++) {
+                if (assigned[j])
+                    continue;
+                const jaccard = this.jaccardSimilarity(wordSets[i], wordSets[j]);
+                if (jaccard >= 0.4) {
+                    group.push(observations[j]);
+                    assigned[j] = true;
+                }
+            }
+            groups.push({ items: group });
+        }
+        return groups;
+    }
+    jaccardSimilarity(a, b) {
+        if (a.size === 0 && b.size === 0)
+            return 1;
+        let intersection = 0;
+        for (const word of a) {
+            if (b.has(word))
+                intersection++;
+        }
+        const union = a.size + b.size - intersection;
+        return union > 0 ? intersection / union : 0;
+    }
+    generateSignature(items) {
+        const wordCounts = new Map();
+        for (const item of items) {
+            const words = new Set(item.context.toLowerCase().split(/\s+/).filter(w => w.length >= 3));
+            for (const word of words) {
+                wordCounts.set(word, (wordCounts.get(word) || 0) + 1);
+            }
+        }
+        const threshold = Math.ceil(items.length * 0.5);
+        const commonWords = [...wordCounts.entries()]
+            .filter(([, count]) => count >= threshold)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([word]) => word)
+            .sort(); // Sort alphabetically for stable signatures
+        return commonWords.join(' ') || items[0].context.slice(0, 50);
+    }
+    findBySignature(signature) {
+        const sigWords = new Set(signature.split(' '));
+        for (const [id, instinct] of this.instincts) {
+            const existingWords = new Set(instinct.pattern.signature.split(' '));
+            const jaccard = this.jaccardSimilarity(sigWords, existingWords);
+            if (jaccard >= 0.7) {
+                return id;
+            }
+        }
+        return null;
+    }
+    load() {
+        if (!this.dataFile || !existsSync(this.dataFile))
+            return;
+        try {
+            const store = JSON.parse(readFileSync(this.dataFile, 'utf-8'));
+            for (const instinct of store.instincts) {
+                this.instincts.set(instinct.id, instinct);
+            }
+            for (const [id, evidenceList] of Object.entries(store.evidence)) {
+                this.evidence.set(id, evidenceList);
+            }
+        }
+        catch { /* start fresh if corrupt */ }
+    }
+    save() {
+        if (!this.dataFile)
+            return;
+        const store = {
+            version: '1.0.0',
+            instincts: [...this.instincts.values()],
+            evidence: Object.fromEntries(this.evidence),
+        };
+        writeFileSync(this.dataFile, JSON.stringify(store, null, 2));
+    }
+}
+export function createInstinctEngine(dataDir) {
+    return new InstinctEngine(dataDir);
+}

package/dist/migrations.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Versioned database migration system for Zouroboros.
+ *
+ * Migrations are defined as numbered entries with up/down SQL.
+ * The system tracks which migrations have been applied in a
+ * `_migrations` table and applies them in order.
+ */
+export interface Migration {
+    id: number;
+    name: string;
+    up: string;
+    down: string;
+}
+export interface MigrationRecord {
+    id: number;
+    name: string;
+    applied_at: number;
+}
+export interface MigrationStatus {
+    applied: MigrationRecord[];
+    pending: Migration[];
+    current: number;
+}
+export interface MigrationResult {
+    applied: string[];
+    skipped: string[];
+    errors: {
+        name: string;
+        error: string;
+    }[];
+}
+/**
+ * Built-in migrations registry.
+ * New migrations are appended here with incrementing IDs.
+ * IDs must be sequential and never reused.
+ */
+export declare const MIGRATIONS: Migration[];
+export interface MigrationRunner {
+    ensureMigrationsTable(): void;
+    getApplied(): MigrationRecord[];
+    getStatus(): MigrationStatus;
+    migrate(targetId?: number): MigrationResult;
+    rollback(targetId: number): MigrationResult;
+}
+/**
+ * Create a migration runner for a given database.
+ * The `db` parameter must support `.exec(sql)`, `.query(sql).all()`,
+ * and `.run(sql, params)` — matching bun:sqlite's Database API.
+ */
+export declare function createMigrationRunner(db: {
+    exec(sql: string): void;
+    query(sql: string): {
+        all(): unknown[];
+    };
+    run(sql: string, params?: unknown[]): void;
+}): MigrationRunner;

package/dist/migrations.js

@@ -0,0 +1,123 @@
+/**
+ * Versioned database migration system for Zouroboros.
+ *
+ * Migrations are defined as numbered entries with up/down SQL.
+ * The system tracks which migrations have been applied in a
+ * `_migrations` table and applies them in order.
+ */
+/**
+ * Built-in migrations registry.
+ * New migrations are appended here with incrementing IDs.
+ * IDs must be sequential and never reused.
+ */
+export const MIGRATIONS = [
+    {
+        id: 1,
+        name: '001_add_migrations_table',
+        up: `
+      CREATE TABLE IF NOT EXISTS _migrations (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL UNIQUE,
+        applied_at INTEGER DEFAULT (strftime('%s', 'now'))
+      );
+    `,
+        down: `DROP TABLE IF EXISTS _migrations;`,
+    },
+    {
+        id: 2,
+        name: '002_add_facts_persona_index',
+        up: `CREATE INDEX IF NOT EXISTS idx_facts_persona ON facts(persona);`,
+        down: `DROP INDEX IF EXISTS idx_facts_persona;`,
+    },
+    {
+        id: 3,
+        name: '003_add_facts_confidence_index',
+        up: `CREATE INDEX IF NOT EXISTS idx_facts_confidence ON facts(confidence);`,
+        down: `DROP INDEX IF EXISTS idx_facts_confidence;`,
+    },
+    {
+        id: 4,
+        name: '004_add_episodes_procedure_index',
+        up: `CREATE INDEX IF NOT EXISTS idx_episodes_procedure ON episodes(procedure_id);`,
+        down: `DROP INDEX IF EXISTS idx_episodes_procedure;`,
+    },
+    {
+        id: 5,
+        name: '005_add_open_loops_priority_index',
+        up: `CREATE INDEX IF NOT EXISTS idx_open_loops_priority ON open_loops(priority, status);`,
+        down: `DROP INDEX IF EXISTS idx_open_loops_priority;`,
+    },
+];
+/**
+ * Create a migration runner for a given database.
+ * The `db` parameter must support `.exec(sql)`, `.query(sql).all()`,
+ * and `.run(sql, params)` — matching bun:sqlite's Database API.
+ */
+export function createMigrationRunner(db) {
+    function ensureMigrationsTable() {
+        db.exec(MIGRATIONS[0].up);
+    }
+    function getApplied() {
+        ensureMigrationsTable();
+        return db.query('SELECT id, name, applied_at FROM _migrations ORDER BY id')
+            .all();
+    }
+    function getStatus() {
+        const applied = getApplied();
+        const appliedIds = new Set(applied.map((m) => m.id));
+        const pending = MIGRATIONS.filter((m) => !appliedIds.has(m.id));
+        const current = applied.length > 0 ? Math.max(...applied.map((m) => m.id)) : 0;
+        return { applied, pending, current };
+    }
+    function migrate(targetId) {
+        const { pending } = getStatus();
+        const target = targetId ?? Math.max(...MIGRATIONS.map((m) => m.id));
+        const toApply = pending
+            .filter((m) => m.id <= target)
+            .sort((a, b) => a.id - b.id);
+        const result = { applied: [], skipped: [], errors: [] };
+        for (const migration of toApply) {
+            try {
+                db.exec(migration.up);
+                db.run('INSERT OR IGNORE INTO _migrations (id, name) VALUES (?, ?)', [migration.id, migration.name]);
+                result.applied.push(migration.name);
+            }
+            catch (err) {
+                result.errors.push({
+                    name: migration.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                break; // stop on first error
+            }
+        }
+        return result;
+    }
+    function rollback(targetId) {
+        const { applied } = getStatus();
+        const toRollback = applied
+            .filter((m) => m.id > targetId)
+            .sort((a, b) => b.id - a.id); // reverse order
+        const result = { applied: [], skipped: [], errors: [] };
+        for (const record of toRollback) {
+            const migration = MIGRATIONS.find((m) => m.id === record.id);
+            if (!migration) {
+                result.skipped.push(`${record.name} (no migration definition found)`);
+                continue;
+            }
+            try {
+                db.exec(migration.down);
+                db.run('DELETE FROM _migrations WHERE id = ?', [migration.id]);
+                result.applied.push(migration.name);
+            }
+            catch (err) {
+                result.errors.push({
+                    name: migration.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                break;
+            }
+        }
+        return result;
+    }
+    return { ensureMigrationsTable, getApplied, getStatus, migrate, rollback };
+}

package/dist/sessions.d.ts

@@ -0,0 +1,88 @@
+/**
+ * ECC-003: Session Management
+ *
+ * Active session capabilities: branching, search, compaction, and metrics.
+ * Persists to disk (JSON file) matching selfheal persistence pattern.
+ * Integrates with hook system for lifecycle events.
+ */
+import type { HookSystem } from './hooks.js';
+export interface Session {
+    id: string;
+    parentId?: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+    status: SessionStatus;
+    metadata: Record<string, unknown>;
+    metrics: SessionMetrics;
+    entries: SessionEntry[];
+}
+export type SessionStatus = 'active' | 'paused' | 'completed' | 'archived' | 'branched';
+export interface SessionEntry {
+    id: string;
+    timestamp: string;
+    type: 'message' | 'tool_call' | 'tool_result' | 'checkpoint' | 'note';
+    content: string;
+    tokens?: number;
+    tags?: string[];
+}
+export interface SessionMetrics {
+    totalTokens: number;
+    entryCount: number;
+    toolCalls: number;
+    duration: number;
+    checkpoints: number;
+}
+export interface SessionSearchResult {
+    sessionId: string;
+    entryId: string;
+    content: string;
+    score: number;
+    timestamp: string;
+}
+export interface CompactionResult {
+    sessionId: string;
+    entriesBefore: number;
+    entriesAfter: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    summary: string;
+}
+export declare class SessionManager {
+    private sessions;
+    private dataFile;
+    private hooks;
+    constructor(dataDir?: string);
+    wireHooks(hooks: HookSystem): void;
+    create(name: string, metadata?: Record<string, unknown>): Session;
+    get(sessionId: string): Session | null;
+    list(filter?: {
+        status?: SessionStatus;
+    }): Session[];
+    addEntry(sessionId: string, entry: Omit<SessionEntry, 'id'>): SessionEntry | null;
+    branch(sessionId: string, branchName: string, options?: {
+        fromEntryIndex?: number;
+        freezeParent?: boolean;
+    }): Session | null;
+    search(query: string, options?: {
+        sessionId?: string;
+        limit?: number;
+    }): SessionSearchResult[];
+    compact(sessionId: string, summarizer?: (entries: SessionEntry[]) => string): CompactionResult | null;
+    getMetrics(sessionId: string): SessionMetrics | null;
+    getAggregateMetrics(): {
+        totalSessions: number;
+        activeSessions: number;
+        totalTokens: number;
+        totalEntries: number;
+        avgTokensPerSession: number;
+        avgEntriesPerSession: number;
+    };
+    updateStatus(sessionId: string, status: SessionStatus): boolean;
+    delete(sessionId: string): boolean;
+    clear(): void;
+    private defaultSummarize;
+    private load;
+    private save;
+}
+export declare function createSessionManager(dataDir?: string): SessionManager;