@brutalist/mcp 0.6.0 → 0.6.1

package/dist/streaming/intelligent-buffer.d.ts

@@ -0,0 +1,141 @@
+import { StreamingEvent } from '../cli-agents.js';
+/**
+ * Priority level for events
+ */
+export type EventPriority = 'immediate' | 'high' | 'normal' | 'low';
+/**
+ * Buffer state for monitoring and metrics
+ */
+interface BufferState {
+    sessionId: string;
+    totalEvents: number;
+    pendingEvents: number;
+    lastFlush: number;
+    flushCount: number;
+    backpressure: boolean;
+    memoryUsage: number;
+}
+/**
+ * Event batch for delivery
+ */
+export interface EventBatch {
+    sessionId: string;
+    events: StreamingEvent[];
+    priority: EventPriority;
+    batchId: string;
+    createdAt: number;
+}
+/**
+ * Intelligent buffering system with adaptive throttling and content-aware batching
+ *
+ * Features:
+ * - Priority-based queuing with immediate delivery for critical events
+ * - Adaptive throttling based on content type and system load
+ * - Content coalescence to reduce noise
+ * - Memory-bounded circular buffers
+ * - Backpressure handling
+ * - Real-time metrics and monitoring
+ */
+export declare class IntelligentBuffer {
+    private buffers;
+    private flushTimers;
+    private states;
+    private backlog;
+    private readonly BUFFERING_RULES;
+    private readonly DEFAULT_RULE;
+    private readonly MAX_BUFFER_SIZE;
+    private readonly MAX_MEMORY_MB;
+    private readonly BACKLOG_SIZE;
+    constructor();
+    /**
+     * Add event to buffer with intelligent routing
+     */
+    add(event: StreamingEvent): void;
+    /**
+     * Force flush of all pending events for a session
+     */
+    flush(sessionId: string, priority?: EventPriority): EventBatch | null;
+    /**
+     * Get backlog events for late subscribers
+     */
+    getBacklog(sessionId: string, limit?: number): StreamingEvent[];
+    /**
+     * Get buffer state for monitoring
+     */
+    getState(sessionId: string): BufferState | null;
+    /**
+     * Get all active sessions
+     */
+    getActiveSessions(): string[];
+    /**
+     * Cleanup session resources
+     */
+    cleanup(sessionId: string): void;
+    /**
+     * Get total memory usage across all sessions
+     */
+    getTotalMemoryUsage(): number;
+    /**
+     * Get system-wide metrics
+     */
+    getMetrics(): {
+        activeSessions: number;
+        totalEvents: number;
+        totalMemoryMB: number;
+        backpressureSessions: number;
+    };
+    /**
+     * Classify event for buffering rules
+     */
+    private classifyEvent;
+    /**
+     * Get event priority for backpressure handling
+     */
+    private getEventPriority;
+    /**
+     * Schedule flush based on buffering rule
+     */
+    private scheduleFlush;
+    /**
+     * Apply content coalescence to reduce noise
+     */
+    private applyCoalescence;
+    /**
+     * Generate coalescence key for grouping similar events
+     */
+    private getCoalescenceKey;
+    /**
+     * Merge similar events into single event
+     */
+    private mergeEvents;
+    /**
+     * Get or create buffer for session
+     */
+    private getOrCreateBuffer;
+    /**
+     * Get or create buffer state
+     */
+    private getOrCreateState;
+    /**
+     * Add event to backlog for late subscribers
+     */
+    private addToBacklog;
+    /**
+     * Estimate memory usage for session
+     */
+    private estimateMemoryUsage;
+    /**
+     * Handle memory pressure by dropping low priority events
+     */
+    private handleMemoryPressure;
+    /**
+     * Clean up stale sessions (no activity for > 1 hour)
+     */
+    private cleanupStaleSessions;
+    /**
+     * Deliver batch to subscribers (to be implemented by transport layer)
+     */
+    private deliverBatch;
+}
+export {};
+//# sourceMappingURL=intelligent-buffer.d.ts.map

