@mxf-dev/core 1.0.1 → 2.0.0

package/dist/events/ServerEventBus.js

@@ -17,12 +17,11 @@
  * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
-import { filter, map } from 'rxjs/operators';
 import { ControlLoopEvents } from './event-definitions/ControlLoopEvents.js';
 import { OrparEvents } from './event-definitions/OrparEvents.js';
 import { McpEvents } from './event-definitions/McpEvents.js';
 import { TaskEvents } from './event-definitions/TaskEvents.js';
-import { BaseEventBusImplementation, validateEventName, isReservedEvent, invokeHandlerSafely } from './EventBusBase.js';
+import { BaseEventBusImplementation, isReservedEvent } from './EventBusBase.js';
 import { createStrictValidator } from '../utils/validation.js';
 import { Logger } from '../utils/Logger.js';
 // Create a logger instance for ServerEventBus
@@ -33,20 +32,45 @@ const validator = createStrictValidator('ServerEventBus');
  * Server-side event bus implementation
  */
 export class ServerEventBus extends BaseEventBusImplementation {
+    /**
+     * Events delivered to specific agents/channels by eventForwardingHandlers.
+     * Broadcasting these over io.emit() would deliver them twice.
+     */
+    static AGENT_SPECIFIC_EVENTS = new Set([
+        ...Object.values(ControlLoopEvents),
+        ...Object.values(OrparEvents),
+        // MCP response events
+        McpEvents.TOOL_RESULT,
+        McpEvents.TOOL_ERROR,
+        McpEvents.TOOL_REGISTERED,
+        McpEvents.TOOL_UNREGISTERED,
+        McpEvents.MXF_TOOL_LIST_RESULT,
+        McpEvents.MXF_TOOL_LIST_ERROR,
+        McpEvents.RESOURCE_RESULT,
+        McpEvents.RESOURCE_ERROR,
+        McpEvents.EXTERNAL_SERVER_REGISTERED,
+        McpEvents.EXTERNAL_SERVER_UNREGISTERED,
+        McpEvents.EXTERNAL_SERVER_REGISTRATION_FAILED,
+        McpEvents.CHANNEL_SERVER_REGISTERED,
+        McpEvents.CHANNEL_SERVER_UNREGISTERED,
+        McpEvents.CHANNEL_SERVER_REGISTRATION_FAILED,
+        // Task lifecycle events
+        TaskEvents.CREATED,
+        TaskEvents.ASSIGNED,
+        TaskEvents.STARTED,
+        TaskEvents.PROGRESS_UPDATED,
+        TaskEvents.COMPLETED,
+        TaskEvents.FAILED,
+        TaskEvents.ERROR,
+        TaskEvents.CANCELLED,
+    ]);
     ioInstance = null;
-    subscriptions = [];
-    categorySubscriptions = new Map();
-    // Track subscriptions by event and handler for proper off() support
-    handlerSubscriptions = new Map();
-    debugMode = false;
-    debugSubscription = null;
     /**
      * Create a new ServerEventBus
      * @param eventSubject Subject to use for events
      */
     constructor(eventSubject) {
-        super(eventSubject);
-        //;
+        super(eventSubject, logger);
     }
     /**
      * Set the Socket.IO server instance
@@ -75,337 +99,48 @@ export class ServerEventBus extends BaseEventBusImplementation {
         return this;
     }
     /**
-     * Emit an event to the server event bus
-     * All components listen to this event bus
+     * Forward an emitted event to the Socket.IO server.
      *
-     * @param event Event name
-     * @param payload Event payload
-     */
-    emit(event, payload) {
-        try {
-            // Validate event name and payload
-            validateEventName(event);
-            this.validateEventPayload(event, payload);
-            // Handle null/undefined payload
-            if (payload === undefined || payload === null) {
-                logger.warn(`[ServerEventBus] Warning: Emitting event '${event}' with ${payload === null ? 'null' : 'undefined'} payload.`);
-                payload = {};
-            }
-            // Special logging for critical events like agent registration
-            if (event.startsWith('agent:')) {
-            }
-            // Emit to local event bus first
-            this.eventSubject.next({
-                type: event,
-                payload,
-            });
-            // Also emit to the Socket.IO server if available
-            // IMPORTANT: Do NOT broadcast agent-specific events via io.emit().
-            // These events are forwarded to specific agents/channels via
-            // eventForwardingHandlers.forwardEventToAgent()/forwardEventToChannel().
-            // Broadcasting them causes duplicates: the SDK's ClientEventBus.setupClientSocketForwarding()
-            // has socket.onAny() that re-injects received socket events back into the RxJS Subject,
-            // so MxfChannelMonitor sees each broadcast event twice (once from Subject push, once from
-            // socket re-injection).
-            const agentSpecificEvents = new Set([
-                ...Object.values(ControlLoopEvents),
-                ...Object.values(OrparEvents),
-                // MCP response events — already forwarded to specific agents via eventForwardingHandlers
-                McpEvents.TOOL_RESULT,
-                McpEvents.TOOL_ERROR,
-                McpEvents.TOOL_REGISTERED,
-                McpEvents.TOOL_UNREGISTERED,
-                McpEvents.MXF_TOOL_LIST_RESULT,
-                McpEvents.MXF_TOOL_LIST_ERROR,
-                McpEvents.RESOURCE_RESULT,
-                McpEvents.RESOURCE_ERROR,
-                McpEvents.EXTERNAL_SERVER_REGISTERED,
-                McpEvents.EXTERNAL_SERVER_UNREGISTERED,
-                McpEvents.EXTERNAL_SERVER_REGISTRATION_FAILED,
-                McpEvents.CHANNEL_SERVER_REGISTERED,
-                McpEvents.CHANNEL_SERVER_UNREGISTERED,
-                McpEvents.CHANNEL_SERVER_REGISTRATION_FAILED,
-                // Task lifecycle events — already forwarded to specific agents/channels
-                TaskEvents.CREATED,
-                TaskEvents.ASSIGNED,
-                TaskEvents.STARTED,
-                TaskEvents.PROGRESS_UPDATED,
-                TaskEvents.COMPLETED,
-                TaskEvents.FAILED,
-                TaskEvents.ERROR,
-                TaskEvents.CANCELLED,
-            ]);
-            if (this.ioInstance && !isReservedEvent(event) && !agentSpecificEvents.has(event)) {
-                //;
-                this.ioInstance.emit(event, payload);
-            }
-            //;
-        }
-        catch (error) {
-            logger.error(`[ServerEventBus] Error emitting event '${event}':`, error instanceof Error ? error.message : String(error));
-            // Re-throw the error for the caller to handle
-            throw error;
-        }
-    }
-    /**
-     * Override the base on method to track handlers and subscriptions
-     * @param event Event name
-     * @param handler Event handler function
-     * @returns Subscription to use for unsubscribing
-     */
-    on(event, handler) {
-        // Create a filtered observable for this event
-        const observable = this.eventSubject.pipe(filter((e) => e.type === event), map((e) => e.payload));
-        // Subscribe with throw/rejection isolation so one bad handler cannot
-        // kill the subscription or fail silently.
-        const subscription = observable.subscribe((payload) => invokeHandlerSafely(logger, event, handler, payload));
-        // Store the subscription for cleanup
-        this.subscriptions.push(subscription);
-        // Track handlers for off() support
-        if (!this.handlerSubscriptions.has(event)) {
-            this.handlerSubscriptions.set(event, new Map());
-        }
-        const eventHandlers = this.handlerSubscriptions.get(event);
-        if (eventHandlers) {
-            eventHandlers.set(handler, subscription);
-        }
-        return subscription;
-    }
-    /**
-     * Override the base once method to track handlers and subscriptions
-     * Once the event is fired, the subscription is automatically removed
+     * Called by BaseEventBusImplementation.emit() after validation and local
+     * delivery.
      *
-     * @param event Event name
-     * @param handler Event handler function
-     * @returns Subscription to use for unsubscribing
+     * Agent-specific events are NOT broadcast with io.emit(). They are routed
+     * to individual agents/channels by eventForwardingHandlers. Broadcasting
+     * them would duplicate delivery: the SDK's ClientEventBus.setupClientSocketForwarding()
+     * re-injects everything the socket receives back into the shared RxJS Subject,
+     * so a broadcast event would be seen twice (once from the Subject push, once
+     * from the socket re-injection).
      */
-    once(event, handler) {
-        // Create a filtered observable for this event
-        const observable = this.eventSubject.pipe(filter((e) => e.type === event), map((e) => e.payload));
-        // Create a wrapper handler that will unsubscribe after first execution
-        const onceHandler = (payload) => {
-            try {
-                invokeHandlerSafely(logger, event, handler, payload);
-            }
-            finally {
-                // Always unsubscribe — once means once, even when the handler throws.
-                this.off(event, onceHandler);
-            }
-        };
-        // Subscribe to the observable with the one-time handler
-        const subscription = observable.subscribe(onceHandler);
-        // Store the subscription for cleanup
-        this.subscriptions.push(subscription);
-        // Track handlers for off() support
-        if (!this.handlerSubscriptions.has(event)) {
-            this.handlerSubscriptions.set(event, new Map());
+    forwardToTransport(event, payload) {
+        if (!this.ioInstance) {
+            return;
         }
-        const eventHandlers = this.handlerSubscriptions.get(event);
-        if (eventHandlers) {
-            eventHandlers.set(handler, subscription);
+        const eventName = String(event);
+        if (isReservedEvent(eventName) || ServerEventBus.AGENT_SPECIFIC_EVENTS.has(eventName)) {
+            return;
         }
-        return subscription;
+        this.ioInstance.emit(eventName, payload);
     }
     /**
-     * Subscribe to all events in the server event bus
+     * Drop the Socket.IO server reference so no further events are broadcast.
+     *
+     * The bus attaches no listeners to the Socket.IO server — it only calls
+     * io.emit() — so there is nothing else to detach here.
      *
-     * @param listener Listener function that receives both event type and payload
-     * @returns Subscription that can be unsubscribed to stop listening
-     */
-    onAll(listener) {
-        // Create an observable that passes both event type and payload
-        const observable = this.eventSubject.pipe(map((e) => ({ type: e.type, payload: e.payload })));
-        // Subscribe to the observable with the listener
-        const subscription = observable.subscribe(event => {
-            listener(event.type, event.payload);
-        });
-        // Store the subscription for cleanup
-        this.subscriptions.push(subscription);
-        return subscription;
-    }
-    /**
-     * Remove all server event listeners
      * @returns this (for chaining)
      */
     removeAllSocketListeners() {
-        if (this.ioInstance) {
-            try {
-                // Since Socket.IO Server doesn't have a direct equivalent to removeAllListeners(),
-                // we would need to track all listeners separately if we want to remove them.
-                // For now, we log that this operation is not fully implemented.
-            }
-            catch (error) {
-                logger.error('[ServerEventBus] Error removing socket listeners:', error instanceof Error ? error.message : String(error));
-            }
-        }
+        this.ioInstance = null;
         return this;
     }
     /**
-     * Clean up all subscriptions and listeners
+     * Dispose every subscription and detach the Socket.IO server.
+     *
      * @returns this (for chaining)
      */
     cleanup() {
-        // Clean up all subscriptions
-        this.subscriptions.forEach(subscription => subscription.unsubscribe());
-        this.subscriptions = [];
-        // Clear category subscriptions
-        this.categorySubscriptions.clear();
-        // Remove socket listeners
+        this.removeAllListeners();
         this.removeAllSocketListeners();
-        // Reset debug mode
-        this.debugMode = false;
-        this.debugSubscription = null;
-        return this;
-    }
-    /**
-     * Enable or disable debug mode to log all events
-     *
-     * @param enabled Whether debug mode should be enabled
-     * @returns this (for chaining)
-     */
-    enableDebugMode(enabled = true) {
-        // If already in the requested mode, do nothing
-        if (this.debugMode === enabled) {
-            return this;
-        }
-        this.debugMode = enabled;
-        // If enabling debug mode
-        if (enabled) {
-            // Create a subscription to all events
-            this.debugSubscription = this.onAll((eventType, payload) => {
-                // ;
-            });
-            // Make sure it's tracked for cleanup
-            if (this.debugSubscription) {
-                this.subscriptions.push(this.debugSubscription);
-            }
-        }
-        // If disabling debug mode
-        else if (this.debugSubscription) {
-            // Unsubscribe from the debug subscription
-            this.debugSubscription.unsubscribe();
-            // Remove from subscriptions array
-            const index = this.subscriptions.indexOf(this.debugSubscription);
-            if (index !== -1) {
-                this.subscriptions.splice(index, 1);
-            }
-            this.debugSubscription = null;
-        }
-        return this;
-    }
-    /**
-     * Subscribe to an event with category for grouped subscription management
-     *
-     * @param category Category name for grouping subscriptions
-     * @param event Event name to subscribe to
-     * @param listener Listener function to call when the event is emitted
-     * @returns Subscription that can be unsubscribed to stop listening
-     */
-    onWithCategory(category, event, listener) {
-        // Create a subscription using the standard on method
-        const subscription = this.on(event, listener);
-        // Store in the category map
-        if (!this.categorySubscriptions.has(category)) {
-            this.categorySubscriptions.set(category, []);
-        }
-        const categorySubs = this.categorySubscriptions.get(category);
-        if (categorySubs) {
-            categorySubs.push(subscription);
-        }
-        // ;
-        return subscription;
-    }
-    /**
-     * Unsubscribe from all events in a specific category
-     *
-     * @param category Category name to unsubscribe from
-     * @returns this (for chaining)
-     */
-    unsubscribeCategory(category) {
-        const subscriptions = this.categorySubscriptions.get(category) || [];
-        if (subscriptions.length > 0) {
-            // Unsubscribe from each subscription in the category
-            subscriptions.forEach(subscription => {
-                subscription.unsubscribe();
-                // Also remove from the main subscriptions array
-                const index = this.subscriptions.indexOf(subscription);
-                if (index !== -1) {
-                    this.subscriptions.splice(index, 1);
-                }
-            });
-            // Clear the category
-            this.categorySubscriptions.delete(category);
-        }
-        else {
-            // ;
-        }
-        return this;
-    }
-    /**
-     * Unsubscribe from an event
-     * @param event Event name
-     * @param handler Event handler function (optional)
-     */
-    off(event, handler) {
-        validateEventName(event);
-        const eventHandlers = this.handlerSubscriptions.get(event);
-        if (!eventHandlers) {
-            // No handlers for this event found
-            // ;
-            return;
-        }
-        if (handler) {
-            // If specific handler provided, just unsubscribe that one
-            const subscription = eventHandlers.get(handler);
-            if (subscription) {
-                // Unsubscribe from the RxJS subscription
-                subscription.unsubscribe();
-                // Remove from our handler registry
-                eventHandlers.delete(handler);
-                // Remove from the array if present
-                const index = this.subscriptions.indexOf(subscription);
-                if (index !== -1) {
-                    this.subscriptions.splice(index, 1);
-                }
-                // ;
-            }
-            else {
-                // ;
-            }
-        }
-        else {
-            // If no specific handler, unsubscribe all handlers for this event
-            let unsubscribedCount = 0;
-            eventHandlers.forEach((subscription) => {
-                // Unsubscribe from the RxJS subscription
-                subscription.unsubscribe();
-                // Remove from the array if present
-                const index = this.subscriptions.indexOf(subscription);
-                if (index !== -1) {
-                    this.subscriptions.splice(index, 1);
-                }
-                unsubscribedCount++;
-            });
-            // Clear all handlers for this event
-            eventHandlers.clear();
-            // ;
-        }
-    }
-    /**
-     * Remove all event listeners for a specific event or all events
-     * @param event Optional specific event name to remove listeners for
-     * @returns this (for chaining)
-     */
-    removeAllListeners(event) {
-        // Remove all event listeners
-        this.eventSubject.observers = [];
-        // Also clear our handler registries if appropriate
-        if (event) {
-            this.handlerSubscriptions.delete(event);
-        }
-        else {
-            this.handlerSubscriptions.clear();
-        }
         return this;
     }
 }

package/dist/events/ServerEventBus.js.map

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

package/dist/events/event-definitions/LlmBudgetEvents.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 declare const LlmBudgetEvents: {
+    /** Spend crossed the warning threshold. SystemLLM is still running. */
+    readonly WARNING: "llm:budget:warning";
+    /** Spend reached the daily ceiling. SystemLLM calls are refused until reset. */
+    readonly EXCEEDED: "llm:budget:exceeded";
+    /** A new budget day started and spend went back to zero. */
+    readonly RESET: "llm:budget:reset";
+};
+/**
+ * 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 declare const LLM_BUDGET_ACTOR_ID: AgentId;
+/** Channel recorded on budget events. The ceiling is global, not per channel. */
+export declare const LLM_BUDGET_CHANNEL_ID: ChannelId;
+//# sourceMappingURL=LlmBudgetEvents.d.ts.map

package/dist/events/event-definitions/LlmBudgetEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LlmBudgetEvents.d.ts","sourceRoot":"","sources":["../../../src/events/event-definitions/LlmBudgetEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;GAEG;AACH,eAAO,MAAM,eAAe;IACxB,uEAAuE;;IAEvE,gFAAgF;;IAEhF,4DAA4D;;CAEtD,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,oBAAoB,EAAE,kBAAkB,CAAC;IACzC,qBAAqB,EAAE,kBAAkB,CAAC;IAC1C,kBAAkB,EAAE,kBAAkB,CAAC;CAC1C;AAED,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,EAA0B,OAAO,CAAC;AAElE,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,EAAe,SAAS,CAAC"}

package/dist/events/event-definitions/LlmBudgetEvents.js

@@ -0,0 +1,35 @@
+/**
+ * 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/
+ */
+/**
+ * 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'
+};
+/** Actor recorded on budget events. Spend is a property of the server, not an agent. */
+export const LLM_BUDGET_ACTOR_ID = 'system-llm-budget';
+/** Channel recorded on budget events. The ceiling is global, not per channel. */
+export const LLM_BUDGET_CHANNEL_ID = 'global';
+//# sourceMappingURL=LlmBudgetEvents.js.map

package/dist/events/event-definitions/LlmBudgetEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LlmBudgetEvents.js","sourceRoot":"","sources":["../../../src/events/event-definitions/LlmBudgetEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAcH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC3B,uEAAuE;IACvE,OAAO,EAAE,oBAAoB;IAC7B,gFAAgF;IAChF,QAAQ,EAAE,qBAAqB;IAC/B,4DAA4D;IAC5D,KAAK,EAAE,kBAAkB;CACnB,CAAC;AA2BX,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAA8B,CAAC;AAElE,iFAAiF;AACjF,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAqB,CAAC"}

package/dist/interfaces/IMemoryPersistence.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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>>;
+}
+//# sourceMappingURL=IMemoryPersistence.d.ts.map

package/dist/interfaces/IMemoryPersistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMemoryPersistence.d.ts","sourceRoot":"","sources":["../../src/interfaces/IMemoryPersistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE1E,MAAM,WAAW,kBAAkB;IAC/B,uCAAuC;IACvC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IAE1D,0CAA0C;IAC1C,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IAEhE,2CAA2C;IAC3C,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAEtE;;;;;;OAMG;IACH,wBAAwB,CACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,CAAC,wBAAwB,CAAC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,uBAAuB,CACnB,SAAS,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC;CACrD"}

package/dist/interfaces/IMemoryPersistence.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=IMemoryPersistence.js.map

package/dist/interfaces/IMemoryPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMemoryPersistence.js","sourceRoot":"","sources":["../../src/interfaces/IMemoryPersistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/middleware/MxpMiddleware.d.ts

@@ -50,7 +50,14 @@ export declare class MxpMiddleware {
      */
     private static extractOperationArgs;
     /**
-     * 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;
     /**