@mxf-dev/core 1.0.0

package/dist/events/EventBus.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+import { IClientEventBus } from './ClientEventBus.js';
+import { IServerEventBus } from './ServerEventBus.js';
+/**
+ * EventBus Implementation
+ *
+ * This implementation uses rxjs for event handling and integrates directly with socket.io
+ */
+export declare class EventBusImplementation {
+    private eventSubject;
+    private clientEventBus;
+    private serverEventBus;
+    /**
+     * Constructor for EventBusImplementation
+     */
+    constructor();
+    /**
+     * Get or create the client EventBus instance
+     *
+     * @returns The client EventBus instance
+     */
+    get client(): IClientEventBus;
+    /**
+     * Get or create the server EventBus instance
+     *
+     * @returns The server EventBus instance
+     */
+    get server(): IServerEventBus;
+    /**
+     * Reset the EventBus to its initial state.
+     * This is primarily used for testing.
+     */
+    reset(): void;
+    /**
+     * Debug method to log all events being processed by the EventBus
+     * @returns A subscription that can be unsubscribed to stop debugging
+     */
+    debug(): import("rxjs").Subscription;
+}
+export declare const EventBus: EventBusImplementation;
+//# sourceMappingURL=EventBus.d.ts.map

package/dist/events/EventBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.d.ts","sourceRoot":"","sources":["../../src/events/EventBus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgBH,OAAO,EAAkB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAkB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAMtE;;;;GAIG;AACH,qBAAa,sBAAsB;IAC/B,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,cAAc,CAAgC;IAEtD;;OAEG;;IAMH;;;;OAIG;IACH,IAAW,MAAM,IAAI,eAAe,CAKnC;IAED;;;;OAIG;IACH,IAAW,MAAM,IAAI,eAAe,CAKnC;IAED;;;OAGG;IACI,KAAK,IAAI,IAAI;IAWpB;;;OAGG;IACI,KAAK;CAKf;AAGD,eAAO,MAAM,QAAQ,wBAA+B,CAAC"}

package/dist/events/EventBus.js

@@ -0,0 +1,98 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * EventBus
+ *
+ * Provides a type-safe event bus implementation for the MXF.
+ * This implementation is designed to be used with socket.io and other event-based systems.
+ *
+ * The EventBus serves as a unified facade over both local events and socket.io events:
+ * - When a socket is set, events are forwarded to the socket when emitted
+ * - For server-side usage, the socket.io server instance can be set for broadcasting
+ * - All events are processed through RxJS for local subscriptions
+ */
+import { Subject } from 'rxjs';
+import { ClientEventBus } from './ClientEventBus.js';
+import { ServerEventBus } from './ServerEventBus.js';
+import { Logger } from '../utils/Logger.js';
+// Create a logger instance for EventBus
+const logger = new Logger('info', 'EventBus', 'server');
+/**
+ * EventBus Implementation
+ *
+ * This implementation uses rxjs for event handling and integrates directly with socket.io
+ */
+export class EventBusImplementation {
+    eventSubject;
+    clientEventBus = null;
+    serverEventBus = null;
+    /**
+     * Constructor for EventBusImplementation
+     */
+    constructor() {
+        this.eventSubject = new Subject();
+        //;
+    }
+    /**
+     * Get or create the client EventBus instance
+     *
+     * @returns The client EventBus instance
+     */
+    get client() {
+        if (!this.clientEventBus) {
+            this.clientEventBus = new ClientEventBus(this.eventSubject);
+        }
+        return this.clientEventBus;
+    }
+    /**
+     * Get or create the server EventBus instance
+     *
+     * @returns The server EventBus instance
+     */
+    get server() {
+        if (!this.serverEventBus) {
+            this.serverEventBus = new ServerEventBus(this.eventSubject);
+        }
+        return this.serverEventBus;
+    }
+    /**
+     * Reset the EventBus to its initial state.
+     * This is primarily used for testing.
+     */
+    reset() {
+        // Reset the event subject
+        this.eventSubject.complete();
+        this.eventSubject = new Subject();
+        // Reset client and server instances
+        this.clientEventBus = null;
+        this.serverEventBus = null;
+    }
+    /**
+     * Debug method to log all events being processed by the EventBus
+     * @returns A subscription that can be unsubscribed to stop debugging
+     */
+    debug() {
+        return this.eventSubject.subscribe(event => {
+        });
+    }
+}
+// Export the EventBus singleton
+export const EventBus = new EventBusImplementation();
+//# sourceMappingURL=EventBus.js.map

