zouroboros-core 2.0.0

package/dist/hooks.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ECC-001: Lifecycle Hook System
+ *
+ * Event-driven hooks that fire at structured points in the conversation lifecycle.
+ * Hooks can be registered programmatically or loaded from hook definition files.
+ */
+export type LifecycleEvent = 'conversation.start' | 'conversation.end' | 'task.start' | 'task.complete' | 'task.fail' | 'tool.call' | 'tool.result' | 'memory.store' | 'memory.search' | 'memory.threshold' | 'persona.switch' | 'context.warning' | 'context.critical' | 'context.emergency' | 'swarm.wave.start' | 'swarm.wave.end' | 'command.execute' | 'session.branch' | 'session.compact' | 'instinct.fired' | 'error.recovery';
+export interface HookPayload {
+    event: LifecycleEvent;
+    timestamp: string;
+    data: Record<string, unknown>;
+    source?: string;
+}
+export type HookHandler = (payload: HookPayload) => void | Promise<void>;
+export interface HookRegistration {
+    id: string;
+    event: LifecycleEvent | LifecycleEvent[];
+    handler: HookHandler;
+    priority: number;
+    once: boolean;
+    enabled: boolean;
+    description?: string;
+}
+export type HookDefinitionAction = 'log' | 'memory_capture' | 'checkpoint' | 'notify' | 'custom';
+export interface HookDefinition {
+    id: string;
+    event: LifecycleEvent | LifecycleEvent[];
+    action: HookDefinitionAction;
+    priority?: number;
+    once?: boolean;
+    config?: Record<string, unknown>;
+    description?: string;
+}
+/** Handler factory for pluggable definition actions */
+export type DefinitionActionHandler = (def: HookDefinition) => HookHandler;
+export interface HookStats {
+    totalRegistered: number;
+    totalFired: number;
+    byEvent: Record<string, {
+        registered: number;
+        fired: number;
+        avgLatencyMs: number;
+    }>;
+    errors: number;
+    lastFired?: string;
+}
+export declare class HookSystem {
+    private hooks;
+    private eventIndex;
+    private actionHandlers;
+    private stats;
+    constructor();
+    /** Register a pluggable action handler for HookDefinition actions */
+    registerAction(action: string, factory: DefinitionActionHandler): void;
+    register(registration: HookRegistration): string;
+    on(event: LifecycleEvent | LifecycleEvent[], handler: HookHandler, options?: {
+        priority?: number;
+        description?: string;
+    }): string;
+    once(event: LifecycleEvent | LifecycleEvent[], handler: HookHandler, options?: {
+        priority?: number;
+    }): string;
+    off(hookId: string): boolean;
+    enable(hookId: string): boolean;
+    disable(hookId: string): boolean;
+    emit(event: LifecycleEvent, data?: Record<string, unknown>, source?: string): Promise<void>;
+    emitSync(event: LifecycleEvent, data?: Record<string, unknown>, source?: string): void;
+    loadDefinitions(definitions: HookDefinition[]): string[];
+    getStats(): HookStats;
+    listHooks(): Array<{
+        id: string;
+        events: LifecycleEvent[];
+        enabled: boolean;
+        priority: number;
+        description?: string;
+    }>;
+    clear(): void;
+}
+export declare function getHookSystem(): HookSystem;
+export declare function createHookSystem(): HookSystem;
+export declare function resetGlobalHooks(): void;

package/dist/hooks.js

