@mxf-dev/core 1.0.1 → 2.0.1

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);
     }
 }

package/src/config/memory-strata.config.ts

@@ -0,0 +1,136 @@
+/**
+ * Memory strata configuration (Nested Learning).
+ *
+ * The strata services — StratumManager, SurpriseCalculator, MemoryCompressor,
+ * RetentionGateService — take their configuration as a constructor argument, and until
+ * now the only place that argument was ever built was inside test files. There was no
+ * production configuration path and no boot-time initialization, so StratumManager stayed
+ * disabled no matter what MEMORY_STRATA_ENABLED was set to, and the whole layer — which
+ * PhaseMemoryOperations and PhaseStrataRouter sit on top of — was inert.
+ *
+ * This module is the missing production path. It reads the same env flag the rest of the
+ * framework already exposes and produces a config the server initializes the strata
+ * services with at boot.
+ */
+
+import { MemoryStrataConfig, MemoryImportance } from '../types/MemoryStrataTypes.js';
+import { isMemoryStrataEnabled } from './FeatureFlags.js';
+
+export { isMemoryStrataEnabled };
+
+const MINUTE = 60 * 1000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+const parseIntEnv = (value: string | undefined, fallback: number): number => {
+    if (value === undefined || value.trim() === '') {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(
+            `Invalid integer for memory strata configuration: "${value}". ` +
+            `Remove the variable to use the default (${fallback}), or set a whole number.`
+        );
+    }
+    return parsed;
+};
+
+const parseFloatEnv = (value: string | undefined, fallback: number): number => {
+    if (value === undefined || value.trim() === '') {
+        return fallback;
+    }
+    const parsed = Number.parseFloat(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(
+            `Invalid number for memory strata configuration: "${value}". ` +
+            `Remove the variable to use the default (${fallback}), or set a number.`
+        );
+    }
+    return parsed;
+};
+
+/**
+ * Resolve the minimum long-term importance, which is a numeric enum, not a string.
+ */
+const parseImportanceEnv = (value: string | undefined): MemoryImportance => {
+    if (value === undefined || value.trim() === '') {
+        return MemoryImportance.Medium;
+    }
+    const byName = (MemoryImportance as unknown as Record<string, number>)[value.trim()];
+    if (typeof byName === 'number') {
+        return byName as MemoryImportance;
+    }
+    throw new Error(
+        `Invalid MEMORY_STRATA_LONG_TERM_MIN_IMPORTANCE: "${value}". ` +
+        `Expected one of: Critical, High, Medium, Low, Trivial.`
+    );
+};
+
+/**
+ * Build the strata configuration from the environment.
+ *
+ * Invalid numeric values throw rather than silently falling back, so a typo in a tuning
+ * variable surfaces at boot instead of quietly changing how memory is retained.
+ */
+export function getMemoryStrataConfig(): MemoryStrataConfig {
+    return {
+        enabled: isMemoryStrataEnabled(),
+
+        working: {
+            maxEntries: parseIntEnv(process.env.MEMORY_STRATA_WORKING_MAX_ENTRIES, 50),
+            ttl: parseIntEnv(process.env.MEMORY_STRATA_WORKING_TTL_MS, 30 * MINUTE)
+        },
+
+        shortTerm: {
+            maxEntries: parseIntEnv(process.env.MEMORY_STRATA_SHORT_TERM_MAX_ENTRIES, 500),
+            ttl: parseIntEnv(process.env.MEMORY_STRATA_SHORT_TERM_TTL_MS, 7 * DAY),
+            consolidationThreshold: parseIntEnv(
+                process.env.MEMORY_STRATA_SHORT_TERM_CONSOLIDATION_THRESHOLD,
+                3
+            )
+        },
+
+        longTerm: {
+            maxEntriesPerAgent: parseIntEnv(process.env.MEMORY_STRATA_LONG_TERM_MAX_ENTRIES, 5000),
+            minImportance: parseImportanceEnv(process.env.MEMORY_STRATA_LONG_TERM_MIN_IMPORTANCE),
+            enableArchival: process.env.MEMORY_STRATA_LONG_TERM_ARCHIVAL !== 'false',
+            archivalAge: parseIntEnv(process.env.MEMORY_STRATA_LONG_TERM_ARCHIVAL_AGE_MS, 90 * DAY)
+        },
+
+        episodic: {
+            maxEpisodesPerAgent: parseIntEnv(process.env.MEMORY_STRATA_EPISODIC_MAX_EPISODES, 200),
+            episodeDuration: parseIntEnv(process.env.MEMORY_STRATA_EPISODIC_DURATION_MS, HOUR)
+        },
+
+        semantic: {
+            maxConceptsPerAgent: parseIntEnv(process.env.MEMORY_STRATA_SEMANTIC_MAX_CONCEPTS, 1000),
+            minConfidence: parseFloatEnv(process.env.MEMORY_STRATA_SEMANTIC_MIN_CONFIDENCE, 0.6)
+        },
+
+        surprise: {
+            enabled: process.env.MEMORY_STRATA_SURPRISE_ENABLED !== 'false',
+            threshold: parseFloatEnv(process.env.MEMORY_STRATA_SURPRISE_THRESHOLD, 0.5),
+            analysisWindow: parseIntEnv(process.env.MEMORY_STRATA_SURPRISE_WINDOW, 20)
+        },
+
+        consolidation: {
+            enabled: process.env.MEMORY_STRATA_CONSOLIDATION_ENABLED !== 'false',
+            interval: parseIntEnv(process.env.MEMORY_STRATA_CONSOLIDATION_INTERVAL_MS, HOUR),
+            similarityThreshold: parseFloatEnv(
+                process.env.MEMORY_STRATA_CONSOLIDATION_SIMILARITY,
+                0.85
+            )
+        },
+
+        patterns: {
+            enabled: process.env.MEMORY_STRATA_PATTERNS_ENABLED !== 'false',
+            minLength: parseIntEnv(process.env.MEMORY_STRATA_PATTERN_MIN_LENGTH, 3),
+            minConfidence: parseFloatEnv(process.env.MEMORY_STRATA_PATTERN_MIN_CONFIDENCE, 0.7),
+            analysisInterval: parseIntEnv(
+                process.env.MEMORY_STRATA_PATTERN_ANALYSIS_INTERVAL_MS,
+                30 * MINUTE
+            )
+        }
+    };
+}

