@mxf-dev/core 1.0.1 → 2.0.0

package/dist/utils/Logger.js

@@ -17,14 +17,15 @@
  * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
-// Default logging configuration
+// Default logging configuration.
+// `enabled: false` gates info/warn/debug/trace only — errors are always written.
 const LOGGING_CONFIG = {
     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'
     }
 };
@@ -69,15 +70,44 @@ 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, context = '', target = '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".
+     */
+    resolveEffectiveLevel() {
+        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
@@ -85,38 +115,39 @@ export class Logger {
      * @param args Additional arguments
      */
     log(level, message, ...args) {
-        // 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);
         }
     }
     /**
@@ -160,12 +191,23 @@ export class Logger {
         this.log('trace', message, ...args);
     }
     /**
-     * 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)
      */
     setLevel(level) {
+        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.
+     */
+    getLevel() {
+        return this.level;
+    }
     /**
      * Get a child logger with a sub-context
      * @param subContext Sub-context to add

package/dist/utils/Logger.js.map

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

package/dist/utils/MxpEncryption.d.ts

@@ -36,21 +36,34 @@ export declare class MxpEncryption {
      */
     isEncryptionEnabled(): boolean;
     /**
-     * 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.
      */
     encrypt(payload: MxpPayload): EncryptedPayload | null;
     /**
-     * Decrypt an encrypted payload
+     * Decrypt an encrypted payload.
+     *
+     * @throws If encryption is not configured, the algorithm is unsupported, or
+     *         the ciphertext fails authentication.
      */
-    decrypt(encryptedPayload: EncryptedPayload): MxpPayload | null;
+    decrypt(encryptedPayload: EncryptedPayload): MxpPayload;
     /**
-     * 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.
      */
     encryptMessage(payload: MxpPayload): MxpPayload | EncryptedPayload;
     /**
-     * Decrypt a message payload (with type checking)
+     * Decrypt a message payload (with type checking).
+     *
+     * @throws If the payload is encrypted and decryption fails.
      */
-    decryptMessage(payload: MxpPayload | EncryptedPayload): MxpPayload | null;
+    decryptMessage(payload: MxpPayload | EncryptedPayload): MxpPayload;
     /**
      * Generate a secure random key (utility for initial setup)
      */

package/dist/utils/MxpEncryption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MxpEncryption.d.ts","sourceRoot":"","sources":["../../src/utils/MxpEncryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAWH,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAA0B,MAAM,kCAAkC,CAAC;AAKxG;;GAEG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAgB;IACvC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,SAAS,CAAkB;IAEnC,OAAO;WAIO,WAAW,IAAI,aAAa;IAO1C;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;OAEG;IACI,mBAAmB,IAAI,OAAO;IAIrC;;OAEG;IACI,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,gBAAgB,GAAG,IAAI;IAkC5D;;OAEG;IACI,OAAO,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,UAAU,GAAG,IAAI;IAmCrE;;OAEG;IACI,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,gBAAgB;IASzE;;OAEG;IACI,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,gBAAgB,GAAG,UAAU,GAAG,IAAI;IAUhF;;OAEG;WACW,iBAAiB,IAAI,MAAM;CAG5C;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,eAA8B,CAAC"}
+{"version":3,"file":"MxpEncryption.d.ts","sourceRoot":"","sources":["../../src/utils/MxpEncryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAyBH,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAA0B,MAAM,kCAAkC,CAAC;AAKxG;;GAEG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAgB;IACvC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,SAAS,CAAkB;IAEnC,OAAO;WAIO,WAAW,IAAI,aAAa;IAO1C;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;OAEG;IACI,mBAAmB,IAAI,OAAO;IAIrC;;;;;;OAMG;IACI,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,gBAAgB,GAAG,IAAI;IAmC5D;;;;;OAKG;IACI,OAAO,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,UAAU;IAoC9D;;;;;;OAMG;IACI,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,gBAAgB;IAezE;;;;OAIG;IACI,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,gBAAgB,GAAG,UAAU;IAUzE;;OAEG;WACW,iBAAiB,IAAI,MAAM;CAG5C;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,eAA8B,CAAC"}

package/dist/utils/MxpEncryption.js

@@ -20,8 +20,22 @@
 /**
  * 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';
 import { requireEnv } from './env.js';
@@ -70,7 +84,11 @@ export class MxpEncryption {
         return this.isEnabled && this.encryptionKey !== null;
     }
     /**
-     * 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.
      */
     encrypt(payload) {
         if (!this.isEncryptionEnabled()) {
@@ -97,21 +115,23 @@ export class MxpEncryption {
             };
         }
         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.
      */
     decrypt(encryptedPayload) {
         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
@@ -121,7 +141,7 @@ export class MxpEncryption {
             // 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()
@@ -130,22 +150,34 @@ export class MxpEncryption {
             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.
      */
     encryptMessage(payload) {
         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.
      */
     decryptMessage(payload) {
         // Check if it's an encrypted payload

package/dist/utils/MxpEncryption.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mxf-dev/core",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Model Exchange Framework core: events, schemas, types, services, and protocol contracts",
   "type": "module",
   "license": "Apache-2.0",
@@ -37,7 +37,6 @@
     "README.md",
     "LICENSE"
   ],
-  "sideEffects": false,
   "scripts": {
     "build": "tsc -b",
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
@@ -45,27 +44,38 @@
   },
   "dependencies": {
     "@google/genai": "^0.9.0",
+    "@mozilla/readability": "^0.6.0",
     "@msgpack/msgpack": "^3.1.2",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "bcrypt": "^5.1.1",
     "dockerode": "^4.0.2",
+    "dompurify": "^3.2.4",
+    "html-to-text": "^9.0.5",
+    "jsdom": "^26.0.0",
     "meilisearch": "^0.53.0",
     "mongoose": "^8.10.2",
     "openai": "^4.95.1",
-    "puppeteer": "^24.11.2",
     "rxjs": "^7.8.2",
+    "turndown": "^7.2.0",
     "uuid": "^9.0.1",
     "zod": "^3.24.3"
   },
   "peerDependencies": {
     "@tensorflow/tfjs": "^4.22.0",
+    "bcrypt": "^5.1.1",
+    "puppeteer": "^24.11.2",
     "socket.io": "^4.7.2"
   },
   "peerDependenciesMeta": {
     "@tensorflow/tfjs": {
       "optional": true
     },
+    "bcrypt": {
+      "optional": true
+    },
+    "puppeteer": {
+      "optional": true
+    },
     "socket.io": {
       "optional": true
     }
@@ -74,7 +84,12 @@
     "@tensorflow/tfjs": "^4.22.0",
     "@types/bcrypt": "^5.0.2",
     "@types/dockerode": "^3.3.24",
+    "@types/html-to-text": "^9.0.4",
+    "@types/jsdom": "^21.1.7",
     "@types/node": "^20.10.5",
+    "@types/turndown": "^5.0.5",
+    "bcrypt": "^5.1.1",
+    "puppeteer": "^24.11.2",
     "socket.io": "^4.7.2",
     "typescript": "^5.2.2"
   },

package/src/adapters/FrameworkAdapter.ts

@@ -123,7 +123,7 @@ export abstract class FrameworkAdapter {
 
     constructor(config: FrameworkAdapterConfig) {
         this.config = config;
-        this.logger = new Logger('FrameworkAdapter');
+        this.logger = new Logger('info', 'FrameworkAdapter');
 
         this.logger.info('Initialized framework adapter', {
             frameworkName: config.frameworkName,

package/src/config/ConfigManager.ts

@@ -25,6 +25,7 @@
  * Enables dynamic configuration of agent behaviors and capabilities.
  */
 
+import { readFile } from 'node:fs/promises';
 import { Observable, from } from 'rxjs';
 import { map } from 'rxjs/operators';
 import { Logger } from '../utils/Logger.js';
@@ -750,24 +751,55 @@ export class ConfigManager implements IConfigManager {
     }
     
     /**
-     * Load configuration from a file
-     * @param filePath - Path to configuration file
+     * Load configuration from a JSON file and merge it over the defaults.
+     *
+     * Errors are surfaced through the Observable: a missing file, unreadable
+     * file, or malformed JSON is a configuration error the caller must see.
+     * (This method previously logged "not fully implemented" and handed back the
+     * current config, so callers believed they had loaded a file they had not.)
+     *
+     * @param filePath - Path to a JSON configuration file
+     * @returns Observable of the merged configuration
      */
     public loadConfigFromFile(filePath: string): Observable<SdkConfig> {
-        // In a browser environment, we would use fetch
-        // In Node.js, we would use fs.readFile
-        
-        // This is a simplified implementation that assumes we're in a Node.js environment
-        try {
-            // Note: In a real implementation, this would be asynchronous
-            // For now, we'll just return the current config
-            this.logger.warn(`loadConfigFromFile not fully implemented. File path: ${filePath}`);
-            
-            return from(Promise.resolve(this.config));
-        } catch (error) {
-            this.logger.error(`Failed to load configuration from file: ${error}`);
-            return from(Promise.resolve(this.config));
+        if (typeof filePath !== 'string' || filePath.trim() === '') {
+            throw new Error('loadConfigFromFile requires a non-empty file path');
         }
+
+        const load = async (): Promise<SdkConfig> => {
+            let fileContents: string;
+            try {
+                fileContents = await readFile(filePath, 'utf8');
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.logger.error(`Failed to read configuration file '${filePath}': ${message}`);
+                throw new Error(`Failed to read configuration file '${filePath}': ${message}`);
+            }
+
+            let parsed: unknown;
+            try {
+                parsed = JSON.parse(fileContents);
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.logger.error(`Configuration file '${filePath}' is not valid JSON: ${message}`);
+                throw new Error(`Configuration file '${filePath}' is not valid JSON: ${message}`);
+            }
+
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                throw new Error(`Configuration file '${filePath}' must contain a JSON object`);
+            }
+
+            // Merge, validate and emit CONFIG_UPDATED through the normal path.
+            this.config = this.mergeConfigs(DEFAULT_CONFIG, parsed as Partial<SdkConfig>);
+            this.validateConfig();
+            this.emitConfigUpdated(['all']);
+
+            this.logger.info(`Loaded configuration from '${filePath}'`);
+
+            return this.config;
+        };
+
+        return from(load());
     }
     
     /**
@@ -1397,10 +1429,11 @@ export class ConfigManager implements IConfigManager {
             data,
             { source: 'ConfigManager' }
         );
-        // Emit to client bus - will propagate to server via shared eventSubject
+        // Emit once. Both buses push into the SAME RxJS Subject (see EventBus.ts),
+        // so emitting on both delivered every local subscriber two copies of the
+        // event. The client bus is the right one here: ConfigManager runs in the
+        // SDK, and the shared Subject already carries the event to server-side
+        // subscribers.
         EventBus.client.emit(ConfigEvents.CHANNEL_SYSTEM_LLM_CHANGED, payload);
-
-        // Also emit to server bus to ensure propagation
-        EventBus.server.emit(ConfigEvents.CHANNEL_SYSTEM_LLM_CHANGED, payload);
     }
 }