zouroboros-core 2.0.0

package/dist/sessions.js

@@ -0,0 +1,275 @@
+/**
+ * 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 { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+export class SessionManager {
+    sessions = new Map();
+    dataFile = null;
+    hooks = null;
+    constructor(dataDir) {
+        if (dataDir) {
+            mkdirSync(dataDir, { recursive: true });
+            this.dataFile = join(dataDir, 'sessions.json');
+            this.load();
+        }
+    }
+    wireHooks(hooks) {
+        this.hooks = hooks;
+    }
+    create(name, metadata = {}) {
+        const id = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const session = {
+            id,
+            name,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            status: 'active',
+            metadata,
+            metrics: { totalTokens: 0, entryCount: 0, toolCalls: 0, duration: 0, checkpoints: 0 },
+            entries: [],
+        };
+        this.sessions.set(id, session);
+        this.save();
+        return session;
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId) || null;
+    }
+    list(filter) {
+        let sessions = [...this.sessions.values()];
+        if (filter?.status) {
+            sessions = sessions.filter(s => s.status === filter.status);
+        }
+        return sessions.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    addEntry(sessionId, entry) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return null;
+        const fullEntry = {
+            id: `entry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            ...entry,
+        };
+        session.entries.push(fullEntry);
+        session.updatedAt = new Date().toISOString();
+        // Update metrics
+        session.metrics.entryCount = session.entries.length;
+        if (entry.tokens)
+            session.metrics.totalTokens += entry.tokens;
+        if (entry.type === 'tool_call')
+            session.metrics.toolCalls++;
+        if (entry.type === 'checkpoint')
+            session.metrics.checkpoints++;
+        if (session.entries.length >= 2) {
+            const first = new Date(session.entries[0].timestamp).getTime();
+            const last = new Date(fullEntry.timestamp).getTime();
+            session.metrics.duration = last - first;
+        }
+        this.save();
+        return fullEntry;
+    }
+    branch(sessionId, branchName, options) {
+        const parent = this.sessions.get(sessionId);
+        if (!parent)
+            return null;
+        const fromEntryIndex = options?.fromEntryIndex;
+        const freezeParent = options?.freezeParent ?? false;
+        const entrySlice = fromEntryIndex !== undefined
+            ? parent.entries.slice(0, fromEntryIndex)
+            : [...parent.entries];
+        const branchId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const branch = {
+            id: branchId,
+            parentId: sessionId,
+            name: branchName,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            status: 'active',
+            metadata: { ...parent.metadata, branchedFrom: sessionId },
+            metrics: { ...parent.metrics },
+            entries: entrySlice.map(e => ({ ...e })),
+        };
+        // Recalculate metrics for branch
+        branch.metrics.entryCount = branch.entries.length;
+        branch.metrics.totalTokens = branch.entries.reduce((sum, e) => sum + (e.tokens || 0), 0);
+        branch.metrics.toolCalls = branch.entries.filter(e => e.type === 'tool_call').length;
+        branch.metrics.checkpoints = branch.entries.filter(e => e.type === 'checkpoint').length;
+        // Only freeze parent if explicitly requested
+        if (freezeParent) {
+            parent.status = 'branched';
+        }
+        this.sessions.set(branchId, branch);
+        this.save();
+        // Emit hook event
+        if (this.hooks) {
+            this.hooks.emit('session.branch', {
+                parentId: sessionId,
+                branchId,
+                branchName,
+                entryCount: branch.entries.length,
+            }, 'session-manager').catch(() => { });
+        }
+        return branch;
+    }
+    search(query, options) {
+        const queryWords = query.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter(w => w.length >= 2);
+        if (queryWords.length === 0)
+            return [];
+        const limit = options?.limit || 20;
+        const results = [];
+        const sessionsToSearch = options?.sessionId
+            ? [options.sessionId]
+            : [...this.sessions.keys()];
+        for (const sid of sessionsToSearch) {
+            const session = this.sessions.get(sid);
+            if (!session)
+                continue;
+            for (const entry of session.entries) {
+                const entryText = entry.content.toLowerCase();
+                const matchCount = queryWords.filter(qw => entryText.includes(qw)).length;
+                if (matchCount > 0) {
+                    const score = matchCount / queryWords.length;
+                    results.push({
+                        sessionId: sid,
+                        entryId: entry.id,
+                        content: entry.content.slice(0, 200),
+                        score,
+                        timestamp: entry.timestamp,
+                    });
+                }
+            }
+        }
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    compact(sessionId, summarizer) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.entries.length === 0)
+            return null;
+        const entriesBefore = session.entries.length;
+        const tokensBefore = session.metrics.totalTokens;
+        // Keep last 20% of entries, summarize older ones
+        const keepCount = Math.max(Math.ceil(session.entries.length * 0.2), 1);
+        const oldEntries = session.entries.slice(0, -keepCount);
+        const keptEntries = session.entries.slice(-keepCount);
+        if (oldEntries.length === 0)
+            return null;
+        const summary = summarizer
+            ? summarizer(oldEntries)
+            : this.defaultSummarize(oldEntries);
+        const summaryEntry = {
+            id: `entry-compact-${Date.now()}`,
+            timestamp: oldEntries[0]?.timestamp || new Date().toISOString(),
+            type: 'note',
+            content: `[Compacted ${oldEntries.length} entries] ${summary}`,
+            tokens: Math.ceil(summary.length / 4),
+        };
+        session.entries = [summaryEntry, ...keptEntries];
+        session.metrics.entryCount = session.entries.length;
+        session.metrics.totalTokens = session.entries.reduce((sum, e) => sum + (e.tokens || 0), 0);
+        session.updatedAt = new Date().toISOString();
+        this.save();
+        const result = {
+            sessionId,
+            entriesBefore,
+            entriesAfter: session.entries.length,
+            tokensBefore,
+            tokensAfter: session.metrics.totalTokens,
+            summary,
+        };
+        // Emit hook event
+        if (this.hooks) {
+            this.hooks.emit('session.compact', {
+                sessionId,
+                entriesBefore,
+                entriesAfter: result.entriesAfter,
+                tokensSaved: tokensBefore - result.tokensAfter,
+            }, 'session-manager').catch(() => { });
+        }
+        return result;
+    }
+    getMetrics(sessionId) {
+        const session = this.sessions.get(sessionId);
+        return session ? { ...session.metrics } : null;
+    }
+    getAggregateMetrics() {
+        const sessions = [...this.sessions.values()];
+        const totalTokens = sessions.reduce((sum, s) => sum + s.metrics.totalTokens, 0);
+        const totalEntries = sessions.reduce((sum, s) => sum + s.metrics.entryCount, 0);
+        return {
+            totalSessions: sessions.length,
+            activeSessions: sessions.filter(s => s.status === 'active').length,
+            totalTokens,
+            totalEntries,
+            avgTokensPerSession: sessions.length > 0 ? totalTokens / sessions.length : 0,
+            avgEntriesPerSession: sessions.length > 0 ? totalEntries / sessions.length : 0,
+        };
+    }
+    updateStatus(sessionId, status) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return false;
+        session.status = status;
+        session.updatedAt = new Date().toISOString();
+        this.save();
+        return true;
+    }
+    delete(sessionId) {
+        const deleted = this.sessions.delete(sessionId);
+        if (deleted)
+            this.save();
+        return deleted;
+    }
+    clear() {
+        this.sessions.clear();
+        this.save();
+    }
+    defaultSummarize(entries) {
+        const types = new Map();
+        for (const e of entries) {
+            types.set(e.type, (types.get(e.type) || 0) + 1);
+        }
+        const parts = [...types.entries()]
+            .map(([type, count]) => `${count} ${type}${count > 1 ? 's' : ''}`)
+            .join(', ');
+        const totalTokens = entries.reduce((sum, e) => sum + (e.tokens || 0), 0);
+        // Include content snippets from key entries
+        const keyEntries = entries
+            .filter(e => e.type === 'message' || e.type === 'tool_call')
+            .slice(0, 3)
+            .map(e => e.content.slice(0, 60));
+        const snippets = keyEntries.length > 0
+            ? ` Key items: ${keyEntries.join('; ')}`
+            : '';
+        return `${parts}. ${totalTokens} tokens total.${snippets}`;
+    }
+    load() {
+        if (!this.dataFile || !existsSync(this.dataFile))
+            return;
+        try {
+            const store = JSON.parse(readFileSync(this.dataFile, 'utf-8'));
+            for (const session of store.sessions) {
+                this.sessions.set(session.id, session);
+            }
+        }
+        catch { /* start fresh if corrupt */ }
+    }
+    save() {
+        if (!this.dataFile)
+            return;
+        const store = {
+            version: '1.0.0',
+            sessions: [...this.sessions.values()],
+        };
+        writeFileSync(this.dataFile, JSON.stringify(store, null, 2));
+    }
+}
+export function createSessionManager(dataDir) {
+    return new SessionManager(dataDir);
+}

