@mxf-dev/core 1.0.0

package/src/models/channelKey.ts

@@ -0,0 +1,129 @@
+/**
+ * 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/
+ */
+
+/**
+ * Channel Authentication Key Model
+ * 
+ * Defines the data schema for channel authentication keys, which are used
+ * to securely connect agents to specific channels. Keys are created by users
+ * and distributed to agents that need access to the channel.
+ */
+
+import mongoose, { Schema, Document } from 'mongoose';
+import crypto from 'crypto';
+
+/**
+ * Interface representing a Channel Authentication Key document in MongoDB
+ */
+export interface IChannelKey extends Document {
+    // The unique key identifier
+    keyId: string;
+    
+    // The actual secret key used for authentication
+    secretKey: string;
+    
+    // Reference to the channel this key provides access to
+    channelId: string;
+    
+    // Optional name for the key (for user reference)
+    name?: string;
+    
+    // Reference to the user who created this key
+    createdBy: Schema.Types.ObjectId;
+    
+    // Whether the key is currently active
+    isActive: boolean;
+    
+    // Optional expiration date
+    expiresAt?: Date;
+    
+    // Timestamps
+    createdAt: Date;
+    updatedAt: Date;
+    lastUsed?: Date;
+}
+
+/**
+ * MongoDB schema for ChannelKey
+ */
+const ChannelKeySchema: Schema = new Schema({
+    keyId: {
+        type: String,
+        required: true,
+        unique: true,
+    },
+    secretKey: {
+        type: String,
+        required: true,
+    },
+    channelId: {
+        type: String,
+        required: true,
+        index: true,
+        ref: 'ChannelRegistration',
+    },
+    name: {
+        type: String,
+        required: false,
+    },
+    createdBy: {
+        type: Schema.Types.ObjectId,
+        ref: 'User',
+        required: true,
+    },
+    isActive: {
+        type: Boolean,
+        default: true,
+    },
+    expiresAt: {
+        type: Date,
+        required: false,
+    },
+    createdAt: {
+        type: Date,
+        default: Date.now,
+    },
+    updatedAt: {
+        type: Date,
+        default: Date.now,
+    },
+    lastUsed: {
+        type: Date,
+        required: false,
+    },
+});
+
+// Index for efficient queries
+ChannelKeySchema.index({ channelId: 1, isActive: 1 });
+
+/**
+ * Generate a new random channel key
+ * @returns Object containing keyId and secretKey
+ */
+export const generateChannelKey = (): { keyId: string; secretKey: string } => {
+    return {
+        keyId: 'key_' + crypto.randomBytes(12).toString('hex'),
+        secretKey: crypto.randomBytes(32).toString('base64'),
+    };
+};
+
+// Create and export the ChannelKey model
+const ChannelKey = mongoose.model<IChannelKey>('ChannelKey', ChannelKeySchema);
+export default ChannelKey;

package/src/models/codeExecution.ts

