@mxf-dev/core 1.0.1 → 2.0.0

package/src/services/PredictiveAnalyticsService.ts

@@ -67,7 +67,13 @@ export enum ModelType {
     GRADIENT_BOOSTING = 'gradient_boosting',
     NEURAL_NETWORK = 'neural_network',
     ISOLATION_FOREST = 'isolation_forest',
-    LSTM = 'lstm'
+    LSTM = 'lstm',
+    /**
+     * A rule-based heuristic, not a trained model. Exists so a heuristic result can say
+     * what it is: without it, heuristic predictions were reported to callers as
+     * GRADIENT_BOOSTING, alongside a hardcoded accuracy figure.
+     */
+    HEURISTIC = 'heuristic'
 }
 
 /**
@@ -188,14 +194,24 @@ export interface RiskScore {
  */
 export interface ModelMetadata {
     modelId: string;
+    /**
+     * Which predictor this describes ('error_prediction', 'anomaly_detection',
+     * 'pattern_forecast'). Identity has to be separate from `type`, because `type` now
+     * changes with training state — a predictor is a HEURISTIC until it is actually
+     * trained — so callers can no longer identify a predictor by its algorithm label.
+     */
+    name: string;
     type: ModelType;
     version: string;
-    trainedAt: number;
+    /** Null until the predictor has actually been trained. */
+    trainedAt: number | null;
+    /** Null for heuristics — they have no measured validation accuracy. */
     accuracy: number | null;
     features: string[];
     hyperparameters: Record<string, any>;
     trainingDataSize: number;
-    validationMetrics: Record<string, number>;
+    /** Null until a real validation run has produced metrics. */
+    validationMetrics: Record<string, number> | null;
 }
 
 /** TF.js model ID for the error prediction Dense classifier */