package/dist/token-budget.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ECC-005: Token Budget Hook Wiring
+ *
+ * Systematic token optimization with proactive checkpointing.
+ * Monitors context usage and triggers compression/checkpoint hooks.
+ */
+import type { HookSystem } from './hooks.js';
+export interface TokenBudgetConfig {
+    maxTokens: number;
+    warningThreshold: number;
+    criticalThreshold: number;
+    emergencyThreshold: number;
+    compressionStrategy: CompressionStrategy;
+}
+export type CompressionStrategy = 'progressive' | 'aggressive' | 'selective';
+export interface TokenState {
+    currentTokens: number;
+    maxTokens: number;
+    utilizationPercent: number;
+    level: 'normal' | 'warning' | 'critical' | 'emergency';
+    lastCheckpoint?: string;
+    compressionCount: number;
+    savedTokens: number;
+}
+export interface CompressionRecord {
+    strategy: CompressionStrategy;
+    tokensBefore: number;
+    tokensAfter: number;
+    saved: number;
+    sections: string[];
+    timestamp: string;
+}
+export interface CheckpointData {
+    timestamp: string;
+    tokenState: TokenState;
+    activeTaskId?: string;
+    context: Record<string, unknown>;
+}
+export declare class TokenBudgetManager {
+    private config;
+    private hooks;
+    private state;
+    private checkpoints;
+    private compressionHistory;
+    constructor(config?: Partial<TokenBudgetConfig>, hooks?: HookSystem);
+    update(currentTokens: number): TokenState;
+    getState(): TokenState;
+    checkpoint(context?: Record<string, unknown>, activeTaskId?: string): CheckpointData;
+    /**
+     * Record a compression that was performed externally.
+     * The caller is responsible for the actual context reduction —
+     * this method tracks the bookkeeping and updates token state.
+     */
+    recordCompression(actualTokensAfter: number, sections: string[]): CompressionRecord;
+    /**
+     * Get the recommended compression target based on current strategy and state.
+     * Returns the number of tokens that should remain after compression.
+     */
+    getCompressionTarget(): {
+        targetTokens: number;
+        reductionPercent: number;
+    };
+    getRecommendation(): {
+        action: string;
+        urgency: 'none' | 'low' | 'medium' | 'high';
+        details: string;
+    };
+    getCheckpoints(): CheckpointData[];
+    getCompressionHistory(): CompressionRecord[];
+    shouldPauseSwarm(): boolean;
+    shouldCompress(): boolean;
+    wireHooks(hooks: HookSystem): void;
+    private computeLevel;
+    private onLevelChange;
+}
+export declare function createTokenBudget(config?: Partial<TokenBudgetConfig>, hooks?: HookSystem): TokenBudgetManager;