@@ -0,0 +1,272 @@
+/**
+ * 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/
+ */
+
+/**
+ * Code Execution Model
+ *
+ * Represents a record of code execution in the sandbox, including metrics,
+ * output, and resource usage. Includes TTL index for automatic cleanup.
+ */
+
+import mongoose, { Document, Schema } from 'mongoose';
+
+/**
+ * Code execution interface
+ */
+export interface ICodeExecution extends Document {
+    agentId: string;
+    channelId: string;
+    requestId: string;
+
+    // Code information
+    language: 'javascript' | 'typescript';
+    codeHash: string;
+    codeLength: number;
+    codeSnippet?: string; // Optional: store first 500 chars for debugging
+
+    // Execution results
+    success: boolean;
+    output: any;
+    logs: string[];
+    error?: string;
+
+    // Performance metrics
+    executionTime: number; // milliseconds
+    timeout: number; // configured timeout
+
+    // Resource usage
+    memoryUsage: number; // MB
+    timeoutOccurred: boolean;
+
+    // Context data
+    contextData?: Record<string, any>;
+
+    // Timestamps
+    executedAt: Date;
+    createdAt: Date;
+}
+
+/**
+ * Code execution schema
+ */
+const CodeExecutionSchema = new Schema<ICodeExecution>({
+    agentId: {
+        type: String,
+        required: true,
+        index: true
+    },
+    channelId: {
+        type: String,
+        required: true,
+        index: true
+    },
+    requestId: {
+        type: String,
+        required: true,
+        unique: true
+    },
+
+    // Code information
+    language: {
+        type: String,
+        required: true,
+        enum: ['javascript', 'typescript']
+    },
+    codeHash: {
+        type: String,
+        required: true,
+        index: true
+    },
+    codeLength: {
+        type: Number,
+        required: true
+    },
+    codeSnippet: {
+        type: String
+    },
+
+    // Execution results
+    success: {
+        type: Boolean,
+        required: true,
+        index: true
+    },
+    output: {
+        type: Schema.Types.Mixed
+    },
+    logs: {
+        type: [String],
+        default: []
+    },
+    error: {
+        type: String
+    },
+
+    // Performance metrics
+    executionTime: {
+        type: Number,
+        required: true
+    },
+    timeout: {
+        type: Number,
+        required: true
+    },
+
+    // Resource usage
+    memoryUsage: {
+        type: Number,
+        required: true
+    },
+    timeoutOccurred: {
+        type: Boolean,
+        default: false
+    },
+
+    // Context data
+    contextData: {
+        type: Schema.Types.Mixed
+    },
+
+    // Timestamps
+    executedAt: {
+        type: Date,
+        required: true,
+        default: Date.now
+    },
+    createdAt: {
+        type: Date,
+        default: Date.now
+    }
+});
+
+// Performance indexes
+CodeExecutionSchema.index({ agentId: 1, executedAt: -1 });
+CodeExecutionSchema.index({ channelId: 1, executedAt: -1 });
+CodeExecutionSchema.index({ codeHash: 1, success: 1 });
+CodeExecutionSchema.index({ language: 1, success: 1 });
+
+// TTL index: auto-delete records after 30 days
+CodeExecutionSchema.index({ executedAt: 1 }, { expireAfterSeconds: 2592000 });
+
+// Compound indexes for analytics queries
+CodeExecutionSchema.index({ agentId: 1, success: 1, executedAt: -1 });
+CodeExecutionSchema.index({ channelId: 1, language: 1, executedAt: -1 });
+
+/**
+ * Static method to get execution statistics for an agent
+ */
+CodeExecutionSchema.statics.getAgentStats = async function(
+    agentId: string,
+    since?: Date
+): Promise<{
+    totalExecutions: number;
+    successfulExecutions: number;
+    failedExecutions: number;
+    averageExecutionTime: number;
+    timeoutCount: number;
+    languageBreakdown: Record<string, number>;
+}> {
+    const matchStage: any = { agentId };
+    if (since) {
+        matchStage.executedAt = { $gte: since };
+    }
+
+    const stats = await this.aggregate([
+        { $match: matchStage },
+        {
+            $group: {
+                _id: null,
+                totalExecutions: { $sum: 1 },
+                successfulExecutions: {
+                    $sum: { $cond: ['$success', 1, 0] }
+                },
+                failedExecutions: {
+                    $sum: { $cond: ['$success', 0, 1] }
+                },
+                averageExecutionTime: { $avg: '$executionTime' },
+                timeoutCount: {
+                    $sum: { $cond: ['$timeoutOccurred', 1, 0] }
+                }
+            }
+        }
+    ]);
+
+    const languageStats = await this.aggregate([
+        { $match: matchStage },
+        {
+            $group: {
+                _id: '$language',
+                count: { $sum: 1 }
+            }
+        }
+    ]);
+
+    const languageBreakdown: Record<string, number> = {};
+    languageStats.forEach((stat: any) => {
+        languageBreakdown[stat._id] = stat.count;
+    });
+
+    return {
+        totalExecutions: stats[0]?.totalExecutions || 0,
+        successfulExecutions: stats[0]?.successfulExecutions || 0,
+        failedExecutions: stats[0]?.failedExecutions || 0,
+        averageExecutionTime: stats[0]?.averageExecutionTime || 0,
+        timeoutCount: stats[0]?.timeoutCount || 0,
+        languageBreakdown
+    };
+};
+
+/**
+ * Static method to find similar executions by code hash
+ */
+CodeExecutionSchema.statics.findByCodeHash = function(
+    codeHash: string,
+    limit: number = 10
+) {
+    return this.find({ codeHash })
+        .sort({ executedAt: -1 })
+        .limit(limit)
+        .select('-output -logs') // Exclude large fields
+        .lean();
+};
+
+/**
+ * Static method to get recent failures for debugging
+ */
+CodeExecutionSchema.statics.getRecentFailures = function(
+    agentId: string,
+    limit: number = 20
+) {
+    return this.find({
+        agentId,
+        success: false
+    })
+        .sort({ executedAt: -1 })
+        .limit(limit)
+        .select('codeHash language error executionTime executedAt')
+        .lean();
+};
+
+// Create the model
+export const CodeExecution = mongoose.model<ICodeExecution>('CodeExecution', CodeExecutionSchema);
+
+// Export types for use in other modules
+export type CodeExecutionDocument = ICodeExecution;
+export type CodeExecutionLanguage = 'javascript' | 'typescript';

package/src/models/controlLoop.ts

