@mxf-dev/core 1.0.1 → 2.0.1

package/src/events/EventNames.ts

@@ -154,6 +154,10 @@ import { MeilisearchEvents } from './event-definitions/MeilisearchEvents.js';
 import type { MeilisearchPayloads } from './event-definitions/MeilisearchEvents.js';
 export { MeilisearchEvents };
 export type { MeilisearchPayloads };
+import { LlmBudgetEvents } from './event-definitions/LlmBudgetEvents.js';
+import type { LlmBudgetPayloads } from './event-definitions/LlmBudgetEvents.js';
+export { LlmBudgetEvents };
+export type { LlmBudgetPayloads };
 
 import { CodeExecutionEvents } from './event-definitions/CodeExecutionEvents.js';
 import type { CodeExecutionPayloads } from './event-definitions/CodeExecutionEvents.js';
@@ -252,6 +256,7 @@ export namespace Events {
     export const Auth = AuthEvents;
     export const Mxp = MxpEvents;
     export const Meilisearch = MeilisearchEvents;
+    export const LlmBudget = LlmBudgetEvents;
     export const CodeExecution = CodeExecutionEvents;
     export const Shell = ShellExecutionEvents;
     export const Workflow = WorkflowEvents;
@@ -288,6 +293,7 @@ export type EventMap =
     BulkPayloads &
     MxpPayloads &
     MeilisearchPayloads &
+    LlmBudgetPayloads &
     CodeExecutionPayloads &
     ShellExecutionPayloads &
     WorkflowPayloads &

package/src/events/PublicEvents.ts

@@ -154,12 +154,15 @@ export const PUBLIC_USER_INPUT_EVENTS = [
 
 /**
  * Public Meilisearch Events - Semantic search operations
+ *
+ * Result events only. The *:request events stay internal, and there is no
+ * search event: search is a request/response call, not something the framework
+ * publishes.
  */
 export const PUBLIC_MEILISEARCH_EVENTS = [
-    'meilisearch:index',
-    'meilisearch:backfill:complete',
-    'meilisearch:backfill:partial',
-    'meilisearch:search',
+    Events.Meilisearch.INDEX,
+    Events.Meilisearch.BACKFILL_COMPLETE,
+    Events.Meilisearch.BACKFILL_PARTIAL,
 ] as const;
 
 /**

package/src/events/ServerEventBus.ts

@@ -26,29 +26,19 @@
  * and event routing to agents and channels.
  */
 
-import { Subject, Subscription } from 'rxjs';
-import { filter, map } from 'rxjs/operators';
-import type { Server as SocketIOServer, Socket } from 'socket.io';
-import { Events, ChannelActionTypes, MessageEvents } from './EventNames.js';
-import type { EventMap } from './EventNames.js';
+import { Subject } from 'rxjs';
+import type { Server as SocketIOServer } from 'socket.io';
 import { ControlLoopEvents } from './event-definitions/ControlLoopEvents.js';
 import { OrparEvents } from './event-definitions/OrparEvents.js';
 import { McpEvents } from './event-definitions/McpEvents.js';
 import { TaskEvents } from './event-definitions/TaskEvents.js';
-import { 
-    AnyEventName, 
-    BaseEventBusImplementation, 
-    EventHandler,
-    EventMessage, 
-    SocketLike, 
-    validateEventName,
-    isReservedEvent
-, invokeHandlerSafely, PayloadOf } from './EventBusBase.js';
-import { 
-    createAgentEventPayload,
-    createChannelEventPayload,
-    createBaseEventPayload
-} from '../schemas/EventPayloadSchema.js';
+import {
+    AnyEventName,
+    BaseEventBusImplementation,
+    EventMessage,
+    isReservedEvent,
+    PayloadOf
+} from './EventBusBase.js';
 import { createStrictValidator } from '../utils/validation.js';
 import { Logger } from '../utils/Logger.js';
 
@@ -75,91 +65,64 @@ export interface IServerEventBus extends BaseEventBusImplementation {
      */
     clearSocketServer(): this;
     
-    /**
-     * Emit an event
-     * @param event Event name
-     * @param payload Event payload
-     */
-    emit<K extends AnyEventName>(event: K, payload: PayloadOf<K>): void;
-
-    /**
-     * Subscribe to all events in the server event bus
-     * 
-     * @param listener Listener function that receives both event type and payload
-     * @returns Subscription that can be unsubscribed to stop listening
-     */
-    onAll(listener: (eventType: string, payload: any) => void): Subscription;
-    
     /**
      * Remove all server event listeners
      * @returns this (for chaining)
      */
     removeAllSocketListeners(): this;
-    
+
     /**
      * Clean up all subscriptions and listeners
      * @returns this (for chaining)
      */
     cleanup(): this;
-    
-    /**
-     * Enable or disable debug mode to log all events
-     * 
-     * @param enabled Whether debug mode should be enabled
-     * @returns this (for chaining)
-     */
-    enableDebugMode(enabled?: boolean): this;
-    
-    /**
-     * Subscribe to an event with category for grouped subscription management
-     * 
-     * @param category Category name for grouping subscriptions
-     * @param event Event name to subscribe to
-     * @param listener Listener function to call when the event is emitted
-     * @returns Subscription that can be unsubscribed to stop listening
-     */
-    onWithCategory<T extends AnyEventName>(
-        category: string,
-        event: T, 
-        listener: (payload: any) => void
-    ): Subscription;
-    
-    /**
-     * Unsubscribe from all events in a specific category
-     * 
-     * @param category Category name to unsubscribe from
-     * @returns this (for chaining)
-     */
-    unsubscribeCategory(category: string): this;
-    
-    /**
-     * Remove all event listeners for a specific event or all events
-     * @param event Optional specific event name to remove listeners for
-     * @returns this (for chaining)
-     */
-    removeAllListeners(event?: AnyEventName): this;
 }
 
 /**
  * Server-side event bus implementation
  */
 export class ServerEventBus extends BaseEventBusImplementation implements IServerEventBus {
+    /**
+     * Events delivered to specific agents/channels by eventForwardingHandlers.
+     * Broadcasting these over io.emit() would deliver them twice.
+     */
+    private static readonly AGENT_SPECIFIC_EVENTS: ReadonlySet<string> = new Set<string>([
+        ...Object.values(ControlLoopEvents),
+        ...Object.values(OrparEvents),
+        // MCP response events
+        McpEvents.TOOL_RESULT,
+        McpEvents.TOOL_ERROR,
+        McpEvents.TOOL_REGISTERED,
+        McpEvents.TOOL_UNREGISTERED,
+        McpEvents.MXF_TOOL_LIST_RESULT,
+        McpEvents.MXF_TOOL_LIST_ERROR,
+        McpEvents.RESOURCE_RESULT,
+        McpEvents.RESOURCE_ERROR,
+        McpEvents.EXTERNAL_SERVER_REGISTERED,
+        McpEvents.EXTERNAL_SERVER_UNREGISTERED,
+        McpEvents.EXTERNAL_SERVER_REGISTRATION_FAILED,
+        McpEvents.CHANNEL_SERVER_REGISTERED,
+        McpEvents.CHANNEL_SERVER_UNREGISTERED,
+        McpEvents.CHANNEL_SERVER_REGISTRATION_FAILED,
+        // Task lifecycle events
+        TaskEvents.CREATED,
+        TaskEvents.ASSIGNED,
+        TaskEvents.STARTED,
+        TaskEvents.PROGRESS_UPDATED,
+        TaskEvents.COMPLETED,
+        TaskEvents.FAILED,
+        TaskEvents.ERROR,
+        TaskEvents.CANCELLED,
+    ]);
+
     private ioInstance: SocketIOServer | null = null;
-    private subscriptions: Subscription[] = [];
-    private categorySubscriptions: Map<string, Subscription[]> = new Map();
-    
-    // Track subscriptions by event and handler for proper off() support
-    private handlerSubscriptions: Map<string, Map<EventHandler<any>, Subscription>> = new Map();
-    private debugMode: boolean = false;
-    private debugSubscription: Subscription | null = null;
-    
+
     /**
      * Create a new ServerEventBus
      * @param eventSubject Subject to use for events
      */
     constructor(eventSubject: Subject<EventMessage>) {
-        super(eventSubject);
-        //;
+        super(eventSubject, logger);
     }
     
     /**
@@ -195,412 +158,54 @@ export class ServerEventBus extends BaseEventBusImplementation implements IServe
     }
     
     /**
-     * Emit an event to the server event bus
-     * All components listen to this event bus
-     * 
-     * @param event Event name
-     * @param payload Event payload
-     */
-    public emit<K extends AnyEventName>(event: K, payload: PayloadOf<K>): void {
-        try {
-            // Validate event name and payload
-            validateEventName(event);
-            this.validateEventPayload(event, payload);
-            
-            // Handle null/undefined payload
-            if (payload === undefined || payload === null) {
-                logger.warn(`[ServerEventBus] Warning: Emitting event '${event}' with ${payload === null ? 'null' : 'undefined'} payload.`);
-                payload = {} as PayloadOf<K>;
-            }
-            
-            // Special logging for critical events like agent registration
-            if (event.startsWith('agent:')) {
-            }
-
-            // Emit to local event bus first
-            this.eventSubject.next({
-                type: event,
-                payload,
-            });
-            
-            // Also emit to the Socket.IO server if available
-            // IMPORTANT: Do NOT broadcast agent-specific events via io.emit().
-            // These events are forwarded to specific agents/channels via
-            // eventForwardingHandlers.forwardEventToAgent()/forwardEventToChannel().
-            // Broadcasting them causes duplicates: the SDK's ClientEventBus.setupClientSocketForwarding()
-            // has socket.onAny() that re-injects received socket events back into the RxJS Subject,
-            // so MxfChannelMonitor sees each broadcast event twice (once from Subject push, once from
-            // socket re-injection).
-            const agentSpecificEvents = new Set([
-                ...Object.values(ControlLoopEvents),
-                ...Object.values(OrparEvents),
-                // MCP response events — already forwarded to specific agents via eventForwardingHandlers
-                McpEvents.TOOL_RESULT,
-                McpEvents.TOOL_ERROR,
-                McpEvents.TOOL_REGISTERED,
-                McpEvents.TOOL_UNREGISTERED,
-                McpEvents.MXF_TOOL_LIST_RESULT,
-                McpEvents.MXF_TOOL_LIST_ERROR,
-                McpEvents.RESOURCE_RESULT,
-                McpEvents.RESOURCE_ERROR,
-                McpEvents.EXTERNAL_SERVER_REGISTERED,
-                McpEvents.EXTERNAL_SERVER_UNREGISTERED,
-                McpEvents.EXTERNAL_SERVER_REGISTRATION_FAILED,
-                McpEvents.CHANNEL_SERVER_REGISTERED,
-                McpEvents.CHANNEL_SERVER_UNREGISTERED,
-                McpEvents.CHANNEL_SERVER_REGISTRATION_FAILED,
-                // Task lifecycle events — already forwarded to specific agents/channels
-                TaskEvents.CREATED,
-                TaskEvents.ASSIGNED,
-                TaskEvents.STARTED,
-                TaskEvents.PROGRESS_UPDATED,
-                TaskEvents.COMPLETED,
-                TaskEvents.FAILED,
-                TaskEvents.ERROR,
-                TaskEvents.CANCELLED,
-            ]);
-
-            if (this.ioInstance && !isReservedEvent(event) && !agentSpecificEvents.has(event)) {
-                //;
-                this.ioInstance.emit(event, payload);
-            }
-            
-            //;
-        } catch (error) {
-            logger.error(`[ServerEventBus] Error emitting event '${event}':`, error instanceof Error ? error.message : String(error));
-            
-            // Re-throw the error for the caller to handle
-            throw error;
-        }
-    }
-    
-    /**
-     * Override the base on method to track handlers and subscriptions
-     * @param event Event name
-     * @param handler Event handler function
-     * @returns Subscription to use for unsubscribing
-     */
-    public override on<K extends AnyEventName>(event: K, handler: EventHandler<PayloadOf<K>>): Subscription {
-        // Create a filtered observable for this event
-        const observable = this.eventSubject.pipe(
-            filter((e: EventMessage) => e.type === event),
-            map((e: EventMessage) => e.payload)
-        );
-        
-        // Subscribe with throw/rejection isolation so one bad handler cannot
-        // kill the subscription or fail silently.
-        const subscription = observable.subscribe((payload) =>
-            invokeHandlerSafely(logger, event, handler, payload)
-        );
-        
-        // Store the subscription for cleanup
-        this.subscriptions.push(subscription);
-        
-        // Track handlers for off() support
-        if (!this.handlerSubscriptions.has(event)) {
-            this.handlerSubscriptions.set(event, new Map());
-        }
-        
-        const eventHandlers = this.handlerSubscriptions.get(event);
-        if (eventHandlers) {
-            eventHandlers.set(handler, subscription);
-        }
-        
-        return subscription;
-    }
-    
-    /**
-     * Override the base once method to track handlers and subscriptions
-     * Once the event is fired, the subscription is automatically removed
-     * 
-     * @param event Event name
-     * @param handler Event handler function
-     * @returns Subscription to use for unsubscribing
-     */
-    public override once<K extends AnyEventName>(event: K, handler: EventHandler<any>): Subscription {
-        // Create a filtered observable for this event
-        const observable = this.eventSubject.pipe(
-            filter((e: EventMessage) => e.type === event),
-            map((e: EventMessage) => e.payload)
-        );
-        
-        // Create a wrapper handler that will unsubscribe after first execution
-        const onceHandler = (payload: any) => {
-            try {
-                invokeHandlerSafely(logger, event, handler, payload);
-            } finally {
-                // Always unsubscribe — once means once, even when the handler throws.
-                this.off(event, onceHandler);
-            }
-        };
-        
-        // Subscribe to the observable with the one-time handler
-        const subscription = observable.subscribe(onceHandler);
-        
-        // Store the subscription for cleanup
-        this.subscriptions.push(subscription);
-        
-        // Track handlers for off() support
-        if (!this.handlerSubscriptions.has(event)) {
-            this.handlerSubscriptions.set(event, new Map());
+     * Forward an emitted event to the Socket.IO server.
+     *
+     * Called by BaseEventBusImplementation.emit() after validation and local
+     * delivery.
+     *
+     * Agent-specific events are NOT broadcast with io.emit(). They are routed
+     * to individual agents/channels by eventForwardingHandlers. Broadcasting
+     * them would duplicate delivery: the SDK's ClientEventBus.setupClientSocketForwarding()
+     * re-injects everything the socket receives back into the shared RxJS Subject,
+     * so a broadcast event would be seen twice (once from the Subject push, once
+     * from the socket re-injection).
+     */
+    protected override forwardToTransport<K extends AnyEventName>(event: K, payload: PayloadOf<K>): void {
+        if (!this.ioInstance) {
+            return;
         }
-        
-        const eventHandlers = this.handlerSubscriptions.get(event);
-        if (eventHandlers) {
-            eventHandlers.set(handler, subscription);
+
+        const eventName = String(event);
+        if (isReservedEvent(eventName) || ServerEventBus.AGENT_SPECIFIC_EVENTS.has(eventName)) {
+            return;
         }
-        
-        return subscription;
-    }
 
-    /**
-     * Subscribe to all events in the server event bus
-     * 
-     * @param listener Listener function that receives both event type and payload
-     * @returns Subscription that can be unsubscribed to stop listening
-     */
-    public onAll(listener: (eventType: string, payload: any) => void): Subscription {
-        // Create an observable that passes both event type and payload
-        const observable = this.eventSubject.pipe(
-            map((e: EventMessage) => ({ type: e.type, payload: e.payload }))
-        );
-        
-        
-        // Subscribe to the observable with the listener
-        const subscription = observable.subscribe(event => {
-            listener(event.type, event.payload);
-        });
-        
-        // Store the subscription for cleanup
-        this.subscriptions.push(subscription);
-        
-        return subscription;
+        this.ioInstance.emit(eventName, payload);
     }
-    
+
     /**
-     * Remove all server event listeners
+     * Drop the Socket.IO server reference so no further events are broadcast.
+     *
+     * The bus attaches no listeners to the Socket.IO server — it only calls
+     * io.emit() — so there is nothing else to detach here.
+     *
      * @returns this (for chaining)
      */
     public removeAllSocketListeners(): this {
-        if (this.ioInstance) {
-            try {
-                // Since Socket.IO Server doesn't have a direct equivalent to removeAllListeners(),
-                // we would need to track all listeners separately if we want to remove them.
-                // For now, we log that this operation is not fully implemented.
-            } catch (error) {
-                logger.error('[ServerEventBus] Error removing socket listeners:', error instanceof Error ? error.message : String(error));
-            }
-        }
-        
+        this.ioInstance = null;
+
         return this;
     }
-    
+
     /**
-     * Clean up all subscriptions and listeners
+     * Dispose every subscription and detach the Socket.IO server.
+     *
      * @returns this (for chaining)
      */
     public cleanup(): this {
-        // Clean up all subscriptions
-        this.subscriptions.forEach(subscription => subscription.unsubscribe());
-        this.subscriptions = [];
-        
-        // Clear category subscriptions
-        this.categorySubscriptions.clear();
-        
-        // Remove socket listeners
+        this.removeAllListeners();
         this.removeAllSocketListeners();
-        
-        // Reset debug mode
-        this.debugMode = false;
-        this.debugSubscription = null;
-        
-        
-        return this;
-    }
-    
-    /**
-     * Enable or disable debug mode to log all events
-     * 
-     * @param enabled Whether debug mode should be enabled
-     * @returns this (for chaining)
-     */
-    public enableDebugMode(enabled: boolean = true): this {
-        // If already in the requested mode, do nothing
-        if (this.debugMode === enabled) {
-            return this;
-        }
-        
-        this.debugMode = enabled;
-        
-        // If enabling debug mode
-        if (enabled) {
-            
-            // Create a subscription to all events
-            this.debugSubscription = this.onAll((eventType, payload) => {
-                // ;
-            });
-            
-            // Make sure it's tracked for cleanup
-            if (this.debugSubscription) {
-                this.subscriptions.push(this.debugSubscription);
-            }
-        } 
-        // If disabling debug mode
-        else if (this.debugSubscription) {
-            
-            // Unsubscribe from the debug subscription
-            this.debugSubscription.unsubscribe();
-            
-            // Remove from subscriptions array
-            const index = this.subscriptions.indexOf(this.debugSubscription);
-            if (index !== -1) {
-                this.subscriptions.splice(index, 1);
-            }
-            
-            this.debugSubscription = null;
-        }
-        
-        return this;
-    }
-    
-    /**
-     * Subscribe to an event with category for grouped subscription management
-     * 
-     * @param category Category name for grouping subscriptions
-     * @param event Event name to subscribe to
-     * @param listener Listener function to call when the event is emitted
-     * @returns Subscription that can be unsubscribed to stop listening
-     */
-    public onWithCategory<T extends AnyEventName>(
-        category: string,
-        event: T, 
-        listener: (payload: any) => void
-    ): Subscription {
-        // Create a subscription using the standard on method
-        const subscription = this.on(event, listener);
-        
-        // Store in the category map
-        if (!this.categorySubscriptions.has(category)) {
-            this.categorySubscriptions.set(category, []);
-        }
-        
-        const categorySubs = this.categorySubscriptions.get(category);
-        if (categorySubs) {
-            categorySubs.push(subscription);
-        }
-        
-        // ;
-        
-        return subscription;
-    }
-    
-    /**
-     * Unsubscribe from all events in a specific category
-     * 
-     * @param category Category name to unsubscribe from
-     * @returns this (for chaining)
-     */
-    public unsubscribeCategory(category: string): this {
-        const subscriptions = this.categorySubscriptions.get(category) || [];
-        
-        if (subscriptions.length > 0) {
-            
-            // Unsubscribe from each subscription in the category
-            subscriptions.forEach(subscription => {
-                subscription.unsubscribe();
-                
-                // Also remove from the main subscriptions array
-                const index = this.subscriptions.indexOf(subscription);
-                if (index !== -1) {
-                    this.subscriptions.splice(index, 1);
-                }
-            });
-            
-            // Clear the category
-            this.categorySubscriptions.delete(category);
-        } else {
-            // ;
-        }
-        
-        return this;
-    }
-    
-    /**
-     * Unsubscribe from an event
-     * @param event Event name
-     * @param handler Event handler function (optional)
-     */
-    public override off<K extends AnyEventName>(event: K, handler?: EventHandler<any>): void {
-        validateEventName(event);
-        
-        const eventHandlers = this.handlerSubscriptions.get(event);
-        if (!eventHandlers) {
-            // No handlers for this event found
-            // ;
-            return;
-        }
-        
-        if (handler) {
-            // If specific handler provided, just unsubscribe that one
-            const subscription = eventHandlers.get(handler);
-            if (subscription) {
-                // Unsubscribe from the RxJS subscription
-                subscription.unsubscribe();
-                
-                // Remove from our handler registry
-                eventHandlers.delete(handler);
-                
-                // Remove from the array if present
-                const index = this.subscriptions.indexOf(subscription);
-                if (index !== -1) {
-                    this.subscriptions.splice(index, 1);
-                }
-                
-                // ;
-            } else {
-                // ;
-            }
-        } else {
-            // If no specific handler, unsubscribe all handlers for this event
-            let unsubscribedCount = 0;
-            
-            eventHandlers.forEach((subscription) => {
-                // Unsubscribe from the RxJS subscription
-                subscription.unsubscribe();
-                
-                // Remove from the array if present
-                const index = this.subscriptions.indexOf(subscription);
-                if (index !== -1) {
-                    this.subscriptions.splice(index, 1);
-                }
-                
-                unsubscribedCount++;
-            });
-            
-            // Clear all handlers for this event
-            eventHandlers.clear();
-            
-            // ;
-        }
-    }
-    
-    /**
-     * Remove all event listeners for a specific event or all events
-     * @param event Optional specific event name to remove listeners for
-     * @returns this (for chaining)
-     */
-    public removeAllListeners(event?: AnyEventName): this {
-        // Remove all event listeners
-        this.eventSubject.observers = [];
-        
-        // Also clear our handler registries if appropriate
-        if (event) {
-            this.handlerSubscriptions.delete(event);
-        } else {
-            this.handlerSubscriptions.clear();
-        }
-        
-        
+
         return this;
     }
 }