package/src/constants/ToolNames.ts

@@ -53,19 +53,10 @@ export const COORDINATION_TOOLS = {
     LIST: 'coordination_list'
 } as const;
 
-/**
- * Control Loop Tools - ORPAR cognitive cycle management
- */
-export const CONTROL_LOOP_TOOLS = {
-    START: 'controlLoop_start',
-    STOP: 'controlLoop_stop',
-    STATUS: 'controlLoop_status',
-    OBSERVE: 'controlLoop_observe',
-    REASON: 'controlLoop_reason',
-    PLAN: 'controlLoop_plan',
-    EXECUTE: 'controlLoop_execute',
-    REFLECT: 'controlLoop_reflect'
-} as const;
+// The controlLoop_* tool family was removed. It was a second, parallel implementation of
+// the ORPAR cognitive cycle with its own state machine and result shape, and agents could
+// see both families at once. orpar_* is the maintained one; controlLoop_status also
+// returned fabricated metrics. See protocols/mcp/tools/OrparTools.ts.
 
 /**
  * Infrastructure Tools - System interaction and data management
@@ -325,7 +316,6 @@ export const ALL_INTERNAL_TOOLS = {
     ...WOLFRAM_TOOLS,
     ...COMMUNICATION_TOOLS,
     ...COORDINATION_TOOLS,
-    ...CONTROL_LOOP_TOOLS,
     ...INFRASTRUCTURE_TOOLS,
     ...CONTEXT_MEMORY_TOOLS,
     ...META_TOOLS,
@@ -409,7 +399,6 @@ export const TOOL_CATEGORIES = {
  */
 export type CommunicationToolName = typeof COMMUNICATION_TOOLS[keyof typeof COMMUNICATION_TOOLS];
 export type CoordinationToolName = typeof COORDINATION_TOOLS[keyof typeof COORDINATION_TOOLS];
-export type ControlLoopToolName = typeof CONTROL_LOOP_TOOLS[keyof typeof CONTROL_LOOP_TOOLS];
 export type InfrastructureToolName = typeof INFRASTRUCTURE_TOOLS[keyof typeof INFRASTRUCTURE_TOOLS];
 export type ContextMemoryToolName = typeof CONTEXT_MEMORY_TOOLS[keyof typeof CONTEXT_MEMORY_TOOLS];
 export type MetaToolName = typeof META_TOOLS[keyof typeof META_TOOLS];
