@mxf-dev/core 1.0.0 → 2.0.0

package/src/middleware/MxpMiddleware.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 
@@ -97,23 +97,23 @@ export class MxpMiddleware {
             this.stats.mxpMessages++;
             const mxpMsg = message as MxpMessage;
             
-            // Decrypt if needed
+            // Decrypt if needed. decryptMessage() throws on failure — an
+            // undecryptable message must not be passed on as if it were fine.
             if (mxpMsg.encrypted && isEncryptedPayload(mxpMsg.payload)) {
-                const decrypted = mxpEncryption.decryptMessage(mxpMsg.payload);
-                if (decrypted) {
+                try {
+                    const decrypted = mxpEncryption.decryptMessage(mxpMsg.payload);
                     this.stats.messagesDecrypted++;
                     return {
                         ...mxpMsg,
                         payload: decrypted,
                         encrypted: false
                     };
-                } else {
-                    logger.error('Failed to decrypt MXP message');
+                } catch (error) {
                     this.stats.encryptionFailures++;
-                    throw new Error('Decryption failed');
+                    throw error;
                 }
             }
-            
+
             return mxpMsg;
         }
         
@@ -206,7 +206,14 @@ export class MxpMiddleware {
     }
     
     /**
-     * Handle encryption for MXP messages
+     * Handle encryption for MXP messages.
+     *
+     * `forceEncryption` means exactly that: if the message cannot be encrypted,
+     * this throws rather than putting the plaintext on the wire. An earlier
+     * version incremented an `encryptionFailures` counter and returned the
+     * message unencrypted, so callers that asked for encryption silently got none.
+     *
+     * @throws If forceEncryption is set and encryption is unavailable or fails.
      */
     private static handleMxpEncryption(
         message: MxpMessage,
@@ -216,26 +223,46 @@ export class MxpMiddleware {
         if (message.encrypted && isEncryptedPayload(message.payload)) {
             return message;
         }
-        
-        // Check if encryption should be applied
-        const shouldEncrypt = forceEncryption || 
+
+        if (isEncryptedPayload(message.payload)) {
+            return message;
+        }
+
+        if (forceEncryption && !mxpEncryption.isEncryptionEnabled()) {
+            this.stats.encryptionFailures++;
+            throw new Error(
+                'forceEncryption was requested but MXP encryption is not configured. ' +
+                'Set MXP_ENCRYPTION_KEY and MXP_ENCRYPTION_SALT, or stop forcing encryption.'
+            );
+        }
+
+        // Reasoning messages stay in the clear unless encryption is forced:
+        // they carry no operational payload and are meant to be human-readable.
+        const shouldEncrypt = forceEncryption ||
             (mxpEncryption.isEncryptionEnabled() && message.type !== MxpMessageType.REASONING);
-        
-        if (shouldEncrypt && !isEncryptedPayload(message.payload)) {
+
+        if (!shouldEncrypt) {
+            return message;
+        }
+
+        try {
+            // Throws on cipher failure; returns null only when encryption is off,
+            // which forceEncryption has already ruled out above.
             const encrypted = mxpEncryption.encrypt(message.payload as MxpPayload);
-            if (encrypted) {
-                this.stats.messagesEncrypted++;
-                return {
-                    ...message,
-                    encrypted: true,
-                    payload: encrypted
-                };
-            } else {
-                this.stats.encryptionFailures++;
+            if (!encrypted) {
+                return message;
             }
+
+            this.stats.messagesEncrypted++;
+            return {
+                ...message,
+                encrypted: true,
+                payload: encrypted
+            };
+        } catch (error) {
+            this.stats.encryptionFailures++;
+            throw error;
         }
-        
-        return message;
     }
     
     /**

package/src/models/PatternLearningModels.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/agent.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/auditLog.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/channel.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/channelKey.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 
@@ -35,13 +35,22 @@ import crypto from 'crypto';
 export interface IChannelKey extends Document {
     // The unique key identifier
     keyId: string;
-    
-    // The actual secret key used for authentication
+
+    // bcrypt hash of the secret. The plaintext is shown once at creation and never stored —
+    // see ChannelKeyService. It used to be kept in the clear, so any read of this
+    // collection exposed every channel credential.
     secretKey: string;
-    
+
     // Reference to the channel this key provides access to
     channelId: string;
-    
+
+    // The agent this key authenticates as.
+    //
+    // Socket authentication reads the agent's identity from here rather than from the
+    // client handshake. Previously the key authenticated the *channel* while the client
+    // chose its own agentId, so one shared key let a client present any agent identity.
+    agentId: string;
+
     // Optional name for the key (for user reference)
     name?: string;
     
@@ -79,6 +88,11 @@ const ChannelKeySchema: Schema = new Schema({
         index: true,
         ref: 'ChannelRegistration',
     },
+    agentId: {
+        type: String,
+        required: true,
+        index: true,
+    },
     name: {
         type: String,
         required: false,

package/src/models/codeExecution.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/controlLoop.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/coordination.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/document.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/entity.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/mcpTool.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/mcpToolExecution.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/memory.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/memoryStrata.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/memoryUtility.ts

@@ -0,0 +1,64 @@
+/**
+ * Memory Utility model (MULS).
+ *
+ * Stores the learned Q-value and reward statistics for a single *retrievable* memory —
+ * the unit QValueManager actually learns about, which is a document in the search index
+ * (a conversation message, action, or pattern), identified by its search-index id.
+ *
+ * Why this is its own collection: the `utility` subdocument on AgentMemory /
+ * ChannelMemory / RelationshipMemory is keyed by the id of a whole memory-scope
+ * document, whereas retrieval returns individual indexed items. Those are different
+ * granularities, so utility written onto a scope document would never match the id a
+ * retrieval learned about. That mismatch is why the previous persistence path silently
+ * matched nothing. Keying by the retrieved memory id is what makes learning durable.
+ */
+
+import mongoose, { Schema, Document, Model } from 'mongoose';
+import { QValueInitSource } from '../types/MemoryUtilityTypes.js';
+
+export interface IMemoryUtilityDocument extends Document {
+    /** The retrieved memory's id — matches the search-index document id. */
+    memoryId: string;
+    /** Agent this memory's utility was learned for (scoping and analytics). */
+    agentId?: string;
+    /** Channel this memory's utility was learned in (scoping and analytics). */
+    channelId?: string;
+    qValue: number;
+    qValueHistory: Array<{ value: number; reward: number; timestamp: Date; phase?: string }>;
+    retrievalCount: number;
+    successCount: number;
+    failureCount: number;
+    lastRewardAt?: Date;
+    initializedFrom: QValueInitSource;
+    updatedAt: Date;
+}
+
+const memoryUtilitySchema = new Schema<IMemoryUtilityDocument>({
+    memoryId: { type: String, required: true, unique: true, index: true },
+    agentId: { type: String, index: true },
+    channelId: { type: String, index: true },
+
+    qValue: { type: Number, default: 0.5, min: 0, max: 1 },
+
+    qValueHistory: [{
+        value: { type: Number, required: true },
+        reward: { type: Number, required: true },
+        timestamp: { type: Date, default: Date.now },
+        phase: { type: String }
+    }],
+
+    retrievalCount: { type: Number, default: 0 },
+    successCount: { type: Number, default: 0 },
+    failureCount: { type: Number, default: 0 },
+    lastRewardAt: { type: Date },
+    initializedFrom: { type: String, default: 'default' },
+    updatedAt: { type: Date, default: Date.now }
+});
+
+// Ranking reads sort by Q-value, scoped by agent or channel.
+memoryUtilitySchema.index({ agentId: 1, qValue: -1 });
+memoryUtilitySchema.index({ channelId: 1, qValue: -1 });
+
+export const MemoryUtility: Model<IMemoryUtilityDocument> =
+    mongoose.models.MemoryUtility ||
+    mongoose.model<IMemoryUtilityDocument>('MemoryUtility', memoryUtilitySchema);

package/src/models/personalAccessToken.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/plan.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/relationship.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/shellOutput.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/task.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/taskEffectiveness.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/tool.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/toolExecution.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/toolModels.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/models/user.ts

@@ -14,12 +14,41 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 
 import mongoose, { Document, Schema } from 'mongoose';
-import bcrypt from 'bcrypt';
+// bcrypt is an OPTIONAL peer dependency: it is a native module that has to be
+// compiled at install time, and only applications that store user passwords need
+// it. Loaded on demand; a clear error is thrown if a password operation is
+// attempted without it installed.
+import type * as BcryptModule from 'bcrypt';
+
+let bcryptModule: typeof BcryptModule | null = null;
+
+/**
+ * Load bcrypt on demand.
+ *
+ * @throws If bcrypt is not installed. Passwords are never stored unhashed.
+ */
+const loadBcrypt = async (): Promise<typeof BcryptModule> => {
+    if (bcryptModule) {
+        return bcryptModule;
+    }
+
+    try {
+        const imported = await import('bcrypt');
+        bcryptModule = (imported.default ?? imported) as typeof BcryptModule;
+        return bcryptModule;
+    } catch (error) {
+        throw new Error(
+            'Password hashing requires the optional peer dependency "bcrypt", which is not installed. ' +
+            'Install it with `bun add bcrypt` (or `npm install bcrypt`) to use the User model. ' +
+            `Underlying error: ${error instanceof Error ? error.message : String(error)}`
+        );
+    }
+};
 
 /**
  * User role enum
@@ -123,15 +152,17 @@ UserSchema.pre('save', async function(next) {
     }
     
     try {
+        const bcrypt = await loadBcrypt();
+
         // Generate a salt
         const salt = await bcrypt.genSalt(10);
-        
+
         // Hash the password along with the new salt
         this.password = await bcrypt.hash(this.password, salt);
-        
+
         // Update the updatedAt field
         this.updatedAt = new Date();
-        
+
         next();
     } catch (error) {
         next(error as Error);
@@ -140,6 +171,7 @@ UserSchema.pre('save', async function(next) {
 
 // Method to compare passwords
 UserSchema.methods.comparePassword = async function(candidatePassword: string): Promise<boolean> {
+    const bcrypt = await loadBcrypt();
     return bcrypt.compare(candidatePassword, this.password);
 };
 

package/src/models/userMemory.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */