@mxf-dev/core 1.0.1 → 2.0.0

package/src/utils/Logger.ts

@@ -20,16 +20,36 @@
 
 /**
  * Unified Logger for the Model Exchange Framework
- * 
+ *
  * Provides a consistent logging interface for both server and SDK components.
  * Features:
  * - Configurable log levels
  * - Context tagging
  * - Timestamp formatting
  * - Separate client/server logging pathways
- * 
+ *
  * This follows DRY principles by providing a single logging implementation
  * for the entire framework.
+ *
+ * ## Level resolution
+ *
+ * Two levels are in play and BOTH are honoured — the more restrictive one wins:
+ *
+ * - The **target level** (`enableServerLogging('info')`, `enableClientLogging(...)`)
+ *   is the application-wide ceiling. An operator who asks for `error` gets `error`.
+ * - The **instance level** (`new Logger('warn', 'Foo')`, `logger.setLevel('warn')`)
+ *   turns an individual component down below that ceiling.
+ *
+ * Effective level = min(instanceLevel, targetLevel). Before this, the target
+ * level was read unconditionally and every instance level in the codebase was
+ * silently discarded.
+ *
+ * ## Errors always surface
+ *
+ * `error()` output ignores the `enabled` flag. A library that swallows its own
+ * errors gives consumers no way to find out something broke: the buses catch
+ * handler failures and log them, so a disabled logger made those failures
+ * disappear entirely. Everything below `error` still respects `enabled`.
  */
 
 // Global logging configuration
@@ -44,14 +64,15 @@ interface LoggingConfig {
     };
 }
 
-// Default logging configuration
+// Default logging configuration.
+// `enabled: false` gates info/warn/debug/trace only — errors are always written.
 const LOGGING_CONFIG: LoggingConfig = {
     server: {
-        enabled: false,  // Server logging disabled by default
+        enabled: false,  // Server non-error logging off by default
         level: 'debug'
     },
     client: {
-        enabled: false,  // Client logging disabled by default (TUI suppresses via disableClientLogging())
+        enabled: false,  // Client non-error logging off by default (TUI suppresses via disableClientLogging())
         level: 'debug'
     }
 };