@@ -461,9 +450,6 @@ export const getToolCategory = (toolName: string): ToolCategory | null => {
     if (Object.values(COORDINATION_TOOLS).includes(toolName as CoordinationToolName)) {
         return TOOL_CATEGORIES.COORDINATION;
     }
-    if (Object.values(CONTROL_LOOP_TOOLS).includes(toolName as ControlLoopToolName)) {
-        return TOOL_CATEGORIES.CONTROL_LOOP;
-    }
     if (Object.values(INFRASTRUCTURE_TOOLS).includes(toolName as InfrastructureToolName)) {
         return TOOL_CATEGORIES.INFRASTRUCTURE;
     }

package/src/database/DatabaseAdapterFactory.ts

@@ -73,6 +73,14 @@ export class DatabaseAdapterFactory {
     private static config: DatabaseConfig | null = null;
     private static connected: boolean = false;
 
+    /**
+     * True only when connect() opened the connection itself, as opposed to
+     * reusing one the host application (e.g. the server) had already opened.
+     * disconnect() closes the connection only in the first case — otherwise the
+     * factory would close the server's connection out from under it.
+     */
+    private static ownsConnection: boolean = false;
+
     /**
      * Initialize the factory with database configuration.
      * Must be called before create().
@@ -81,6 +89,7 @@ export class DatabaseAdapterFactory {
         this.config = config;
         this.instance = null; // Reset instance on re-initialization
         this.connected = false;
+        this.ownsConnection = false;
     }
 
     /**
@@ -115,7 +124,8 @@ export class DatabaseAdapterFactory {
     private static async connectMongo(): Promise<void> {
         // Check if mongoose is already connected (e.g., server has established connection)
         if (mongoose.connection.readyState === 1) {
-            // Already connected, reuse existing connection
+            // Reuse the existing connection. We did not open it, so we must not close it.
+            this.ownsConnection = false;
             return;
         }
 
@@ -127,6 +137,7 @@ export class DatabaseAdapterFactory {
         };
 
         await mongoose.connect(this.config!.connectionString, options);
+        this.ownsConnection = true;
     }
 
     /**
@@ -180,22 +191,28 @@ export class DatabaseAdapterFactory {
         this.instance = null;
         this.config = null;
         this.connected = false;
+        this.ownsConnection = false;
     }
 
     /**
      * Disconnect from the database.
-     * Note: Only disconnects if the factory established the connection.
-     * If mongoose was already connected (e.g., by server), this is a no-op.
+     *
+     * Closes the connection only when connect() opened it. If mongoose was
+     * already connected when connect() ran — the usual case inside the server —
+     * the connection belongs to the host and is left alone.
+     *
+     * Previously `connected` was set true in both cases, so calling disconnect()
+     * closed the server's own mongoose connection.
      */
     static async disconnect(): Promise<void> {
-        if (this.connected && this.config?.type === 'mongodb') {
-            // Only disconnect if we established the connection
-            // Check if mongoose connection was established by us
+        if (this.connected && this.ownsConnection && this.config?.type === 'mongodb') {
             if (mongoose.connection.readyState === 1) {
                 await mongoose.connection.close();
             }
         }
+
         this.connected = false;
+        this.ownsConnection = false;
     }
 
     /**

package/src/database/adapters/mongodb/MongoBaseRepository.ts

@@ -184,7 +184,13 @@ export abstract class MongoBaseRepository<T, D extends Document, CreateDTO = Par
     }
 
     /**
-     * Map comparison operator to MongoDB operator
+     * Map comparison operator to MongoDB operator.
+     *
+     * An unknown operator throws. Defaulting to '$eq' turned, say, a mistyped
+     * 'gte' into an equality match: the query ran, returned the wrong rows, and
+     * nothing anywhere said so.
+     *
+     * @throws If the operator is not one this repository supports
      */
     private mapComparisonOperator(op: ComparisonOperator): string {
         const mapping: Record<string, string> = {
@@ -198,6 +204,14 @@ export abstract class MongoBaseRepository<T, D extends Document, CreateDTO = Par
             'nin': '$nin',
             'regex': '$regex'
         };
-        return mapping[op] || '$eq';
+
+        const mongoOperator = mapping[op];
+        if (!mongoOperator) {
+            throw new Error(
+                `Unsupported comparison operator '${op}'. Supported operators: ${Object.keys(mapping).join(', ')}`
+            );
+        }
+
+        return mongoOperator;
     }
 }