package/dist/token-budget.js

@@ -0,0 +1,196 @@
+/**
+ * ECC-005: Token Budget Hook Wiring
+ *
+ * Systematic token optimization with proactive checkpointing.
+ * Monitors context usage and triggers compression/checkpoint hooks.
+ */
+const DEFAULT_CONFIG = {
+    maxTokens: 200000,
+    warningThreshold: 0.70,
+    criticalThreshold: 0.85,
+    emergencyThreshold: 0.95,
+    compressionStrategy: 'progressive',
+};
+export class TokenBudgetManager {
+    config;
+    hooks;
+    state;
+    checkpoints = [];
+    compressionHistory = [];
+    constructor(config, hooks) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.hooks = hooks || null;
+        this.state = {
+            currentTokens: 0,
+            maxTokens: this.config.maxTokens,
+            utilizationPercent: 0,
+            level: 'normal',
+            compressionCount: 0,
+            savedTokens: 0,
+        };
+    }
+    update(currentTokens) {
+        this.state.currentTokens = currentTokens;
+        this.state.maxTokens = this.config.maxTokens;
+        this.state.utilizationPercent = currentTokens / this.config.maxTokens;
+        const prevLevel = this.state.level;
+        this.state.level = this.computeLevel();
+        // Fire hooks on level transitions
+        if (this.hooks && prevLevel !== this.state.level) {
+            this.onLevelChange(prevLevel, this.state.level);
+        }
+        return { ...this.state };
+    }
+    getState() {
+        return { ...this.state };
+    }
+    checkpoint(context = {}, activeTaskId) {
+        const cp = {
+            timestamp: new Date().toISOString(),
+            tokenState: { ...this.state },
+            activeTaskId,
+            context,
+        };
+        this.checkpoints.push(cp);
+        if (this.checkpoints.length > 50) {
+            this.checkpoints = this.checkpoints.slice(-50);
+        }
+        this.state.lastCheckpoint = cp.timestamp;
+        return cp;
+    }
+    /**
+     * Record a compression that was performed externally.
+     * The caller is responsible for the actual context reduction —
+     * this method tracks the bookkeeping and updates token state.
+     */
+    recordCompression(actualTokensAfter, sections) {
+        const tokensBefore = this.state.currentTokens;
+        const saved = tokensBefore - actualTokensAfter;
+        const record = {
+            strategy: this.config.compressionStrategy,
+            tokensBefore,
+            tokensAfter: actualTokensAfter,
+            saved: Math.max(saved, 0),
+            sections,
+            timestamp: new Date().toISOString(),
+        };
+        this.state.currentTokens = actualTokensAfter;
+        this.state.compressionCount++;
+        this.state.savedTokens += record.saved;
+        this.state.utilizationPercent = this.state.currentTokens / this.config.maxTokens;
+        this.state.level = this.computeLevel();
+        this.compressionHistory.push(record);
+        if (this.compressionHistory.length > 20) {
+            this.compressionHistory = this.compressionHistory.slice(-20);
+        }
+        return record;
+    }
+    /**
+     * Get the recommended compression target based on current strategy and state.
+     * Returns the number of tokens that should remain after compression.
+     */
+    getCompressionTarget() {
+        const current = this.state.currentTokens;
+        let reductionPercent;
+        switch (this.config.compressionStrategy) {
+            case 'progressive':
+                reductionPercent = 0.20;
+                break;
+            case 'aggressive':
+                reductionPercent = 0.40;
+                break;
+            case 'selective':
+                reductionPercent = 0.15;
+                break;
+        }
+        return {
+            targetTokens: Math.floor(current * (1 - reductionPercent)),
+            reductionPercent,
+        };
+    }
+    getRecommendation() {
+        switch (this.state.level) {
+            case 'emergency':
+                return {
+                    action: 'immediate_checkpoint_and_compress',
+                    urgency: 'high',
+                    details: `At ${(this.state.utilizationPercent * 100).toFixed(1)}% — checkpoint now and aggressively compress. Pause swarm waves.`,
+                };
+            case 'critical':
+                return {
+                    action: 'checkpoint_and_compress',
+                    urgency: 'medium',
+                    details: `At ${(this.state.utilizationPercent * 100).toFixed(1)}% — create checkpoint, apply progressive compression.`,
+                };
+            case 'warning':
+                return {
+                    action: 'prepare_checkpoint',
+                    urgency: 'low',
+                    details: `At ${(this.state.utilizationPercent * 100).toFixed(1)}% — prepare checkpoint data, summarize old context.`,
+                };
+            default:
+                return { action: 'none', urgency: 'none', details: 'Token budget healthy.' };
+        }
+    }
+    getCheckpoints() {
+        return [...this.checkpoints];
+    }
+    getCompressionHistory() {
+        return [...this.compressionHistory];
+    }
+    shouldPauseSwarm() {
+        return this.state.level === 'emergency' || this.state.level === 'critical';
+    }
+    shouldCompress() {
+        return this.state.level === 'critical' || this.state.level === 'emergency';
+    }
+    wireHooks(hooks) {
+        this.hooks = hooks;
+        // Auto-checkpoint on conversation end
+        hooks.on('conversation.end', (payload) => {
+            this.checkpoint({ reason: 'conversation_end', ...payload.data });
+        }, { priority: 10, description: 'Token budget auto-checkpoint on conversation end' });
+        // Monitor context warnings — don't overwrite actual token state,
+        // only trigger a checkpoint if we're already at warning level
+        hooks.on('context.warning', () => {
+            if (this.shouldCompress()) {
+                this.checkpoint({ reason: 'context_warning_auto' });
+            }
+        }, { priority: 5, description: 'Token budget context warning handler' });
+        hooks.on('context.critical', () => {
+            this.checkpoint({ reason: 'context_critical_auto' });
+        }, { priority: 5, description: 'Token budget context critical handler' });
+    }
+    computeLevel() {
+        const util = this.state.utilizationPercent;
+        if (util >= this.config.emergencyThreshold)
+            return 'emergency';
+        if (util >= this.config.criticalThreshold)
+            return 'critical';
+        if (util >= this.config.warningThreshold)
+            return 'warning';
+        return 'normal';
+    }
+    onLevelChange(from, to) {
+        if (!this.hooks)
+            return;
+        const eventMap = {
+            warning: 'context.warning',
+            critical: 'context.critical',
+            emergency: 'context.emergency',
+        };
+        const event = eventMap[to];
+        if (event) {
+            this.hooks.emit(event, {
+                from,
+                to,
+                utilization: this.state.utilizationPercent,
+                currentTokens: this.state.currentTokens,
+                maxTokens: this.config.maxTokens,
+            }, 'token-budget');
+        }
+    }
+}
+export function createTokenBudget(config, hooks) {
+    return new TokenBudgetManager(config, hooks);
+}