@@ -234,8 +250,6 @@ export class PredictiveAnalyticsService extends EventEmitter {
     // Otherwise falls back to the heuristic distance-based isolation score.
     private tfAnomalyAutoencoderReady: boolean = false;
 
-    // Models (simplified in-memory implementation)
-    private readonly models = new Map<string, any>();
     private readonly modelMetadata = new Map<string, ModelMetadata>();
     
     // Training data
@@ -601,7 +615,9 @@ export class PredictiveAnalyticsService extends EventEmitter {
             },
             features,
             model: {
-                type: usedTfModel ? ModelType.NEURAL_NETWORK : ModelType.GRADIENT_BOOSTING,
+                // Say which it actually was. A heuristic reported as GRADIENT_BOOSTING is
+                // how an unvalidated rule of thumb ends up being trusted as a trained model.
+                type: usedTfModel ? ModelType.NEURAL_NETWORK : ModelType.HEURISTIC,
                 version: modelMeta?.version || '1.0',
                 accuracy: modelMeta?.accuracy ?? null
             }
@@ -1662,37 +1678,36 @@ export class PredictiveAnalyticsService extends EventEmitter {
     /**
      * Initialize models
      */
+    /**
+     * Register metadata for the predictors this service exposes.
+     *
+     * Until a model is actually trained (see trainErrorPredictionModel and friends), every
+     * predictor here is a rule-based heuristic and is described as one. Nothing is
+     * reported as trained, and no accuracy is claimed.
+     *
+     * This previously registered three constant functions — `predict: () => ({score: 0.5,
+     * confidence: 0.7})` labelled GRADIENT_BOOSTING, and `sequence[last] * 1.1` labelled
+     * LSTM — together with a hardcoded accuracy of 0.75, a training-set size of 1000, and
+     * invented precision/recall figures, all of which were served to callers through the
+     * predictive_* tools and the REST layer. The predict functions were dead (nothing ever
+     * read this.models), but the fabricated metadata was not: it was read on every
+     * prediction. Both are gone.
+     */
     private initializeModels(): void {
-        // Initialize simplified models
-        // In production, would load actual trained models
-        
-        this.models.set('error_prediction', {
-            type: ModelType.GRADIENT_BOOSTING,
-            predict: (features: number[]) => ({ score: 0.5, confidence: 0.7 })
-        });
-        
-        this.models.set('anomaly_detection', {
-            type: ModelType.ISOLATION_FOREST,
-            predict: (features: number[]) => ({ score: 0.5 })
-        });
-        
-        this.models.set('pattern_forecast', {
-            type: ModelType.LSTM,
-            predict: (sequence: number[]) => sequence[sequence.length - 1] * 1.1
-        });
-        
-        // Set metadata
-        for (const [name, model] of this.models) {
+        const heuristicPredictors = ['error_prediction', 'anomaly_detection', 'pattern_forecast'];
+
+        for (const name of heuristicPredictors) {
             this.modelMetadata.set(name, {
                 modelId: uuidv4(),
-                type: model.type,
+                name,
+                type: ModelType.HEURISTIC,
                 version: '1.0.0',
-                trainedAt: Date.now(),
-                accuracy: 0.75,
+                trainedAt: null,
+                accuracy: null, // heuristics have no measured validation accuracy
                 features: [],
                 hyperparameters: {},
-                trainingDataSize: 1000,
-                validationMetrics: { accuracy: 0.75, precision: 0.8, recall: 0.7 }
+                trainingDataSize: 0,
+                validationMetrics: null
             });
         }
     }
@@ -1792,9 +1807,14 @@ export class PredictiveAnalyticsService extends EventEmitter {
                 // Update internal metadata with real training metrics
                 const modelMeta = this.modelMetadata.get('error_prediction');
                 if (modelMeta) {
+                    // Backed by a trained classifier now, not the heuristic.
+                    modelMeta.type = ModelType.NEURAL_NETWORK;
                     modelMeta.trainedAt = Date.now();
                     modelMeta.trainingDataSize = features.length;
-                    modelMeta.accuracy = metrics.accuracy ?? metrics.valAccuracy ?? 0.75;
+                    // If training reported no accuracy, we do not know the accuracy. Say so.
+                    // This previously fell back to 0.75 — an invented figure indistinguishable
+                    // from a measured one.
+                    modelMeta.accuracy = metrics.accuracy ?? metrics.valAccuracy ?? null;
                     modelMeta.validationMetrics = {
                         accuracy: metrics.accuracy ?? 0,
                         val_accuracy: metrics.valAccuracy ?? 0,
@@ -1916,6 +1936,9 @@ export class PredictiveAnalyticsService extends EventEmitter {
                 // Update internal metadata with real training metrics
                 const modelMeta = this.modelMetadata.get('anomaly_detection');
                 if (modelMeta) {
+                    // A real autoencoder is now backing this predictor, so it stops being a
+                    // heuristic and says so.
+                    modelMeta.type = ModelType.NEURAL_NETWORK;
                     modelMeta.trainedAt = Date.now();
                     modelMeta.trainingDataSize = features.length;
                     // For autoencoders, accuracy is not directly applicable —

package/src/services/QValueManager.ts

@@ -169,6 +169,16 @@ export class QValueManager {
         return result;
     }
 
+    /**
+     * Whether a Q-value for this memory is already in the cache.
+     *
+     * Used by MemoryService.hydrateQValues so a retrieval only reads persistence for
+     * memories this process has not scored yet.
+     */
+    public isCached(memoryId: string): boolean {
+        return this.qValueCache.has(memoryId);
+    }
+
     /**
      * Set Q-value in cache (typically called when loading from persistence)
      */

package/src/services/RewardSignalProcessor.ts

@@ -91,6 +91,15 @@ export class RewardSignalProcessor {
     // Memory usage tracking (task ID -> memories used)
     private taskMemoryUsage: Map<string, MemoryUsageRecord[]> = new Map();
 
+    /**
+     * Memories retrieved by an agent that are not yet attributed to a completed task,
+     * keyed by `${agentId}:${channelId}`. Drained on task completion.
+     */
+    private agentMemoryUsage: Map<string, MemoryUsageRecord[]> = new Map();
+
+    /** Cap on buffered memories per agent+channel, so the buffer cannot grow unbounded. */
+    private static readonly MAX_BUFFERED_MEMORIES_PER_AGENT = 200;
+
     // Event listener cleanup functions
     private eventCleanupFns: (() => void)[] = [];
 
@@ -157,6 +166,15 @@ export class RewardSignalProcessor {
             EventBus.server.on(Events.Task.COMPLETED, taskCompletedHandler);
             this.eventCleanupFns.push(() => EventBus.server.off(Events.Task.COMPLETED, taskCompletedHandler));
 
+            // A failed task is the strongest signal MULS has that the memories it surfaced
+            // were unhelpful, and it was being thrown away: nothing listened for
+            // Events.Task.FAILED, so failure could never lower a Q-value.
+            const taskFailedHandler = (payload: any) => {
+                this.handleTaskCompleted(payload, 'failure');
+            };
+            EventBus.server.on(Events.Task.FAILED, taskFailedHandler);
+            this.eventCleanupFns.push(() => EventBus.server.off(Events.Task.FAILED, taskFailedHandler));
+
             // Listen for analytics task completed events (may have evaluation scores)
             const analyticsCompletedHandler = (payload: any) => {
                 this.handleAnalyticsTaskCompleted(payload);
@@ -183,17 +201,48 @@ export class RewardSignalProcessor {
     /**
      * Handle task completion event
      */
-    private async handleTaskCompleted(payload: any): Promise<void> {
+    private async handleTaskCompleted(payload: any, forcedStatus?: TaskOutcomeStatus): Promise<void> {
         if (!this.enabled) return;
 
         try {
             const taskId = payload.data?.taskId ?? payload.taskId;
-            const status = this.mapStatusToOutcome(payload.data?.status ?? payload.status);
             const agentId = payload.agentId ?? payload.data?.agentId;
             const channelId = payload.channelId ?? payload.data?.channelId;
 
-            // Get memories used during this task
-            const memoriesUsed = this.taskMemoryUsage.get(taskId) ?? [];
+            // Task events carry the task object in `data.task` (see TaskEventData), so the
+            // real status lives at data.task.status. Reading only data.status meant the
+            // status was always undefined, which the mapper then turned into 'partial' —
+            // giving every task, successful or not, the same small positive reward.
+            const rawStatus =
+                payload.data?.task?.status ??
+                payload.data?.status ??
+                payload.status;
+
+            const status = forcedStatus ?? this.mapStatusToOutcome(rawStatus);
+
+            // Never invent an outcome. Attributing a reward from a status we could not read
+            // would teach the system from a number nobody measured.
+            if (!status) {
+                this.logger.warn(
+                    `[RewardSignalProcessor] Task ${taskId} completed with an unrecognised status ` +
+                    `(${String(rawStatus)}); skipping reward attribution rather than guessing one.`
+                );
+                return;
+            }
+
+            // Memories used during this task: anything explicitly tracked against the task
+            // id, plus anything the agent retrieved in this channel since its last
+            // completion (retrieval has no task id to attribute to — see
+            // trackAgentMemoriesUsage).
+            const explicitlyTracked = this.taskMemoryUsage.get(taskId) ?? [];
+            const bufferedForAgent = this.drainAgentMemories(agentId, channelId);
+
+            const memoriesUsed: MemoryUsageRecord[] = [...explicitlyTracked];
+            for (const record of bufferedForAgent) {
+                if (!memoriesUsed.some(m => m.memoryId === record.memoryId)) {
+                    memoriesUsed.push(record);
+                }
+            }
 
             if (memoriesUsed.length === 0) {
                 this.logger.debug(`[RewardSignalProcessor] No memories tracked for task ${taskId}`);
@@ -259,7 +308,14 @@ export class RewardSignalProcessor {
     /**
      * Map task status string to TaskOutcomeStatus
      */
-    private mapStatusToOutcome(status: string): TaskOutcomeStatus {
+    /**
+     * Map a task status to a reward outcome, or null when the status is unrecognised.
+     *
+     * Returns null rather than defaulting to 'partial'. The old default meant an
+     * unreadable status still earned a positive reward, so memories were reinforced by
+     * tasks whose outcome was never actually known.
+     */
+    private mapStatusToOutcome(status: string): TaskOutcomeStatus | null {
         switch (status?.toLowerCase()) {
             case 'completed':
             case 'success':
@@ -276,7 +332,7 @@ export class RewardSignalProcessor {
             case 'timed_out':
                 return 'timeout';
             default:
-                return 'partial'; // Default to partial for unknown statuses
+                return null; // Unknown status — the caller must skip attribution, not guess.
         }
     }
 
@@ -494,6 +550,66 @@ export class RewardSignalProcessor {
         }
     }
 
+    /**
+     * Track memories retrieved by an agent, without needing a task id.
+     *
+     * Retrieval happens inside MCP tool handlers, and the tool context carries only
+     * agentId/channelId — never the task the agent is working on. Rather than plumb a
+     * task id through the whole MCP execution path, retrieval records what it returned
+     * against the agent+channel, and handleTaskCompleted drains that buffer when the
+     * agent's task finishes. A task is executed by one agent in one channel, so the
+     * memories buffered for that pair are exactly the ones the task used.
+     *
+     * This is the call that was missing: nothing in production ever recorded which
+     * memories were used, so every task completed with an empty usage list and no
+     * reward was ever attributed.
+     */
+    public trackAgentMemoriesUsage(
+        agentId: string,
+        channelId: string,
+        memoryIds: string[],
+        phase: OrparPhase,
+        usageType?: MemoryUsageRecord['usageType']
+    ): void {
+        if (!this.enabled || !this.config.trackMemoryUsage) return;
+        if (!agentId || !channelId || memoryIds.length === 0) return;
+
+        const key = `${agentId}:${channelId}`;
+        let records = this.agentMemoryUsage.get(key);
+        if (!records) {
+            records = [];
+            this.agentMemoryUsage.set(key, records);
+        }
+
+        for (const memoryId of memoryIds) {
+            if (!records.some(r => r.memoryId === memoryId)) {
+                records.push({ memoryId, phase, retrievedAt: new Date(), usageType });
+            }
+        }
+
+        // Bound the buffer. An agent that retrieves memories without ever completing a
+        // task would otherwise grow this map without limit.
+        if (records.length > RewardSignalProcessor.MAX_BUFFERED_MEMORIES_PER_AGENT) {
+            records.splice(0, records.length - RewardSignalProcessor.MAX_BUFFERED_MEMORIES_PER_AGENT);
+        }
+
+        this.logger.debug(
+            `[RewardSignalProcessor] Buffered ${memoryIds.length} memories for ${key} (phase=${phase})`
+        );
+    }
+
+    /**
+     * Take and clear the memories buffered for an agent in a channel.
+     */
+    private drainAgentMemories(agentId?: string, channelId?: string): MemoryUsageRecord[] {
+        if (!agentId || !channelId) return [];
+
+        const key = `${agentId}:${channelId}`;
+        const records = this.agentMemoryUsage.get(key) ?? [];
+        this.agentMemoryUsage.delete(key);
+        return records;
+    }
+
     /**
      * Track multiple memories for a task
      */
@@ -605,16 +721,29 @@ export class RewardSignalProcessor {
     }
 
     /**
-     * Get tracking statistics
+     * Get tracking statistics.
+     *
+     * `bufferedMemories` counts memories retrieved by agents that are not yet attributed
+     * to a completed task (see trackAgentMemoriesUsage).
      */
-    public getTrackingStats(): { activeTasks: number; totalMemoriesTracked: number } {
+    public getTrackingStats(): {
+        activeTasks: number;
+        totalMemoriesTracked: number;
+        bufferedMemories: number;
+    } {
         let totalMemories = 0;
         for (const [, records] of this.taskMemoryUsage) {
             totalMemories += records.length;
         }
+
+        let bufferedMemories = 0;
+        for (const [, records] of this.agentMemoryUsage) {
+            bufferedMemories += records.length;
+        }
         return {
             activeTasks: this.taskMemoryUsage.size,
-            totalMemoriesTracked: totalMemories
+            totalMemoriesTracked: totalMemories,
+            bufferedMemories
         };
     }
 

package/src/services/SharedStateService.ts

@@ -51,16 +51,45 @@ export class SharedStateService {
     private static instance: SharedStateService;
     private stateStore = new Map<string, SharedStateEntry>();
     private channelStates = new Map<string, Set<string>>(); // channelId -> Set of stateIds
-    
+
+    /** How long an untouched state entry is kept before cleanup (24 hours). */
+    private static readonly STATE_TTL_MS = 24 * 60 * 60 * 1000;
+
+    /** How often the cleanup sweep runs (1 hour). */
+    private static readonly CLEANUP_INTERVAL_MS = 60 * 60 * 1000;
+
+    private cleanupInterval: NodeJS.Timeout | null = null;
+
     private constructor() {
+        // This is a process-lifetime singleton holding an unbounded Map, so the
+        // sweep has to be driven by something. cleanupOldStates() existed but had
+        // no callers anywhere, so stateStore/channelStates simply grew forever.
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupOldStates();
+        }, SharedStateService.CLEANUP_INTERVAL_MS);
+        // Background sweep — must not keep the event loop alive on its own.
+        this.cleanupInterval.unref();
+
+        // Do not hold the event loop open on account of a garbage-collection timer.
+        this.cleanupInterval.unref?.();
     }
-    
+
     public static getInstance(): SharedStateService {
         if (!SharedStateService.instance) {
             SharedStateService.instance = new SharedStateService();
         }
         return SharedStateService.instance;
     }
+
+    /**
+     * Stop the cleanup timer. For tests and shutdown.
+     */
+    public stopCleanup(): void {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
     
     /**
      * Store collaborative state that can be referenced by ID
@@ -178,27 +207,46 @@ export class SharedStateService {
     }
     
     /**
-     * Clean up old states to prevent memory leaks
+     * Drop states that have not been touched within the TTL.
+     *
+     * Runs on a timer from the constructor; also callable directly.
+     *
+     * @param maxAgeMs Age past which a state is dropped (default: 24 hours)
+     * @returns The number of states removed
      */
-    public cleanupOldStates(maxAgeMs: number = 24 * 60 * 60 * 1000): void { // Default 24 hours
+    public cleanupOldStates(maxAgeMs: number = SharedStateService.STATE_TTL_MS): number {
         const now = Date.now();
         const toDelete: string[] = [];
-        
+
         for (const [stateId, state] of this.stateStore.entries()) {
             const age = now - (state.lastUpdatedAt || state.createdAt);
             if (age > maxAgeMs) {
                 toDelete.push(stateId);
             }
         }
-        
+
         for (const stateId of toDelete) {
             const state = this.stateStore.get(stateId);
             if (state) {
                 this.stateStore.delete(stateId);
-                this.channelStates.get(state.channelId)?.delete(stateId);
+
+                const channelStateIds = this.channelStates.get(state.channelId);
+                if (channelStateIds) {
+                    channelStateIds.delete(stateId);
+                    // Drop the channel entry too, or channelStates grows forever
+                    // with empty Sets for channels that are long gone.
+                    if (channelStateIds.size === 0) {
+                        this.channelStates.delete(state.channelId);
+                    }
+                }
             }
         }
-        
+
+        if (toDelete.length > 0) {
+            logger.debug(`Removed ${toDelete.length} shared state entries older than ${maxAgeMs}ms`);
+        }
+
+        return toDelete.length;
     }
     
     /**