package/dist/events/EventBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.js","sourceRoot":"","sources":["../../src/events/EventBus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B,OAAO,EAAE,cAAc,EAAmB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAmB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,wCAAwC;AACxC,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;AAExD;;;;GAIG;AACH,MAAM,OAAO,sBAAsB;IACvB,YAAY,CAAwB;IACpC,cAAc,GAA2B,IAAI,CAAC;IAC9C,cAAc,GAA2B,IAAI,CAAC;IAEtD;;OAEG;IACH;QACI,IAAI,CAAC,YAAY,GAAG,IAAI,OAAO,EAAgB,CAAC;QAChD,GAAG;IACP,CAAC;IAED;;;;OAIG;IACH,IAAW,MAAM;QACb,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACvB,IAAI,CAAC,cAAc,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,IAAW,MAAM;QACb,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACvB,IAAI,CAAC,cAAc,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACI,KAAK;QACR,0BAA0B;QAC1B,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,IAAI,OAAO,EAAgB,CAAC;QAEhD,oCAAoC;QACpC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;IAE/B,CAAC;IAED;;;OAGG;IACI,KAAK;QAER,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE;QAC3C,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AAED,gCAAgC;AAChC,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,sBAAsB,EAAE,CAAC"}

package/dist/events/EventBusBase.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * EventBusBase
+ *
+ * Provides base interfaces and functionality for the MXF event system.
+ * This file contains common types, interfaces, and validation functions used
+ * by both client and server event bus implementations.
+ */
+import { Subject, Subscription } from 'rxjs';
+import type { EventMap } from './EventNames.js';
+import type { BaseEventPayload } from '../schemas/EventPayloadSchema.js';
+import { Logger } from '../utils/Logger.js';
+/**
+ * Invokes an event handler so that neither a synchronous throw nor an async
+ * rejection can kill the bus subscription or vanish silently. Errors are
+ * logged loudly with the event name; the bus stays alive for other handlers.
+ */
+export declare const invokeHandlerSafely: (busLogger: Logger, eventName: unknown, handler: (payload: any) => unknown, payload: any) => void;
+/**
+ * Socket interface based on the subset of Socket.IO functionality we use
+ */
+export interface SocketLike {
+    id?: string;
+    connected?: boolean;
+    on: (event: string, listener: (...args: any[]) => void) => any;
+    off: (event: string, listener?: (...args: any[]) => void) => any;
+    emit: (event: string, ...args: any[]) => any;
+    onAny?: (listener: (event: string, ...args: any[]) => void) => any;
+    offAny?: () => any;
+    removeAllListeners?: () => any;
+    disconnect?: () => void;
+    data?: {
+        agentId?: string;
+        channelId?: string;
+        authenticated?: boolean;
+        [key: string]: any;
+    };
+    join?: (room: string) => any;
+    leave?: (room: string) => any;
+}
+/**
+ * Type alias for event names
+ */
+export type EventName = keyof EventMap;
+/**
+ * Type for any event name (including custom string events)
+ */
+export type AnyEventName = EventName | string;
+/**
+ * Payload type for an event. EventMap entries historically declare the raw
+ * event DATA type, but the runtime shape on the bus is always the
+ * BaseEventPayload envelope produced by the EventPayloadSchema helpers —
+ * Normalize wraps data-level entries so the type system matches reality.
+ * Arbitrary string events (external MCP, custom) stay open.
+ */
+type NormalizePayload<P> = P extends BaseEventPayload<any> ? P : BaseEventPayload<P>;
+export type PayloadOf<T extends AnyEventName> = T extends keyof EventMap ? NormalizePayload<EventMap[T]> : any;
+/**
+ * Export EventMap for use in other files
+ */
+export { EventMap };
+/**
+ * Event handler type for event subscriptions
+ */
+export type EventHandler<T> = (payload: T) => void;
+/**
+ * Internal event message format used by the event bus
+ */
+export interface EventMessage {
+    type: string;
+    payload: any;
+}
+/**
+ * Base interface for event bus functionality shared by both client and server
+ */
+export interface EventBusBase {
+    /**
+     * Subscribe to an event
+     * @param event Event name
+     * @param handler Event handler function
+     * @returns Subscription to use for unsubscribing
+     */
+    on<K extends AnyEventName>(event: K, handler: EventHandler<any>): Subscription;
+    /**
+     * Subscribe to an event once
+     * @param event Event name
+     * @param handler Event handler function
+     * @returns Subscription to use for unsubscribing
+     */
+    once<K extends AnyEventName>(event: K, handler: EventHandler<any>): Subscription;
+    /**
+     * Unsubscribe from an event
+     * @param event Event name
+     * @param handler Event handler function (optional - if not provided, all handlers for this event are removed)
+     */
+    off<K extends AnyEventName>(event: K, handler?: EventHandler<any>): void;
+    /**
+     * Emit an event
+     * @param event Event name
+     * @param payload Event payload
+     */
+    emit?(event: AnyEventName, payload: any): void;
+    /**
+     * Check if an event has subscribers
+     * @param event Event name
+     * @returns True if the event has subscribers, false otherwise
+     */
+    hasSubscribers?(event: AnyEventName): boolean;
+    /**
+     * Get number of listeners for an event
+     * @param event Event name
+     * @returns Number of listeners
+     */
+    listenerCount(event: AnyEventName): number;
+    /**
+     * Check if event has listeners
+     * @param event Event name
+     * @returns true if the event has listeners, false otherwise
+     */
+    hasListeners(event: AnyEventName): boolean;
+    /**
+     * Remove all listeners for a given event or all events if no event is specified
+     * @param event Optional event name to remove all listeners for
+     * @returns this (for chaining)
+     */
+    removeAllListeners(event?: AnyEventName): this;
+}
+/**
+ * Helper function to validate an event name
+ * @param event Event name to validate
+ * @returns true if valid, throws error if invalid
+ */
+export declare function validateEventName(event: AnyEventName): boolean;
+/**
+ * Helper function to check if an event is a reserved Socket.IO event
+ * @param event Event name to check
+ * @returns true if it's a reserved event
+ */
+export declare function isReservedEvent(event: string): boolean;
+/**
+ * Helper function to check if an event is a critical event that must always be processed
+ * @param event Event name to check
+ * @returns true if it's a critical event
+ */
+export declare function isCriticalEvent(event: string): boolean;
+/**
+ * Base event bus implementation with RxJS
+ */
+export declare abstract class BaseEventBusImplementation implements EventBusBase {
+    protected eventSubject: Subject<EventMessage>;
+    protected subscriptionCountMap: Map<string, number>;
+    constructor(eventSubject: Subject<EventMessage>);
+    /**
+     * Emit an event with validation
+     * @param event Event name
+     * @param payload Event payload
+     */
+    emit<K extends AnyEventName>(event: K, payload: PayloadOf<K>): void;
+    /**
+     * Check if an event has subscribers
+     * @param event Event name
+     * @returns True if the event has subscribers, false otherwise
+     */
+    hasSubscribers(event: AnyEventName): boolean;
+    /**
+     * Subscribe to an event
+     * @param event Event name
+     * @param handler Event handler function
+     * @returns Subscription to use for unsubscribing
+     */
+    on<K extends AnyEventName>(event: K, handler: EventHandler<PayloadOf<K>>): Subscription;
+    /**
+     * Subscribe to an event once
+     * @param event Event name
+     * @param handler Event handler function
+     * @returns Subscription to use for unsubscribing
+     */
+    once<K extends AnyEventName>(event: K, handler: EventHandler<PayloadOf<K>>): Subscription;
+    /**
+     * Unsubscribe from an event
+     * @param event Event name
+     * @param handler Event handler function (optional)
+     *
+     * Note: For best results in RxJS-based EventBus, it's preferable to keep
+     * the Subscription object returned by on() and call subscription.unsubscribe() directly.
+     * This method is provided for compatibility with traditional event emitter patterns.
+     */
+    off<K extends AnyEventName>(event: K, handler?: EventHandler<any>): void;
+    /**
+     * Get number of listeners for an event (approximate)
+     * Note: This is an approximation as RxJS doesn't expose subscriber counts directly
+     * @param event Event name
+     * @returns Number of listeners
+     */
+    listenerCount(event: AnyEventName): number;
+    /**
+     * Check if an event has listeners
+     * Note: This is an approximation as RxJS doesn't expose subscriber counts directly
+     * @param event Event name
+     * @returns true if the event has listeners
+     */
+    hasListeners(event: AnyEventName): boolean;
+    /**
+     * Remove all listeners for a given event or all events if no event is specified
+     * Note: With RxJS, we can't selectively unsubscribe other subscribers
+     * @param event Optional event name to remove all listeners for
+     * @returns this (for chaining)
+     */
+    removeAllListeners(event?: AnyEventName): this;
+    /**
+     * Validate event payload to ensure it follows the expected schema
+     * @param event Event name
+     * @param payload Event payload
+     * @returns true if valid, throws error if invalid
+     */
+    protected validateEventPayload(event: string, payload: any): boolean;
+}
+//# sourceMappingURL=EventBusBase.d.ts.map

