@mxf-dev/core 1.0.0

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

@@ -0,0 +1,254 @@
+/**
+ * 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/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * Memory Utility Learning System (MULS) Events
+ *
+ * Events emitted by the MULS components for analytics, monitoring, and debugging.
+ * These events track Q-value updates, utility-based retrieval, and reward attribution.
+ *
+ * Feature flag: MEMORY_UTILITY_LEARNING_ENABLED
+ */
+
+import type { MemoryQValueUpdatedEventData, MemoryQValueBatchUpdatedEventData, MemoryRewardAttributedEventData } from '../../schemas/EventPayloadSchema.js';
+import { OrparPhase, TaskOutcomeStatus } from '../../types/MemoryUtilityTypes.js';
+
+/**
+ * MULS event names
+ */
+export const MemoryUtilityEvents = {
+    /** Emitted when a single Q-value is updated */
+    QVALUE_UPDATED: 'memory:qvalue_updated',
+
+    /** Emitted when multiple Q-values are updated in a batch */
+    QVALUE_BATCH_UPDATED: 'memory:qvalue_batch_updated',
+
+    /** Emitted when utility-based retrieval is completed */
+    UTILITY_RETRIEVAL_COMPLETED: 'memory:utility_retrieval_completed',
+
+    /** Emitted when rewards are attributed to memories after task completion */
+    REWARD_ATTRIBUTED: 'memory:reward_attributed',
+
+    /** Emitted when memory usage is tracked for a task */
+    MEMORY_TRACKED: 'memory:tracked',
+
+    /** Emitted when MULS configuration changes */
+    CONFIG_UPDATED: 'memory:utility_config_updated'
+} as const;
+
+/**
+ * Type for MULS event names
+ */
+export type MemoryUtilityEventName = typeof MemoryUtilityEvents[keyof typeof MemoryUtilityEvents];
+
+/**
+ * Base payload for all MULS events
+ */
+export interface MemoryUtilityBasePayload {
+    /** Event type */
+    eventType: MemoryUtilityEventName;
+    /** Timestamp of the event */
+    timestamp: number;
+}
+
+/**
+ * Payload for QVALUE_UPDATED event
+ */
+export interface QValueUpdatedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.QVALUE_UPDATED;
+    data: {
+        /** The memory ID that was updated */
+        memoryId: string;
+        /** Q-value before the update */
+        oldValue: number;
+        /** Q-value after the update */
+        newValue: number;
+        /** Reward signal that triggered the update */
+        reward: number;
+        /** Change in Q-value (newValue - oldValue) */
+        delta: number;
+        /** Optional task ID that triggered the update */
+        taskId?: string;
+        /** Optional agent ID */
+        agentId?: string;
+        /** Optional channel ID */
+        channelId?: string;
+        /** Optional ORPAR phase */
+        phase?: OrparPhase;
+    };
+}
+
+/**
+ * Payload for QVALUE_BATCH_UPDATED event
+ */
+export interface QValueBatchUpdatedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.QVALUE_BATCH_UPDATED;
+    data: {
+        /** Total number of updates attempted */
+        totalUpdates: number;
+        /** Number of successful updates */
+        updated: number;
+        /** Number of failed updates */
+        failed: number;
+        /** Optional task ID that triggered the batch update */
+        taskId?: string;
+        /** Optional summary of errors */
+        errors?: Array<{ memoryId: string; error: string }>;
+    };
+}
+
+/**
+ * Payload for UTILITY_RETRIEVAL_COMPLETED event
+ */
+export interface UtilityRetrievalCompletedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.UTILITY_RETRIEVAL_COMPLETED;
+    data: {
+        /** Query used for retrieval */
+        query: string;
+        /** ORPAR phase (if specified) */
+        phase?: OrparPhase;
+        /** Lambda value used for scoring */
+        lambda: number;
+        /** Number of candidates in Phase A */
+        totalCandidates: number;
+        /** Number of results returned */
+        resultsReturned: number;
+        /** Time for semantic search (ms) */
+        semanticSearchTimeMs: number;
+        /** Time for utility scoring (ms) */
+        utilityScoringTimeMs: number;
+        /** Total retrieval time (ms) */
+        totalTimeMs: number;
+        /** IDs of retrieved memories */
+        memoryIds: string[];
+        /** Optional agent ID */
+        agentId?: string;
+        /** Optional channel ID */
+        channelId?: string;
+    };
+}
+
+/**
+ * Payload for REWARD_ATTRIBUTED event
+ */
+export interface RewardAttributedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.REWARD_ATTRIBUTED;
+    data: {
+        /** Task ID (if task-level attribution) */
+        taskId?: string;
+        /** Task outcome status */
+        status?: TaskOutcomeStatus;
+        /** Reward value attributed */
+        reward: number;
+        /** Number of memories that received the reward */
+        memoriesUpdated: number;
+        /** Number of memories that failed to update */
+        memoriesFailed: number;
+        /** IDs of memories that received the reward */
+        memoryIds: string[];
+        /** Whether this was a manual injection */
+        isManual?: boolean;
+        /** Reason for manual injection */
+        reason?: string;
+        /** New Q-value (for single memory manual injection) */
+        newQValue?: number;
+        /** Single memory ID (for manual injection) */
+        memoryId?: string;
+    };
+}
+
+/**
+ * Payload for MEMORY_TRACKED event
+ */
+export interface MemoryTrackedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.MEMORY_TRACKED;
+    data: {
+        /** Task ID the memory is tracked for */
+        taskId: string;
+        /** Memory ID being tracked */
+        memoryId: string;
+        /** ORPAR phase when tracked */
+        phase: OrparPhase;
+        /** Usage type */
+        usageType?: 'context' | 'reasoning' | 'action-guidance' | 'pattern-match';
+        /** Timestamp of tracking */
+        trackedAt: Date;
+    };
+}
+
+/**
+ * Payload for CONFIG_UPDATED event
+ */
+export interface ConfigUpdatedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.CONFIG_UPDATED;
+    data: {
+        /** Whether MULS is now enabled */
+        enabled: boolean;
+        /** New global lambda value */
+        lambda?: number;
+        /** New learning rate */
+        learningRate?: number;
+        /** Updated phase lambdas */
+        phaseLambdas?: Record<OrparPhase, number>;
+        /** Source of the update */
+        source: 'api' | 'config' | 'env' | 'tool';
+    };
+}
+
+/**
+ * Union type for all MULS payloads
+ */
+export type MemoryUtilityPayload =
+    | QValueUpdatedPayload
+    | QValueBatchUpdatedPayload
+    | UtilityRetrievalCompletedPayload
+    | RewardAttributedPayload
+    | MemoryTrackedPayload
+    | ConfigUpdatedPayload;
+
+/**
+ * Payload types for MULS events (indexed by event name)
+ */
+/**
+ * Data carried by UTILITY_RETRIEVAL_COMPLETED (envelope data — the
+ * BaseEventPayload wrapper carries eventType/agentId/channelId/timestamp).
+ */
+export interface UtilityRetrievalCompletedEventData {
+    query: string;
+    phase?: string;
+    lambda: number;
+    totalCandidates: number;
+    resultsReturned: number;
+    semanticSearchTimeMs: number;
+    utilityScoringTimeMs: number;
+    totalTimeMs: number;
+    memoryIds: string[];
+    agentId?: string;
+    channelId?: string;
+}
+
+export interface MemoryUtilityPayloads {
+    'memory:qvalue_updated': MemoryQValueUpdatedEventData;
+    'memory:qvalue_batch_updated': MemoryQValueBatchUpdatedEventData;
+    'memory:utility_retrieval_completed': UtilityRetrievalCompletedEventData;
+    'memory:reward_attributed': MemoryRewardAttributedEventData;
+    'memory:tracked': MemoryTrackedPayload;
+    'memory:utility_config_updated': ConfigUpdatedPayload;
+}

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