@@ -103,16 +124,54 @@ export class Logger {
 
     /**
      * Create a new Logger
-     * @param level Log level (error, warn, info, debug, trace)
+     *
+     * @param level Log level (error, warn, info, debug, trace). Caps this
+     *              component's verbosity; the target level still applies, and
+     *              the more restrictive of the two wins.
      * @param context Context string to prefix log messages
      * @param target Target pathway ('server' or 'client') - defaults to 'server'
      */
     constructor(level: string, context: string = '', target: 'server' | 'client' = 'server') {
+        if (Logger.LOG_LEVELS[level] === undefined) {
+            throw new Error(
+                `Logger: unknown log level '${level}'. Valid levels: ${Object.keys(Logger.LOG_LEVELS).join(', ')}`
+            );
+        }
         this.level = level;
         this.context = context;
         this.target = target;
     }
 
+    /**
+     * Resolve the level this logger actually writes at.
+     *
+     * The instance level and the target level are both honoured; whichever is
+     * more restrictive wins. Levels are ordered error(0) → trace(4), so "more
+     * restrictive" is the lower number.
+     *
+     * An unknown level string is a programming error and is rejected rather
+     * than silently treated as "log everything".
+     */
+    private resolveEffectiveLevel(): number {
+        const instanceRank = Logger.LOG_LEVELS[this.level];
+        if (instanceRank === undefined) {
+            throw new Error(
+                `Logger: unknown log level '${this.level}'. Valid levels: ${Object.keys(Logger.LOG_LEVELS).join(', ')}`
+            );
+        }
+
+        const targetLevel = LOGGING_CONFIG[this.target].level;
+        const targetRank = Logger.LOG_LEVELS[targetLevel];
+        if (targetRank === undefined) {
+            throw new Error(
+                `Logger: unknown log level '${targetLevel}' configured for target '${this.target}'. ` +
+                `Valid levels: ${Object.keys(Logger.LOG_LEVELS).join(', ')}`
+            );
+        }
+
+        return Math.min(instanceRank, targetRank);
+    }
+
     /**
      * Internal log method
      * @param level Log level
@@ -120,40 +179,43 @@ export class Logger {
      * @param args Additional arguments
      */
     private log(level: string, message: string, ...args: any[]): void {
-        // Get target-specific configuration
-        const targetConfig = LOGGING_CONFIG[this.target];
-        
-        // Check if logging is enabled for this target
-        if (!targetConfig.enabled) {
+        const isError = level === 'error';
+
+        // Errors are always written. Everything else respects the target's
+        // enabled flag, so a host app can keep its output clean without also
+        // hiding failures from itself.
+        if (!isError && !LOGGING_CONFIG[this.target].enabled) {
+            return;
+        }
+
+        const messageRank = Logger.LOG_LEVELS[level];
+        if (messageRank === undefined) {
+            throw new Error(
+                `Logger: unknown log level '${level}'. Valid levels: ${Object.keys(Logger.LOG_LEVELS).join(', ')}`
+            );
+        }
+
+        // Errors bypass the level check too — error is rank 0, so this is only
+        // belt-and-braces against a misconfigured level.
+        if (!isError && messageRank > this.resolveEffectiveLevel()) {
             return;
         }
-        
-        // Use target-specific level if different from instance level
-        const effectiveLevel = targetConfig.level || this.level;
-        
-        // Only log if the level is sufficient
-        if (Logger.LOG_LEVELS[level] <= Logger.LOG_LEVELS[effectiveLevel]) {
-            const timestamp = new Date().toISOString();
-            const targetPrefix = this.target === 'client' ? 'CLIENT' : 'SERVER';
-            const prefix = this.context 
-                ? `[${timestamp}][${targetPrefix}][${level.toUpperCase()}][${this.context}]` 
-                : `[${timestamp}][${targetPrefix}][${level.toUpperCase()}]`;
-            
-            // Output to console based on level
-            if (level === 'error') {
-                console.error(prefix, message, ...args);
-            } else if (level === 'warn') {
-                console.warn(prefix, message, ...args);
-            } else if (level === 'info') {
-                console.info(prefix, message, ...args);
-            } else {
-                console.log(prefix, message, ...args);
-            }
-            
-            // Force flush stdout if in Node.js environment to ensure logs appear immediately
-            if (typeof process !== 'undefined' && process.stdout && process.stdout.write) {
-                process.stdout.write('');
-            }
+
+        const timestamp = new Date().toISOString();
+        const targetPrefix = this.target === 'client' ? 'CLIENT' : 'SERVER';
+        const prefix = this.context
+            ? `[${timestamp}][${targetPrefix}][${level.toUpperCase()}][${this.context}]`
+            : `[${timestamp}][${targetPrefix}][${level.toUpperCase()}]`;
+
+        // Output to console based on level
+        if (isError) {
+            console.error(prefix, message, ...args);
+        } else if (level === 'warn') {
+            console.warn(prefix, message, ...args);
+        } else if (level === 'info') {
+            console.info(prefix, message, ...args);
+        } else {
+            console.log(prefix, message, ...args);
         }
     }
 
@@ -203,13 +265,27 @@ export class Logger {
     }
 
     /**
-     * Set the log level
-     * @param level New log level
+     * Set the log level for this instance.
+     * Caps this component's verbosity; the target level still applies.
+     *
+     * @param level New log level (error, warn, info, debug, trace)
      */
     public setLevel(level: string): void {
+        if (Logger.LOG_LEVELS[level] === undefined) {
+            throw new Error(
+                `Logger: unknown log level '${level}'. Valid levels: ${Object.keys(Logger.LOG_LEVELS).join(', ')}`
+            );
+        }
         this.level = level;
     }
 
+    /**
+     * Get the log level configured for this instance.
+     */
+    public getLevel(): string {
+        return this.level;
+    }
+
     /**
      * Get a child logger with a sub-context
      * @param subContext Sub-context to add

package/src/utils/MxpEncryption.ts

@@ -20,9 +20,23 @@
 
 /**
  * MXP Encryption Utilities
- * 
- * Simple encryption/decryption using a shared key from environment variables.
+ *
+ * Encryption/decryption using a shared key from environment variables.
  * Uses AES-256-GCM for authenticated encryption.
+ *
+ * ## Failure policy
+ *
+ * Encryption is a security boundary, so there is no degraded mode:
+ *
+ * - `encrypt()` / `decrypt()` return `null` ONLY to mean "encryption is not
+ *   configured" (no MXP_ENCRYPTION_KEY). That is a deliberate, operator-chosen
+ *   state, not a failure.
+ * - Any actual crypto failure — bad key, bad IV, failed authentication tag,
+ *   unsupported algorithm — THROWS.
+ *
+ * Earlier versions returned the plaintext payload when encryption threw
+ * (`return encrypted || payload`), so a crypto fault silently put cleartext on
+ * the wire while the caller believed it was encrypted.
  */
 
 import * as crypto from 'crypto';
@@ -82,30 +96,34 @@ export class MxpEncryption {
     }
     
     /**
-     * Encrypt an MXP payload
+     * Encrypt an MXP payload.
+     *
+     * @returns The encrypted payload, or null if encryption is not configured.
+     * @throws If encryption IS configured but the cipher fails. Never returns
+     *         plaintext.
      */
     public encrypt(payload: MxpPayload): EncryptedPayload | null {
         if (!this.isEncryptionEnabled()) {
             return null;
         }
-        
+
         try {
             // Generate a random IV for each encryption
             const iv = crypto.randomBytes(16);
-            
+
             // Create cipher
             const cipher = crypto.createCipheriv('aes-256-gcm', this.encryptionKey!, iv);
-            
+
             // Encrypt the payload
             const payloadString = JSON.stringify(payload);
             const encrypted = Buffer.concat([
                 cipher.update(payloadString, 'utf8'),
                 cipher.final()
             ]);
-            
+
             // Get the authentication tag
             const authTag = cipher.getAuthTag();
-            
+
             return {
                 algorithm: MxpEncryptionAlgorithm.AES_256_GCM,
                 data: encrypted.toString('base64'),
@@ -113,70 +131,87 @@ export class MxpEncryption {
                 authTag: authTag.toString('base64')
             };
         } catch (error) {
-            logger.error(`Encryption failed: ${error}`);
-            return null;
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error(`Encryption failed: ${message}`);
+            throw new Error(`MXP encryption failed: ${message}`);
         }
     }
-    
+
     /**
-     * Decrypt an encrypted payload
+     * Decrypt an encrypted payload.
+     *
+     * @throws If encryption is not configured, the algorithm is unsupported, or
+     *         the ciphertext fails authentication.
      */
-    public decrypt(encryptedPayload: EncryptedPayload): MxpPayload | null {
+    public decrypt(encryptedPayload: EncryptedPayload): MxpPayload {
         if (!this.isEncryptionEnabled()) {
-            logger.error('Cannot decrypt - encryption not configured');
-            return null;
+            throw new Error(
+                'Cannot decrypt MXP payload: encryption is not configured. Set MXP_ENCRYPTION_KEY and MXP_ENCRYPTION_SALT.'
+            );
         }
-        
+
         if (encryptedPayload.algorithm !== MxpEncryptionAlgorithm.AES_256_GCM) {
-            logger.error(`Unsupported encryption algorithm: ${encryptedPayload.algorithm}`);
-            return null;
+            throw new Error(`Unsupported MXP encryption algorithm: ${encryptedPayload.algorithm}`);
         }
-        
+
         try {
             // Decode from base64
             const encrypted = Buffer.from(encryptedPayload.data, 'base64');
             const iv = Buffer.from(encryptedPayload.iv, 'base64');
             const authTag = Buffer.from(encryptedPayload.authTag, 'base64');
-            
+
             // Create decipher
             const decipher = crypto.createDecipheriv('aes-256-gcm', this.encryptionKey!, iv);
             decipher.setAuthTag(authTag);
-            
-            // Decrypt
+
+            // Decrypt — final() throws if the authentication tag does not match
             const decrypted = Buffer.concat([
                 decipher.update(encrypted),
                 decipher.final()
             ]);
-            
+
             // Parse the JSON payload
             return JSON.parse(decrypted.toString('utf8'));
         } catch (error) {
-            logger.error(`Decryption failed: ${error}`);
-            return null;
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error(`Decryption failed: ${message}`);
+            throw new Error(`MXP decryption failed: ${message}`);
         }
     }
-    
+
     /**
-     * Encrypt a full message payload (for convenience)
+     * Encrypt a full message payload.
+     *
+     * @returns The encrypted payload, or the original payload when encryption
+     *          is not configured.
+     * @throws If encryption is configured but fails.
      */
     public encryptMessage(payload: MxpPayload): MxpPayload | EncryptedPayload {
         if (!this.isEncryptionEnabled()) {
-            return payload; // Return unencrypted if encryption is disabled
+            return payload; // Encryption not configured — caller opted out
         }
-        
+
         const encrypted = this.encrypt(payload);
-        return encrypted || payload; // Fallback to unencrypted on error
+        if (!encrypted) {
+            // isEncryptionEnabled() was true, so encrypt() either returns a
+            // payload or throws. Reaching here means the two disagree.
+            throw new Error('MXP encryption is enabled but produced no payload');
+        }
+
+        return encrypted;
     }
-    
+
     /**
-     * Decrypt a message payload (with type checking)
+     * Decrypt a message payload (with type checking).
+     *
+     * @throws If the payload is encrypted and decryption fails.
      */
-    public decryptMessage(payload: MxpPayload | EncryptedPayload): MxpPayload | null {
+    public decryptMessage(payload: MxpPayload | EncryptedPayload): MxpPayload {
         // Check if it's an encrypted payload
         if ('algorithm' in payload && 'data' in payload && 'iv' in payload) {
             return this.decrypt(payload as EncryptedPayload);
         }
-        
+
         // It's already decrypted
         return payload as MxpPayload;
     }

package/dist/mxp/MxpEventForwardingEnhancer.d.ts

@@ -1,134 +0,0 @@
-/**
- * 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/BradA1878/model-exchange-framework
- * @documentation https://mxf-dev.github.io/mxf/
- */
-import { CompressionResult } from './BinaryProtocolLayer.js';
-export declare enum EventPriority {
-    CRITICAL = 0,// System failures, agent disconnections
-    HIGH = 1,// Task assignments, tool results  
-    NORMAL = 2,// Agent messages, status updates
-    LOW = 3,// Discovery requests, heartbeats
-    BACKGROUND = 4
-}
-export interface MxpQueuedEvent {
-    id: string;
-    priority: EventPriority;
-    type: 'agent' | 'channel';
-    eventName: string;
-    payload: any;
-    targetId: string;
-    excludedAgentId?: string;
-    timestamp: number;
-    retryCount: number;
-    compressionEnabled?: boolean;
-    originalSize?: number;
-    compressedData?: CompressionResult;
-    channelId?: string;
-}
-export interface MxpEventQueueConfig {
-    enabled: boolean;
-    batchSize: number;
-    processingDelayMs: number;
-    maxQueueSize: number;
-    maxRetries: number;
-    mxpEnabled: boolean;
-    compressionByPriority: {
-        [key in EventPriority]: {
-            enabled: boolean;
-            algorithm: 'none' | 'msgpack' | 'msgpack-compressed';
-            minSize: number;
-        };
-    };
-}
-export declare class MxpEventForwardingEnhancer {
-    private static instance;
-    private readonly logger;
-    private readonly validator;
-    private config;
-    private enhancedQueues;
-    private processing;
-    private processingTimer;
-    private stats;
-    private constructor();
-    /**
-     * Get the singleton instance of MxpEventForwardingEnhancer
-     */
-    static getInstance(): MxpEventForwardingEnhancer;
-    /**
-     * Enhanced event queueing with MXP compression support
-     * Only applies compression when bandwidth optimization is enabled
-     */
-    enqueueEvent(eventName: string, payload: any, priority: EventPriority, targetId: string, type: 'agent' | 'channel', channelId?: string, excludedAgentId?: string): Promise<void>;
-    /**
-     * Enhanced batch processing with MXP compression awareness
-     */
-    private processBatch;
-    /**
-     * Apply MXP compression to an event if warranted
-     */
-    private applyMxpCompression;
-    /**
-     * Check if an event should be compressed based on configuration
-     */
-    private shouldCompressEvent;
-    /**
-     * Process a compressed event (placeholder for actual forwarding logic)
-     */
-    private processCompressedEvent;
-    /**
-     * Process an uncompressed event (placeholder for actual forwarding logic)
-     */
-    private processUncompressedEvent;
-    /**
-     * Start enhanced batch processing
-     */
-    startProcessing(): void;
-    /**
-     * Stop enhanced batch processing
-     */
-    stopProcessing(): void;
-    /**
-     * Schedule next batch processing
-     */
-    private scheduleNextBatch;
-    /**
-     * Get MXP-enhanced queue statistics
-     */
-    getEnhancedStats(): {
-        totalEvents: number;
-        compressedEvents: number;
-        compressionRate: number;
-        totalBandwidthSaved: number;
-        averageCompressionRatio: number;
-        queueSizes: Record<string, number>;
-        processingTimeMs: number;
-    };
-    /**
-     * Update configuration at runtime
-     */
-    updateConfig(newConfig: Partial<MxpEventQueueConfig>): void;
-    /**
-     * Clear all queues (useful for testing or shutdown)
-     */
-    clearQueues(): void;
-    /**
-     * Check if MXP enhancement is enabled
-     */
-    isMxpEnabled(): boolean;
-}
-//# sourceMappingURL=MxpEventForwardingEnhancer.d.ts.map

package/dist/mxp/MxpEventForwardingEnhancer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"MxpEventForwardingEnhancer.d.ts","sourceRoot":"","sources":["../../src/mxp/MxpEventForwardingEnhancer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgBH,OAAO,EAAuB,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlF,oBAAY,aAAa;IACrB,QAAQ,IAAI,CAAK,wCAAwC;IACzD,IAAI,IAAI,CAAS,mCAAmC;IACpD,MAAM,IAAI,CAAO,iCAAiC;IAClD,GAAG,IAAI,CAAU,iCAAiC;IAClD,UAAU,IAAI;CACjB;AAGD,MAAM,WAAW,cAAc;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,GAAG,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IAGnB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,iBAAiB,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,mBAAmB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IAGnB,UAAU,EAAE,OAAO,CAAC;IACpB,qBAAqB,EAAE;SAClB,GAAG,IAAI,aAAa,GAAG;YACpB,OAAO,EAAE,OAAO,CAAC;YACjB,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,oBAAoB,CAAC;YACrD,OAAO,EAAE,MAAM,CAAC;SACnB;KACJ,CAAC;CACL;AAwCD,qBAAa,0BAA0B;IACnC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2C;IAElE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuD;IACjF,OAAO,CAAC,MAAM,CAAsB;IAGpC,OAAO,CAAC,cAAc,CAAmD;IACzE,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,eAAe,CAA+B;IAGtD,OAAO,CAAC,KAAK,CAMX;IAEF,OAAO;IAaP;;OAEG;WACW,WAAW,IAAI,0BAA0B;IAOvD;;;OAGG;IACU,YAAY,CACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,GAAG,EACZ,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,IAAI,CAAC;IAgEhB;;OAEG;YACW,YAAY;IA8C1B;;OAEG;YACW,mBAAmB;IA0DjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAK3B;;OAEG;YACW,sBAAsB;IAcpC;;OAEG;YACW,wBAAwB;IAKtC;;OAEG;IACI,eAAe,IAAI,IAAI;IAO9B;;OAEG;IACI,cAAc,IAAI,IAAI;IAQ7B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IASzB;;OAEG;IACI,gBAAgB,IAAI;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;QACxB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,uBAAuB,EAAE,MAAM,CAAC;QAChC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnC,gBAAgB,EAAE,MAAM,CAAC;KAC5B;IAkBD;;OAEG;IACI,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI;IAIlE;;OAEG;IACI,WAAW,IAAI,IAAI;IAM1B;;OAEG;IACI,YAAY,IAAI,OAAO;CAGjC"}