@@ -0,0 +1,231 @@
+/**
+ * ECC-001: Lifecycle Hook System
+ *
+ * Event-driven hooks that fire at structured points in the conversation lifecycle.
+ * Hooks can be registered programmatically or loaded from hook definition files.
+ */
+export class HookSystem {
+    hooks = new Map();
+    eventIndex = new Map();
+    actionHandlers = new Map();
+    stats = { totalFired: 0, byEvent: {}, errors: 0 };
+    constructor() {
+        // Register built-in action handlers
+        this.registerAction('log', (def) => (payload) => {
+            console.log(`[hook:${def.id}] ${payload.event}`, JSON.stringify(payload.data).slice(0, 200));
+        });
+        this.registerAction('notify', (def) => (payload) => {
+            console.log(`[hook:${def.id}] Notification: ${payload.event}`, payload.data);
+        });
+        // memory_capture, checkpoint, custom — default to log until wired by integration layer
+        this.registerAction('memory_capture', (def) => (payload) => {
+            console.log(`[hook:${def.id}] Memory capture triggered by ${payload.event}`);
+        });
+        this.registerAction('checkpoint', (def) => (payload) => {
+            console.log(`[hook:${def.id}] Checkpoint at ${payload.event}`);
+        });
+        this.registerAction('custom', (def) => (payload) => {
+            console.log(`[hook:${def.id}] Custom action for ${payload.event}`);
+        });
+    }
+    /** Register a pluggable action handler for HookDefinition actions */
+    registerAction(action, factory) {
+        this.actionHandlers.set(action, factory);
+    }
+    register(registration) {
+        this.hooks.set(registration.id, registration);
+        const events = Array.isArray(registration.event) ? registration.event : [registration.event];
+        for (const event of events) {
+            if (!this.eventIndex.has(event)) {
+                this.eventIndex.set(event, new Set());
+            }
+            this.eventIndex.get(event).add(registration.id);
+        }
+        return registration.id;
+    }
+    on(event, handler, options) {
+        const id = `hook-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.register({
+            id,
+            event,
+            handler,
+            priority: options?.priority ?? 100,
+            once: false,
+            enabled: true,
+            description: options?.description,
+        });
+        return id;
+    }
+    once(event, handler, options) {
+        const id = `hook-once-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.register({
+            id,
+            event,
+            handler,
+            priority: options?.priority ?? 100,
+            once: true,
+            enabled: true,
+        });
+        return id;
+    }
+    off(hookId) {
+        const hook = this.hooks.get(hookId);
+        if (!hook)
+            return false;
+        this.hooks.delete(hookId);
+        const events = Array.isArray(hook.event) ? hook.event : [hook.event];
+        for (const event of events) {
+            this.eventIndex.get(event)?.delete(hookId);
+        }
+        return true;
+    }
+    enable(hookId) {
+        const hook = this.hooks.get(hookId);
+        if (!hook)
+            return false;
+        hook.enabled = true;
+        return true;
+    }
+    disable(hookId) {
+        const hook = this.hooks.get(hookId);
+        if (!hook)
+            return false;
+        hook.enabled = false;
+        return true;
+    }
+    async emit(event, data = {}, source) {
+        const hookIds = this.eventIndex.get(event);
+        if (!hookIds || hookIds.size === 0)
+            return;
+        const payload = {
+            event,
+            timestamp: new Date().toISOString(),
+            data,
+            source,
+        };
+        // Sort by priority
+        const hooks = [...hookIds]
+            .map(id => this.hooks.get(id))
+            .filter(h => h && h.enabled)
+            .sort((a, b) => a.priority - b.priority);
+        const start = Date.now();
+        for (const hook of hooks) {
+            try {
+                await hook.handler(payload);
+            }
+            catch {
+                this.stats.errors++;
+            }
+            if (hook.once) {
+                this.off(hook.id);
+            }
+        }
+        const latency = Date.now() - start;
+        this.stats.totalFired++;
+        this.stats.lastFired = payload.timestamp;
+        if (!this.stats.byEvent[event]) {
+            this.stats.byEvent[event] = { fired: 0, totalLatency: 0 };
+        }
+        this.stats.byEvent[event].fired++;
+        this.stats.byEvent[event].totalLatency += latency;
+    }
+    emitSync(event, data = {}, source) {
+        const hookIds = this.eventIndex.get(event);
+        if (!hookIds || hookIds.size === 0)
+            return;
+        const payload = {
+            event,
+            timestamp: new Date().toISOString(),
+            data,
+            source,
+        };
+        const hooks = [...hookIds]
+            .map(id => this.hooks.get(id))
+            .filter(h => h && h.enabled)
+            .sort((a, b) => a.priority - b.priority);
+        for (const hook of hooks) {
+            try {
+                const result = hook.handler(payload);
+                // If handler returns a promise, catch errors without blocking
+                if (result && typeof result.catch === 'function') {
+                    result.catch(() => { this.stats.errors++; });
+                }
+            }
+            catch {
+                this.stats.errors++;
+            }
+            if (hook.once) {
+                this.off(hook.id);
+            }
+        }
+        this.stats.totalFired++;
+        this.stats.lastFired = payload.timestamp;
+        if (!this.stats.byEvent[event]) {
+            this.stats.byEvent[event] = { fired: 0, totalLatency: 0 };
+        }
+        this.stats.byEvent[event].fired++;
+    }
+    loadDefinitions(definitions) {
+        const ids = [];
+        for (const def of definitions) {
+            const factory = this.actionHandlers.get(def.action);
+            const handler = factory ? factory(def) : (() => { });
+            const id = this.register({
+                id: def.id,
+                event: def.event,
+                handler,
+                priority: def.priority ?? 100,
+                once: def.once ?? false,
+                enabled: true,
+                description: def.description,
+            });
+            ids.push(id);
+        }
+        return ids;
+    }
+    getStats() {
+        const byEvent = {};
+        for (const [event, hookIds] of this.eventIndex) {
+            const eventStats = this.stats.byEvent[event] || { fired: 0, totalLatency: 0 };
+            byEvent[event] = {
+                registered: hookIds.size,
+                fired: eventStats.fired,
+                avgLatencyMs: eventStats.fired > 0 ? eventStats.totalLatency / eventStats.fired : 0,
+            };
+        }
+        return {
+            totalRegistered: this.hooks.size,
+            totalFired: this.stats.totalFired,
+            byEvent,
+            errors: this.stats.errors,
+            lastFired: this.stats.lastFired,
+        };
+    }
+    listHooks() {
+        return [...this.hooks.values()].map(h => ({
+            id: h.id,
+            events: Array.isArray(h.event) ? h.event : [h.event],
+            enabled: h.enabled,
+            priority: h.priority,
+            description: h.description,
+        }));
+    }
+    clear() {
+        this.hooks.clear();
+        this.eventIndex.clear();
+    }
+}
+// Singleton for ecosystem-wide hook system
+let _globalHooks = null;
+export function getHookSystem() {
+    if (!_globalHooks) {
+        _globalHooks = new HookSystem();
+    }
+    return _globalHooks;
+}
+export function createHookSystem() {
+    return new HookSystem();
+}
+export function resetGlobalHooks() {
+    _globalHooks = null;
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Zouroboros Core
+ *
+ * Core types, constants, and utilities shared across all Zouroboros packages.
+ *
+ * @module zouroboros-core
+ */
+export * from './types.js';
+export * from './constants.js';
+export * from './config/loader.js';
+export * from './config/schema.js';
+export * from './backup.js';
+export * from './errors.js';
+export * from './migrations.js';
+export * from './hooks.js';
+export * from './token-budget.js';
+export * from './commands.js';
+export * from './sessions.js';
+export * from './instincts.js';
+export declare const VERSION = "2.0.0";

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * Zouroboros Core
+ *
+ * Core types, constants, and utilities shared across all Zouroboros packages.
+ *
+ * @module zouroboros-core
+ */
+export * from './types.js';
+export * from './constants.js';
+export * from './config/loader.js';
+export * from './config/schema.js';
+export * from './backup.js';
+export * from './errors.js';
+export * from './migrations.js';
+export * from './hooks.js';
+export * from './token-budget.js';
+export * from './commands.js';
+export * from './sessions.js';
+export * from './instincts.js';
+// Version
+export const VERSION = '2.0.0';

package/dist/instincts.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 type { HookSystem, LifecycleEvent } from './hooks.js';
+export interface Instinct {
+    id: string;
+    name: string;
+    description: string;
+    confidence: number;
+    pattern: PatternSpec;
+    trigger: TriggerSpec;
+    resolution: string;
+    evidenceCount: number;
+    lastSeen: string;
+    createdAt: string;
+    status: InstinctStatus;
+    tags: string[];
+}
+export type InstinctStatus = 'candidate' | 'active' | 'suspended' | 'retired';
+export interface PatternSpec {
+    type: 'error_repeat' | 'tool_sequence' | 'context_drift' | 'custom';
+    signature: string;
+    frequency: number;
+    windowSize: number;
+}
+export interface TriggerSpec {
+    event: LifecycleEvent | '*';
+    condition: string;
+    cooldownMs: number;
+}
+export interface PatternEvidence {
+    timestamp: string;
+    sessionId?: string;
+    context: string;
+    matchStrength: number;
+}
+export interface InstinctMatch {
+    instinct: Instinct;
+    confidence: number;
+    evidence: PatternEvidence[];
+}
+export interface ExtractionResult {
+    patternsDetected: number;
+    instinctsCreated: number;
+    instinctsUpdated: number;
+    details: Array<{
+        id: string;
+        action: 'created' | 'updated' | 'skipped';
+        reason?: string;
+    }>;
+}
+export declare class InstinctEngine {
+    private instincts;
+    private evidence;
+    private lastFired;
+    private dataFile;
+    private hooks;
+    private pendingObservations;
+    constructor(dataDir?: string);
+    wireHooks(hooks: HookSystem): void;
+    /** Record a single observation for later batch extraction */
+    recordObservation(obs: {
+        context: string;
+        outcome: string;
+        timestamp: string;
+        sessionId?: string;
+    }): void;
+    register(instinct: Instinct): void;
+    get(id: string): Instinct | null;
+    list(filter?: {
+        status?: InstinctStatus;
+        minConfidence?: number;
+        tag?: string;
+    }): Instinct[];
+    addEvidence(instinctId: string, ev: PatternEvidence): boolean;
+    /** Record a negative match — the instinct fired but was wrong */
+    rejectMatch(instinctId: string): boolean;
+    match(context: string, event?: string): InstinctMatch[];
+    fire(instinctId: string): boolean;
+    extract(observations: Array<{
+        context: string;
+        outcome: string;
+        timestamp: string;
+        sessionId?: string;
+    }>): ExtractionResult;
+    suspend(id: string): boolean;
+    activate(id: string): boolean;
+    retire(id: string): boolean;
+    remove(id: string): boolean;
+    getStats(): {
+        total: number;
+        byStatus: Record<InstinctStatus, number>;
+        avgConfidence: number;
+        totalEvidence: number;
+    };
+    exportInstinct(id: string): object | null;
+    importInstinct(data: Instinct & {
+        evidence?: PatternEvidence[];
+    }): void;
+    private calculateConfidence;
+    private computeMatch;
+    /**
+     * Group observations by context similarity using Jaccard index on word sets.
+     */
+    private groupByContextSimilarity;
+    private jaccardSimilarity;
+    private generateSignature;
+    private findBySignature;
+    private load;
+    private save;
+}
+export declare function createInstinctEngine(dataDir?: string): InstinctEngine;