@@ -0,0 +1,165 @@
+/**
+ * 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/
+ */
+
+/**
+ * controlLoop.ts
+ * 
+ * Shared model definitions for the Control Loop architecture.
+ * Includes interfaces and types used by both server and client components.
+ */
+
+import { AgentId } from '../types/Agent.js';
+import { Plan, PlanAction, ActionStatus, Reflection } from '../types/ControlLoopTypes.js';
+
+// Re-export consolidated types for backward compatibility
+export type { Plan, PlanAction, ActionStatus, Reflection };
+
+/**
+ * Enum for control loop state
+ */
+export enum ControlLoopStateEnum {
+    IDLE = 'idle',
+    INITIALIZING = 'initializing',
+    READY = 'ready',
+    RUNNING = 'running',
+    OBSERVING = 'observing',
+    REASONING = 'reasoning',
+    PLANNING = 'planning',
+    EXECUTING = 'executing',
+    REFLECTING = 'reflecting',
+    STOPPING = 'stopping',
+    STOPPED = 'stopped',
+    ERROR = 'error'
+}
+
+/**
+ * Interface for control loop configuration
+ */
+export interface ControlLoopConfig {
+    // Core configuration
+    loopId?: string;          // Unique ID for this control loop, generated if not provided
+    agentId: AgentId;         // ID of the agent this control loop belongs to
+    channelId?: string;       // Channel to receive observations and emit events
+    autoStart?: boolean;      // Whether to start the control loop automatically after initialization
+    
+    // Performance configuration
+    maxObservationsToProcess?: number;  // Maximum number of observations to process in one cycle
+    processingInterval?: number;        // Interval in ms between processing cycles
+    
+    // Error handling configuration
+    errorRecovery?: ErrorRecoveryConfig; // Error recovery configuration
+    
+    // Extension points
+    plugins?: any[];           // Plugins to extend control loop functionality
+    customHandlers?: Record<string, Function>; // Custom handlers for specific events
+    
+    // Operational constraints
+    timeout?: number;         // Timeout in ms for various operations
+    maxRetries?: number;      // Maximum number of retries for failing operations
+    
+    // Created timestamp
+    createdAt?: number;       // Timestamp when this config was created
+}
+
+/**
+ * Interface for error recovery configuration
+ */
+export interface ErrorRecoveryConfig {
+    maxConsecutiveErrors?: number; // Maximum consecutive errors before entering degraded mode
+    enableAutoHealing?: boolean;   // Whether to enable automatic recovery from errors
+    maxRetries?: number;           // Maximum retries for failed operations
+    retryDelay?: number;           // Delay in ms between retries
+}
+
+/**
+ * Interface for observations fed into the control loop
+ */
+export interface Observation {
+    id: string;                 // Unique ID for this observation
+    agentId: AgentId;           // ID of the agent this observation is for or from
+    source: string;             // Source of the observation (e.g., "user", "sensor", "agent")
+    content: any;               // Content of the observation
+    timestamp: number;          // When the observation was created
+    priority?: number;          // Priority of the observation (higher values = higher priority)
+    metadata?: Record<string, any>; // Additional metadata
+    processed?: boolean;        // Whether this observation has been processed
+}
+
+/**
+ * Interface for reasoning generated from observations
+ */
+export interface Reasoning {
+    id: string;                 // Unique ID for this reasoning
+    agentId: AgentId;           // ID of the agent that generated this reasoning
+    observations: string[];     // IDs of observations this reasoning is based on
+    content: any;               // Content of the reasoning
+    timestamp: number;          // When the reasoning was generated
+    confidence?: number;        // Confidence in the reasoning (0-1)
+    metadata?: Record<string, any>; // Additional metadata
+}
+
+/**
+ * Interface for a complete control loop implementation
+ */
+export interface IControlLoop {
+    /**
+     * Initialize the control loop
+     * @param config Control loop configuration
+     */
+    initialize(config: ControlLoopConfig): Promise<boolean>;
+    
+    /**
+     * Start the control loop
+     */
+    start(): Promise<boolean>;
+    
+    /**
+     * Stop the control loop
+     */
+    stop(): Promise<boolean>;
+    
+    /**
+     * Reset the control loop
+     */
+    reset(): Promise<boolean>;
+    
+    /**
+     * Get the current state of the control loop
+     */
+    getCurrentState(): Promise<ControlLoopStateEnum>;
+    
+    /**
+     * Add an observation to the control loop
+     * @param observation Observation to add
+     */
+    addObservation(observation: Observation): Promise<boolean>;
+    
+    /**
+     * Execute an action
+     * @param action Action to execute
+     */
+    executeAction(action: PlanAction): Promise<any>;
+    
+    /**
+     * Attempt to recover from an error state
+     * @param error Error that triggered recovery
+     */
+    recover(error: any): Promise<boolean>;
+}