@@ -0,0 +1,107 @@
+/**
+ * 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/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+import { 
+    ChannelMessage, 
+    AgentMessage 
+} from '../../schemas/MessageSchemas.js';
+
+import type {
+    MessageEventData,
+    MessagePersistFailedPayload as MessagePersistFailedEventData,
+    MessageSendFailedPayload as MessageSendFailedEventData,
+    AgentMessageEventPayload,
+    ChannelMessageEventPayload,
+    BaseEventPayload
+} from '../../schemas/EventPayloadSchema.js';
+
+/**
+ * Type definition for agent message events imported from EventPayloadSchema
+ * @deprecated BACKWARD-COMPATIBILITY: Import from src/shared/schemas/EventPayloadSchema.ts instead
+ * This type alias is maintained for backward compatibility and will be removed in a future release
+ */
+export type AgentMessageEvent = AgentMessage;
+
+/**
+ * Type definition for channel message events imported from EventPayloadSchema
+ * @deprecated BACKWARD-COMPATIBILITY: Import from src/shared/schemas/EventPayloadSchema.ts instead
+ * This type alias is maintained for backward compatibility and will be removed in a future release
+ */
+export type ChannelMessageEvent = ChannelMessage;
+
+/**
+ * Events for agent messaging
+ */
+export const MessageEvents = {
+    // Agent-to-agent direct messaging
+    AGENT_MESSAGE: 'message:agent', // Client event to send a direct message from one agent to another
+    AGENT_MESSAGE_DELIVERED: 'message:agent:delivered', // Server event confirming the agent message was successfully delivered to the recipient
+    
+    // Channel messaging
+    CHANNEL_MESSAGE: 'message:channel', // Client event to send a message to an entire channel
+    CHANNEL_MESSAGE_DELIVERED: 'message:channel:delivered', // Server event confirming the channel message was successfully delivered
+    
+    // Message error handling
+    MESSAGE_ERROR: 'message:error', // Error event for message handling failures
+    
+    // System messages
+    SYSTEM_MESSAGE: 'message:system', // Message from the system to agents
+    SYSTEM_MESSAGE_DELIVERED: 'message:system:delivered', // Server event confirming the system message was successfully delivered
+    
+    // LLM-specific messages
+    LLM_MESSAGE: 'llmMessage', // Message from an LLM agent
+
+    // Message persistence events
+    PERSIST_CHANNEL_MESSAGE_REQUEST: 'message:persist:request', // Request to persist a channel message
+    MESSAGE_PERSIST_FAILED: 'message:persist:failed', // Event indicating message persistence failed
+    MESSAGE_SEND_FAILED: 'message:send:failed', // Event indicating message sending failed (e.g., to a channel)
+};
+
+// Using the types imported from EventPayloadSchema.ts
+// MessagePersistFailedEventData and MessageSendFailedEventData are aliases for
+// MessagePersistFailedPayload and MessageSendFailedPayload from EventPayloadSchema.ts
+
+/**
+ * @deprecated BACKWARD-COMPATIBILITY: Import from src/shared/schemas/EventPayloadSchema.ts instead
+ * These type aliases are maintained for backward compatibility and will be removed in a future release
+ * Used by: src/server/socket/services/ChannelService.ts
+ */
+export type MessagePersistFailedPayload = MessagePersistFailedEventData;
+export type MessageSendFailedPayload = MessageSendFailedEventData;
+
+/**
+ * Payload types for Message events
+ */
+export interface MessagePayloads {
+    'message:agent': AgentMessageEvent;
+    'message:agent:delivered': AgentMessageEvent;
+    'message:channel': ChannelMessageEvent;
+    'message:channel:delivered': ChannelMessageEvent;
+    'message:error': { channelId?: string, messageId?: string, error: string, timestamp: number, fromAgentId?: string };
+    'message:system': { content: string, timestamp: number };
+    'message:system:delivered': { content: string, timestamp: number };
+    'message': any;
+    'llmMessage': any;
+
+    // Payloads for message persistence events
+    'message:persist:request': MessageEventData;
+    'message:persist:failed': MessagePersistFailedEventData;
+    'message:send:failed': MessageSendFailedEventData;
+}

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

