@mxf-dev/core 1.0.1 → 2.0.0

package/src/events/event-definitions/LlmBudgetEvents.ts

@@ -0,0 +1,74 @@
+/**
+ * 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/
+ */
+
+/**
+ * LLM Budget Events
+ *
+ * Emitted as SystemLLM spend approaches and crosses its daily ceiling. SystemLLM runs on
+ * Claude Opus and had no absolute spend cap — only per-channel and global cooldowns — so
+ * a busy or looping channel could run up real cost with nothing to stop it. These events
+ * make that spend observable, and the EXCEEDED event marks the point where SystemLLM
+ * calls start being refused.
+ */
+
+import { AgentId, ChannelId } from '../../types/ChannelContext.js';
+
+/**
+ * Events emitted as SystemLLM spend approaches and crosses the daily ceiling.
+ */
+export const LlmBudgetEvents = {
+    /** Spend crossed the warning threshold. SystemLLM is still running. */
+    WARNING: 'llm:budget:warning',
+    /** Spend reached the daily ceiling. SystemLLM calls are refused until reset. */
+    EXCEEDED: 'llm:budget:exceeded',
+    /** A new budget day started and spend went back to zero. */
+    RESET: 'llm:budget:reset'
+} as const;
+
+/**
+ * Spend figures carried by every budget event.
+ */
+export interface LlmBudgetEventData {
+    /** Money spent so far in the current budget day, in USD. */
+    spentUsd: number;
+    /** The daily ceiling, in USD. */
+    limitUsd: number;
+    /** Fraction of the ceiling used (spentUsd / limitUsd). */
+    utilization: number;
+    /** Start of the current budget day, as an ISO timestamp. */
+    periodStart: string;
+    /** Model whose call triggered the event, when there was one. */
+    model?: string;
+}
+
+/**
+ * Payload types for LLM budget events.
+ */
+export interface LlmBudgetPayloads {
+    'llm:budget:warning': LlmBudgetEventData;
+    'llm:budget:exceeded': LlmBudgetEventData;
+    'llm:budget:reset': LlmBudgetEventData;
+}
+
+/** Actor recorded on budget events. Spend is a property of the server, not an agent. */
+export const LLM_BUDGET_ACTOR_ID = 'system-llm-budget' as AgentId;
+
+/** Channel recorded on budget events. The ceiling is global, not per channel. */
+export const LLM_BUDGET_CHANNEL_ID = 'global' as ChannelId;

package/src/interfaces/IMemoryPersistence.ts

@@ -0,0 +1,51 @@
+/**
+ * Memory persistence contract.
+ *
+ * MemoryService lives in @mxf-dev/core but the concrete persistence implementation
+ * lives in the server (it owns the Mongoose connection). Core must not import from
+ * src/**, so the server injects its implementation into MemoryService at boot.
+ *
+ * This interface is that injection point. It exists so the dependency is typed:
+ * MemoryService previously held the persistence service as `any`, which allowed a
+ * call to `updateAgentMemoryUtility?.()` — a method that was never implemented — to
+ * compile and then silently no-op forever, discarding every learned Q-value. Typing
+ * the contract turns that class of mistake into a compile error.
+ */
+
+import { Observable } from 'rxjs';
+import { IAgentMemory, IChannelMemory } from '../types/MemoryTypes.js';
+import { MemoryUtilitySubdocument } from '../types/MemoryUtilityTypes.js';
+
+export interface IMemoryPersistence {
+    /** Load an agent's memory document. */
+    getAgentMemory(agentId: string): Observable<IAgentMemory>;
+
+    /** Persist an agent's memory document. */
+    saveAgentMemory(memory: IAgentMemory): Observable<IAgentMemory>;
+
+    /** Persist a channel's memory document. */
+    saveChannelMemory(memory: IChannelMemory): Observable<IChannelMemory>;
+
+    /**
+     * Persist the MULS utility subdocument for a single memory.
+     *
+     * Called by QValueManager's persistence callback whenever a Q-value changes, and
+     * again when a dirty cache entry is evicted. Must throw on failure — a silent
+     * failure here means the system reports learning it did not retain.
+     */
+    updateAgentMemoryUtility(
+        memoryId: string,
+        utility: Partial<MemoryUtilitySubdocument>
+    ): Promise<void>;
+
+    /**
+     * Load utility subdocuments for a batch of memories.
+     *
+     * Used to hydrate the Q-value cache on retrieval so learning survives a restart.
+     * Memories with no stored utility are simply absent from the returned map; the
+     * caller falls back to the configured default Q-value for those.
+     */
+    getAgentMemoryUtilities(
+        memoryIds: string[]
+    ): Promise<Map<string, MemoryUtilitySubdocument>>;
+}

package/src/middleware/MxpMiddleware.ts

@@ -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/channelKey.ts

@@ -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/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/user.ts

@@ -19,7 +19,36 @@
  */
 
 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);
 };