package/dist/streaming/intelligent-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intelligent-buffer.d.ts","sourceRoot":"","sources":["../../src/streaming/intelligent-buffer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAyIpE;;GAEG;AACH,UAAU,WAAW;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAoD;IACnE,OAAO,CAAC,WAAW,CAAqC;IACxD,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,OAAO,CAAqD;IAGpE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAgE9B;IAEF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAK3B;IAGF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAM;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAO;;IAOpC;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IA8ChC;;OAEG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,UAAU,GAAG,IAAI;IAyCrE;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE;IAS/D;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAI/C;;OAEG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAI7B;;OAEG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAmBhC;;OAEG;IACH,mBAAmB,IAAI,MAAM;IAK7B;;OAEG;IACH,UAAU,IAAI;QACZ,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,oBAAoB,EAAE,MAAM,CAAC;KAC9B;IAWD;;OAEG;IACH,OAAO,CAAC,aAAa;IAwCrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;OAEG;IACH,OAAO,CAAC,aAAa;IAoCrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA8BxB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAkBnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAexB;;OAEG;IACH,OAAO,CAAC,YAAY;IAUpB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAmB3B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;OAEG;IACH,OAAO,CAAC,YAAY;CAMrB"}

package/dist/streaming/intelligent-buffer.js

@@ -0,0 +1,555 @@
+import { logger } from '../logger.js';
+/**
+ * Circular buffer for memory-efficient event storage
+ */
+class CircularBuffer {
+    buffer;
+    size;
+    head = 0;
+    tail = 0;
+    count = 0;
+    constructor(capacity) {
+        this.size = capacity;
+        this.buffer = new Array(capacity);
+    }
+    add(item) {
+        this.buffer[this.tail] = item;
+        this.tail = (this.tail + 1) % this.size;
+        if (this.count < this.size) {
+            this.count++;
+        }
+        else {
+            // Buffer full, move head
+            this.head = (this.head + 1) % this.size;
+        }
+    }
+    flush() {
+        const items = [];
+        while (this.count > 0) {
+            items.push(this.buffer[this.head]);
+            this.head = (this.head + 1) % this.size;
+            this.count--;
+        }
+        return items;
+    }
+    peek(count = this.count) {
+        const items = [];
+        let current = this.head;
+        for (let i = 0; i < Math.min(count, this.count); i++) {
+            items.push(this.buffer[current]);
+            current = (current + 1) % this.size;
+        }
+        return items;
+    }
+    getCount() {
+        return this.count;
+    }
+    isFull() {
+        return this.count === this.size;
+    }
+}
+/**
+ * Priority queue implementation for event batching
+ */
+class PriorityQueue {
+    queues = new Map();
+    priorities = ['immediate', 'high', 'normal', 'low'];
+    constructor() {
+        this.priorities.forEach(priority => {
+            this.queues.set(priority, []);
+        });
+    }
+    enqueue(item, priority) {
+        const queue = this.queues.get(priority);
+        if (queue) {
+            queue.push(item);
+        }
+    }
+    dequeue() {
+        for (const priority of this.priorities) {
+            const queue = this.queues.get(priority);
+            if (queue && queue.length > 0) {
+                const item = queue.shift();
+                return { item, priority };
+            }
+        }
+        return null;
+    }
+    dequeueAll(priority) {
+        if (priority) {
+            const queue = this.queues.get(priority);
+            if (queue) {
+                const items = [...queue];
+                queue.length = 0;
+                return items;
+            }
+            return [];
+        }
+        // Dequeue all items in priority order
+        const items = [];
+        for (const p of this.priorities) {
+            const queue = this.queues.get(p);
+            if (queue) {
+                items.push(...queue);
+                queue.length = 0;
+            }
+        }
+        return items;
+    }
+    size(priority) {
+        if (priority) {
+            return this.queues.get(priority)?.length || 0;
+        }
+        return Array.from(this.queues.values()).reduce((sum, queue) => sum + queue.length, 0);
+    }
+    isEmpty() {
+        return this.size() === 0;
+    }
+}
+/**
+ * Intelligent buffering system with adaptive throttling and content-aware batching
+ *
+ * Features:
+ * - Priority-based queuing with immediate delivery for critical events
+ * - Adaptive throttling based on content type and system load
+ * - Content coalescence to reduce noise
+ * - Memory-bounded circular buffers
+ * - Backpressure handling
+ * - Real-time metrics and monitoring
+ */
+export class IntelligentBuffer {
+    buffers = new Map();
+    flushTimers = new Map();
+    states = new Map();
+    backlog = new Map();
+    // Adaptive buffering rules based on content analysis
+    BUFFERING_RULES = {
+        // Critical findings bypass buffering
+        'critical_finding': {
+            delay: 0,
+            maxBatch: 1,
+            coalescence: false,
+            priority: 'immediate'
+        },
+        // Security issues get high priority
+        'security_finding': {
+            delay: 50,
+            maxBatch: 2,
+            coalescence: false,
+            priority: 'high'
+        },
+        // Regular findings with moderate batching
+        'finding': {
+            delay: 200,
+            maxBatch: 5,
+            coalescence: true,
+            priority: 'normal'
+        },
+        // Progress updates with standard throttling
+        'agent_progress': {
+            delay: 200,
+            maxBatch: 10,
+            coalescence: true,
+            priority: 'normal'
+        },
+        // Errors need immediate attention
+        'agent_error': {
+            delay: 0,
+            maxBatch: 1,
+            coalescence: false,
+            priority: 'immediate'
+        },
+        // Completion events are high priority
+        'agent_complete': {
+            delay: 100,
+            maxBatch: 1,
+            coalescence: false,
+            priority: 'high'
+        },
+        // Debug info can be heavily throttled
+        'debug_info': {
+            delay: 1000,
+            maxBatch: 20,
+            coalescence: true,
+            priority: 'low'
+        },
+        // Milestones are important but can be batched
+        'milestone': {
+            delay: 150,
+            maxBatch: 3,
+            coalescence: false,
+            priority: 'high'
+        }
+    };
+    DEFAULT_RULE = {
+        delay: 500,
+        maxBatch: 5,
+        coalescence: true,
+        priority: 'normal'
+    };
+    // Configuration
+    MAX_BUFFER_SIZE = 1000; // Events per session
+    MAX_MEMORY_MB = 50; // Memory limit per session
+    BACKLOG_SIZE = 500; // Backlog events for late subscribers
+    constructor() {
+        // Periodic cleanup of stale sessions
+        setInterval(() => this.cleanupStaleSessions(), 60000); // Every minute
+    }
+    /**
+     * Add event to buffer with intelligent routing
+     */
+    add(event) {
+        if (!event.sessionId) {
+            logger.warn('Event without sessionId dropped');
+            return;
+        }
+        // Get or create buffer state
+        const state = this.getOrCreateState(event.sessionId);
+        // Check for backpressure
+        if (state.backpressure) {
+            logger.warn(`Backpressure detected for session ${event.sessionId}, dropping low priority events`);
+            if (this.getEventPriority(event) === 'low') {
+                return;
+            }
+        }
+        // Classify event and get buffering rule
+        const classification = this.classifyEvent(event);
+        const rule = this.BUFFERING_RULES[classification] || this.DEFAULT_RULE;
+        // Get or create buffer
+        const buffer = this.getOrCreateBuffer(event.sessionId);
+        // Add to backlog for late subscribers
+        this.addToBacklog(event);
+        // Enqueue with priority
+        buffer.enqueue(event, rule.priority);
+        // Update state
+        state.totalEvents++;
+        state.pendingEvents = buffer.size();
+        state.memoryUsage = this.estimateMemoryUsage(event.sessionId);
+        // Check memory limits
+        if (state.memoryUsage > this.MAX_MEMORY_MB * 1024 * 1024) {
+            this.handleMemoryPressure(event.sessionId);
+        }
+        // Schedule flush based on rule
+        this.scheduleFlush(event.sessionId, rule);
+        logger.debug(`Buffered ${classification} event for session ${event.sessionId} (${state.pendingEvents} pending)`);
+    }
+    /**
+     * Force flush of all pending events for a session
+     */
+    flush(sessionId, priority) {
+        const buffer = this.buffers.get(sessionId);
+        const state = this.states.get(sessionId);
+        if (!buffer || !state) {
+            return null;
+        }
+        const events = buffer.dequeueAll(priority);
+        if (events.length === 0) {
+            return null;
+        }
+        // Apply coalescence if enabled
+        const coalescedEvents = this.applyCoalescence(events);
+        // Update state
+        state.pendingEvents = buffer.size();
+        state.lastFlush = Date.now();
+        state.flushCount++;
+        // Clear timer if exists
+        const timer = this.flushTimers.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.flushTimers.delete(sessionId);
+        }
+        const batch = {
+            sessionId,
+            events: coalescedEvents,
+            priority: priority || 'normal',
+            batchId: `${sessionId}-${state.flushCount}-${Date.now()}`,
+            createdAt: Date.now()
+        };
+        logger.debug(`Flushed ${coalescedEvents.length} events for session ${sessionId} (batch: ${batch.batchId})`);
+        return batch;
+    }
+    /**
+     * Get backlog events for late subscribers
+     */
+    getBacklog(sessionId, limit) {
+        const backlog = this.backlog.get(sessionId);
+        if (!backlog) {
+            return [];
+        }
+        return backlog.peek(limit);
+    }
+    /**
+     * Get buffer state for monitoring
+     */
+    getState(sessionId) {
+        return this.states.get(sessionId) || null;
+    }
+    /**
+     * Get all active sessions
+     */
+    getActiveSessions() {
+        return Array.from(this.buffers.keys());
+    }
+    /**
+     * Cleanup session resources
+     */
+    cleanup(sessionId) {
+        // Flush any remaining events
+        this.flush(sessionId);
+        // Clear timer
+        const timer = this.flushTimers.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.flushTimers.delete(sessionId);
+        }
+        // Remove all resources
+        this.buffers.delete(sessionId);
+        this.states.delete(sessionId);
+        this.backlog.delete(sessionId);
+        logger.info(`Cleaned up buffer resources for session ${sessionId}`);
+    }
+    /**
+     * Get total memory usage across all sessions
+     */
+    getTotalMemoryUsage() {
+        return Array.from(this.states.values())
+            .reduce((sum, state) => sum + state.memoryUsage, 0);
+    }
+    /**
+     * Get system-wide metrics
+     */
+    getMetrics() {
+        const states = Array.from(this.states.values());
+        return {
+            activeSessions: states.length,
+            totalEvents: states.reduce((sum, s) => sum + s.totalEvents, 0),
+            totalMemoryMB: Math.round(this.getTotalMemoryUsage() / (1024 * 1024)),
+            backpressureSessions: states.filter(s => s.backpressure).length
+        };
+    }
+    /**
+     * Classify event for buffering rules
+     */
+    classifyEvent(event) {
+        const content = event.content?.toLowerCase() || '';
+        const metadata = event.metadata;
+        // Check metadata classification first
+        if (metadata?.contentType === 'finding') {
+            if (metadata.severity === 'critical') {
+                return 'critical_finding';
+            }
+            if (content.includes('security') || content.includes('vulnerability')) {
+                return 'security_finding';
+            }
+            return 'finding';
+        }
+        // Event type classification
+        if (event.type === 'agent_error') {
+            return 'agent_error';
+        }
+        if (event.type === 'agent_complete') {
+            return 'agent_complete';
+        }
+        // Content-based classification
+        if (content.includes('critical') || content.includes('security')) {
+            return 'critical_finding';
+        }
+        if (metadata?.contentType === 'milestone') {
+            return 'milestone';
+        }
+        if (metadata?.contentType === 'debug') {
+            return 'debug_info';
+        }
+        return 'agent_progress';
+    }
+    /**
+     * Get event priority for backpressure handling
+     */
+    getEventPriority(event) {
+        const classification = this.classifyEvent(event);
+        return this.BUFFERING_RULES[classification]?.priority || 'normal';
+    }
+    /**
+     * Schedule flush based on buffering rule
+     */
+    scheduleFlush(sessionId, rule) {
+        // Immediate delivery
+        if (rule.delay === 0) {
+            setImmediate(() => {
+                const batch = this.flush(sessionId, rule.priority);
+                if (batch) {
+                    this.deliverBatch(batch);
+                }
+            });
+            return;
+        }
+        // Check if we should flush due to batch size
+        const buffer = this.buffers.get(sessionId);
+        if (buffer && buffer.size(rule.priority) >= rule.maxBatch) {
+            const batch = this.flush(sessionId, rule.priority);
+            if (batch) {
+                this.deliverBatch(batch);
+            }
+            return;
+        }
+        // Schedule timer if not already scheduled
+        if (!this.flushTimers.has(sessionId)) {
+            const timer = setTimeout(() => {
+                this.flushTimers.delete(sessionId);
+                const batch = this.flush(sessionId);
+                if (batch) {
+                    this.deliverBatch(batch);
+                }
+            }, rule.delay);
+            this.flushTimers.set(sessionId, timer);
+        }
+    }
+    /**
+     * Apply content coalescence to reduce noise
+     */
+    applyCoalescence(events) {
+        if (events.length <= 1) {
+            return events;
+        }
+        const coalesced = [];
+        const groups = new Map();
+        // Group similar events
+        for (const event of events) {
+            const key = this.getCoalescenceKey(event);
+            if (!groups.has(key)) {
+                groups.set(key, []);
+            }
+            groups.get(key).push(event);
+        }
+        // Coalesce each group
+        for (const group of groups.values()) {
+            if (group.length === 1) {
+                coalesced.push(group[0]);
+            }
+            else {
+                const merged = this.mergeEvents(group);
+                coalesced.push(merged);
+            }
+        }
+        return coalesced.sort((a, b) => a.timestamp - b.timestamp);
+    }
+    /**
+     * Generate coalescence key for grouping similar events
+     */
+    getCoalescenceKey(event) {
+        return `${event.agent}-${event.type}-${event.metadata?.contentType || 'default'}`;
+    }
+    /**
+     * Merge similar events into single event
+     */
+    mergeEvents(events) {
+        const first = events[0];
+        const last = events[events.length - 1];
+        return {
+            ...first,
+            content: events.length > 3
+                ? `${first.content} ... [${events.length - 2} similar events] ... ${last.content}`
+                : events.map(e => e.content).join(' | '),
+            timestamp: last.timestamp,
+            metadata: {
+                ...first.metadata,
+                coalescedCount: events.length,
+                timespan: last.timestamp - first.timestamp
+            }
+        };
+    }
+    /**
+     * Get or create buffer for session
+     */
+    getOrCreateBuffer(sessionId) {
+        if (!this.buffers.has(sessionId)) {
+            this.buffers.set(sessionId, new PriorityQueue());
+        }
+        return this.buffers.get(sessionId);
+    }
+    /**
+     * Get or create buffer state
+     */
+    getOrCreateState(sessionId) {
+        if (!this.states.has(sessionId)) {
+            this.states.set(sessionId, {
+                sessionId,
+                totalEvents: 0,
+                pendingEvents: 0,
+                lastFlush: Date.now(),
+                flushCount: 0,
+                backpressure: false,
+                memoryUsage: 0
+            });
+        }
+        return this.states.get(sessionId);
+    }
+    /**
+     * Add event to backlog for late subscribers
+     */
+    addToBacklog(event) {
+        if (!event.sessionId)
+            return;
+        if (!this.backlog.has(event.sessionId)) {
+            this.backlog.set(event.sessionId, new CircularBuffer(this.BACKLOG_SIZE));
+        }
+        this.backlog.get(event.sessionId).add(event);
+    }
+    /**
+     * Estimate memory usage for session
+     */
+    estimateMemoryUsage(sessionId) {
+        const buffer = this.buffers.get(sessionId);
+        const backlog = this.backlog.get(sessionId);
+        let size = 0;
+        // Estimate buffer size (rough approximation)
+        if (buffer) {
+            size += buffer.size() * 500; // ~500 bytes per event
+        }
+        // Estimate backlog size
+        if (backlog) {
+            size += backlog.getCount() * 500;
+        }
+        return size;
+    }
+    /**
+     * Handle memory pressure by dropping low priority events
+     */
+    handleMemoryPressure(sessionId) {
+        const state = this.getOrCreateState(sessionId);
+        const buffer = this.buffers.get(sessionId);
+        state.backpressure = true;
+        // Flush low priority events immediately to free memory
+        if (buffer) {
+            const lowPriorityEvents = buffer.dequeueAll('low');
+            logger.warn(`Memory pressure: dropped ${lowPriorityEvents.length} low priority events for session ${sessionId}`);
+        }
+        // Clear backpressure after a delay
+        setTimeout(() => {
+            state.backpressure = false;
+        }, 5000);
+    }
+    /**
+     * Clean up stale sessions (no activity for > 1 hour)
+     */
+    cleanupStaleSessions() {
+        const now = Date.now();
+        const staleThreshold = 60 * 60 * 1000; // 1 hour
+        for (const [sessionId, state] of this.states.entries()) {
+            if (now - state.lastFlush > staleThreshold) {
+                logger.info(`Cleaning up stale session: ${sessionId}`);
+                this.cleanup(sessionId);
+            }
+        }
+    }
+    /**
+     * Deliver batch to subscribers (to be implemented by transport layer)
+     */
+    deliverBatch(batch) {
+        // This will be called by the transport layer
+        // For now, just emit a custom event that can be listened to
+        // Emit batch as event (commented out as it's not needed for current implementation)
+        // process.emit('streaming-batch', batch);
+    }
+}
+//# sourceMappingURL=intelligent-buffer.js.map