@@ -0,0 +1,138 @@
+/**
+ * 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/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * MXP 2.0 Event Definitions
+ * 
+ * Defines all events for the Model Exchange Protocol 2.0 optimization system.
+ * Integrates with existing EventBus architecture and follows MXF event patterns.
+ */
+
+import { z } from 'zod';
+
+/**
+ * MXP 2.0 Event Names
+ */
+export const MxpEvents = {
+    // Token optimization events
+    TOKEN_OPTIMIZATION_START: 'mxp:token:optimization:start',
+    TOKEN_OPTIMIZATION_COMPLETE: 'mxp:token:optimization:complete',
+    CONTEXT_COMPRESSED: 'mxp:token:context:compressed',
+    PROMPT_OPTIMIZED: 'mxp:token:prompt:optimized',
+    TEMPLATE_GENERATED: 'mxp:token:template:generated',
+    TEMPLATE_APPLIED: 'mxp:token:template:applied',
+    
+    // Bandwidth optimization events
+    BANDWIDTH_OPTIMIZATION_START: 'mxp:bandwidth:optimization:start',
+    BANDWIDTH_OPTIMIZATION_COMPLETE: 'mxp:bandwidth:optimization:complete',
+    MESSAGE_COMPRESSED: 'mxp:bandwidth:message:compressed',
+    BATCH_CREATED: 'mxp:bandwidth:batch:created',
+    BINARY_ENCODED: 'mxp:bandwidth:binary:encoded',
+    
+    // Security events
+    SECURITY_LEVEL_CHANGED: 'mxp:security:level:changed',
+    KEY_ROTATED: 'mxp:security:key:rotated',
+    ENCRYPTION_ENHANCED: 'mxp:security:encryption:enhanced',
+    
+    // Analytics events
+    OPTIMIZATION_METRICS: 'mxp:analytics:metrics',
+    PERFORMANCE_REPORT: 'mxp:analytics:performance',
+    COST_SAVINGS_CALCULATED: 'mxp:analytics:cost:savings'
+} as const;
+
+/**
+ * MXP Token Optimization Event Data
+ */
+export interface MxpTokenOptimizationEventData {
+    originalTokens: number;
+    optimizedTokens: number;
+    compressionRatio: number;
+    strategy: 'context_compression' | 'conversation_summarization' | 'prompt_optimization' | 'template_matching' | 'entity_deduplication';
+    operationId: string;
+    timestamp: number;
+    toolsOptimized?: string[];
+    contextWindowReduction?: number;
+}
+
+/**
+ * MXP Bandwidth Optimization Event Data
+ */
+export interface MxpBandwidthOptimizationEventData {
+    originalSize: number;
+    compressedSize: number;
+    compressionRatio: number;
+    encoding: 'json' | 'msgpack' | 'msgpack-compressed' | 'binary';
+    operationId: string;
+    timestamp: number;
+    messagesAggregated?: number;
+    batchingApplied?: boolean;
+}
+
+/**
+ * MXP Security Event Data
+ */
+export interface MxpSecurityEventData {
+    previousLevel?: 'standard' | 'enhanced' | 'regulated' | 'classified';
+    newLevel: 'standard' | 'enhanced' | 'regulated' | 'classified';
+    keyId?: string;
+    rotationReason?: 'scheduled' | 'security' | 'upgrade' | 'manual';
+    timestamp: number;
+}
+
+/**
+ * MXP Analytics Event Data
+ */
+export interface MxpAnalyticsEventData {
+    metricType: 'token_savings' | 'bandwidth_savings' | 'cost_reduction' | 'performance_improvement';
+    value: number;
+    unit: 'tokens' | 'bytes' | 'percentage' | 'milliseconds' | 'dollars';
+    period: 'real_time' | 'hourly' | 'daily' | 'weekly' | 'monthly';
+    timestamp: number;
+    agentCount?: number;
+    channelCount?: number;
+}
+
+/**
+ * MXP Event Payloads Type Map
+ */
+export interface MxpPayloads {
+    [MxpEvents.TOKEN_OPTIMIZATION_START]: MxpTokenOptimizationEventData;
+    [MxpEvents.TOKEN_OPTIMIZATION_COMPLETE]: MxpTokenOptimizationEventData;
+    [MxpEvents.CONTEXT_COMPRESSED]: MxpTokenOptimizationEventData;
+    [MxpEvents.PROMPT_OPTIMIZED]: MxpTokenOptimizationEventData;
+    [MxpEvents.TEMPLATE_GENERATED]: MxpTokenOptimizationEventData;
+    [MxpEvents.TEMPLATE_APPLIED]: MxpTokenOptimizationEventData;
+    
+    [MxpEvents.BANDWIDTH_OPTIMIZATION_START]: MxpBandwidthOptimizationEventData;
+    [MxpEvents.BANDWIDTH_OPTIMIZATION_COMPLETE]: MxpBandwidthOptimizationEventData;
+    [MxpEvents.MESSAGE_COMPRESSED]: MxpBandwidthOptimizationEventData;
+    [MxpEvents.BATCH_CREATED]: MxpBandwidthOptimizationEventData;
+    [MxpEvents.BINARY_ENCODED]: MxpBandwidthOptimizationEventData;
+    
+    [MxpEvents.SECURITY_LEVEL_CHANGED]: MxpSecurityEventData;
+    [MxpEvents.KEY_ROTATED]: MxpSecurityEventData;
+    [MxpEvents.ENCRYPTION_ENHANCED]: MxpSecurityEventData;
+    
+    [MxpEvents.OPTIMIZATION_METRICS]: MxpAnalyticsEventData;
+    [MxpEvents.PERFORMANCE_REPORT]: MxpAnalyticsEventData;
+    [MxpEvents.COST_SAVINGS_CALCULATED]: MxpAnalyticsEventData;
+}
+
+export type MxpEventName = keyof MxpPayloads;