package/dist/events/EventBusBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBusBase.d.ts","sourceRoot":"","sources":["../../src/events/EventBusBase.ts"],"names":[],"mappings":"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"}

package/dist/events/EventBusBase.js

@@ -0,0 +1,247 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+import { SOCKET_RESERVED_EVENTS, Events } from './EventNames.js';
+import { MessageEvents } from './event-definitions/MessageEvents.js';
+import { createStrictValidator } from '../utils/validation.js';
+import { Logger } from '../utils/Logger.js';
+/**
+ * Invokes an event handler so that neither a synchronous throw nor an async
+ * rejection can kill the bus subscription or vanish silently. Errors are
+ * logged loudly with the event name; the bus stays alive for other handlers.
+ */
+export const invokeHandlerSafely = (busLogger, eventName, handler, payload) => {
+    try {
+        const result = handler(payload);
+        if (result && typeof result.then === 'function') {
+            result.catch((error) => {
+                busLogger.error(`Async handler for '${String(eventName)}' rejected: ${error instanceof Error ? error.stack : String(error)}`);
+            });
+        }
+    }
+    catch (error) {
+        busLogger.error(`Handler for '${String(eventName)}' threw: ${error instanceof Error ? error.stack : String(error)}`);
+    }
+};
+// Create a logger instance for EventBus
+const logger = new Logger('info', 'EventBus', 'server');
+/**
+ * Helper function to validate an event name
+ * @param event Event name to validate
+ * @returns true if valid, throws error if invalid
+ */
+export function validateEventName(event) {
+    const validator = createStrictValidator('EventBus');
+    validator.assertIsNonEmptyString(event);
+    return true;
+}
+/**
+ * Helper function to check if an event is a reserved Socket.IO event
+ * @param event Event name to check
+ * @returns true if it's a reserved event
+ */
+export function isReservedEvent(event) {
+    return SOCKET_RESERVED_EVENTS.includes(event);
+}
+/**
+ * Helper function to check if an event is a critical event that must always be processed
+ * @param event Event name to check
+ * @returns true if it's a critical event
+ */
+export function isCriticalEvent(event) {
+    const criticalEvents = [
+        // Message events
+        MessageEvents.CHANNEL_MESSAGE_DELIVERED,
+        MessageEvents.AGENT_MESSAGE_DELIVERED,
+        MessageEvents.MESSAGE_ERROR,
+        Events.Agent.CONNECTION_ERROR
+    ];
+    return criticalEvents.includes(event);
+}
+/**
+ * Base event bus implementation with RxJS
+ */
+export class BaseEventBusImplementation {
+    eventSubject;
+    // Track event subscription counts
+    subscriptionCountMap = new Map();
+    constructor(eventSubject) {
+        this.eventSubject = eventSubject;
+    }
+    /**
+     * Emit an event with validation
+     * @param event Event name
+     * @param payload Event payload
+     */
+    emit(event, payload) {
+        try {
+            // Validate event name
+            validateEventName(event);
+            // Validate payload is not null or undefined, which can cause client errors
+            if (payload === undefined || payload === null) {
+                logger.warn(`[EventBus] Warning: Emitting event '${event}' with ${payload === null ? 'null' : 'undefined'} payload. This may cause errors for subscribers.`);
+                // Create a safe default payload if none provided
+                payload = {};
+            }
+            if (isCriticalEvent(event)) {
+            }
+            else {
+            }
+            // Only emit if we have subscribers to avoid wasted processing
+            if (this.hasSubscribers(event)) {
+                this.eventSubject.next({ type: event, payload });
+            }
+        }
+        catch (error) {
+            logger.error(`[EventBus] Error emitting event '${event}': ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Check if an event has subscribers
+     * @param event Event name
+     * @returns True if the event has subscribers, false otherwise
+     */
+    hasSubscribers(event) {
+        // In base implementation, we assume there might be subscribers if we don't have tracking
+        // Derived classes should override this for more accurate tracking
+        return true;
+    }
+    /**
+     * Subscribe to an event
+     * @param event Event name
+     * @param handler Event handler function
+     * @returns Subscription to use for unsubscribing
+     */
+    on(event, handler) {
+        // In base implementation, we can only log the request
+        // Derived classes should override this method to provide actual subscription functionality
+        return undefined;
+    }
+    /**
+     * Subscribe to an event once
+     * @param event Event name
+     * @param handler Event handler function
+     * @returns Subscription to use for unsubscribing
+     */
+    once(event, handler) {
+        // In base implementation, we can only log the request
+        // Derived classes should override this method to provide actual subscription functionality
+        return undefined;
+    }
+    /**
+     * Unsubscribe from an event
+     * @param event Event name
+     * @param handler Event handler function (optional)
+     *
+     * Note: For best results in RxJS-based EventBus, it's preferable to keep
+     * the Subscription object returned by on() and call subscription.unsubscribe() directly.
+     * This method is provided for compatibility with traditional event emitter patterns.
+     */
+    off(event, handler) {
+        // In base implementation, we can only log the request
+        // Derived classes should override this method to provide actual unsubscription functionality
+    }
+    /**
+     * Get number of listeners for an event (approximate)
+     * Note: This is an approximation as RxJS doesn't expose subscriber counts directly
+     * @param event Event name
+     * @returns Number of listeners
+     */
+    listenerCount(event) {
+        // RxJS doesn't provide a way to count subscribers directly
+        // This is a limitation of our current implementation
+        logger.warn('[EventBus] listenerCount is not fully supported with RxJS');
+        return this.hasListeners(event) ? 1 : 0;
+    }
+    /**
+     * Check if an event has listeners
+     * Note: This is an approximation as RxJS doesn't expose subscriber counts directly
+     * @param event Event name
+     * @returns true if the event has listeners
+     */
+    hasListeners(event) {
+        // RxJS doesn't provide a way to check if there are subscribers
+        // This is a limitation of our current implementation
+        logger.warn('[EventBus] hasListeners is not fully supported with RxJS');
+        return true; // We don't know for sure, so assume there might be listeners
+    }
+    /**
+     * Remove all listeners for a given event or all events if no event is specified
+     * Note: With RxJS, we can't selectively unsubscribe other subscribers
+     * @param event Optional event name to remove all listeners for
+     * @returns this (for chaining)
+     */
+    removeAllListeners(event) {
+        logger.warn('[EventBus] removeAllListeners is not fully supported with RxJS');
+        return this;
+    }
+    /**
+     * Validate event payload to ensure it follows the expected schema
+     * @param event Event name
+     * @param payload Event payload
+     * @returns true if valid, throws error if invalid
+     */
+    validateEventPayload(event, payload) {
+        // Log event details to help track events without proper schemas
+        //     eventName: event, 
+        //     payloadType: typeof payload,
+        //     hasAgentId: typeof payload === 'object' && payload !== null && 'agentId' in payload,
+        //     hasChannelId: typeof payload === 'object' && payload !== null && 'channelId' in payload,
+        //     hasEventId: typeof payload === 'object' && payload !== null && 'eventId' in payload,
+        //     hasData: typeof payload === 'object' && payload !== null && 'data' in payload
+        // });
+        // Use validation utility for fail-fast behavior - all events must follow BaseEventPayload structure
+        const validator = createStrictValidator('EventBus');
+        try {
+            // All events must have the standard BaseEventPayload structure
+            validator.assertIsEventPayload(payload);
+            // Additional validation for eventId and data fields
+            validator.assertHasProperty(payload, 'eventId', 'EventPayload must have eventId field');
+            validator.assertHasProperty(payload, 'data', 'EventPayload must have data field');
+            // Data-specific validation for message events
+            // Channel message events (should validate as ChannelMessage)
+            const channelMessageEvents = [
+                MessageEvents.CHANNEL_MESSAGE_DELIVERED,
+                MessageEvents.CHANNEL_MESSAGE,
+                MessageEvents.SYSTEM_MESSAGE,
+                MessageEvents.SYSTEM_MESSAGE_DELIVERED,
+            ];
+            // Agent message events (should validate as AgentMessage) 
+            const agentMessageEvents = [
+                MessageEvents.AGENT_MESSAGE_DELIVERED,
+                MessageEvents.AGENT_MESSAGE,
+                MessageEvents.LLM_MESSAGE
+            ];
+            if (channelMessageEvents.includes(event)) {
+                validator.assertIsChannelMessage(payload.data);
+            }
+            else if (agentMessageEvents.includes(event)) {
+                validator.assertIsAgentMessage(payload.data);
+            }
+            return true;
+        }
+        catch (error) {
+            // For rejected events, log detailed payload information
+            // Log the rejection and re-throw for fail-fast behavior
+            logger.error(`[EventBus] Rejecting non-standard payload for event ${event}: ${error instanceof Error ? error.message : 'Non-standard payload for event ' + event + ' - all events MUST use proper schema'}`);
+            throw new Error(`Invalid payload for event ${event}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=EventBusBase.js.map

package/dist/events/EventBusBase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBusBase.js","sourceRoot":"","sources":["../../src/events/EventBusBase.ts"],"names":[],"mappings":"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"}