@mxf-dev/core 1.0.0

package/src/interfaces/AgentInterfaces.ts

@@ -0,0 +1,132 @@
+/**
+ * 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/
+ */
+
+/**
+ * AgentInterfaces.ts
+ * 
+ * Defines interfaces and types for agent configuration and management
+ * in the Model Exchange Framework.
+ */
+
+/**
+ * LLM Reasoning configuration interface
+ * Supports both OpenAI/ChatGPT style (effort) and Anthropic/Claude style (max_tokens)
+ */
+export interface LlmReasoningConfig {
+    enabled?: boolean;                    // Enable reasoning with default "medium" effort
+    effort?: 'low' | 'medium' | 'high';  // OpenAI/ChatGPT style: effort level (20%, 50%, 80% of max_tokens)
+    maxTokens?: number;                   // Anthropic/Claude style: direct token allocation for reasoning
+    exclude?: boolean;                    // If true, reasoning used internally but not returned in response
+}
+
+/**
+ * Base Agent configuration interface
+ */
+export interface AgentConfig {
+    // Basic agent properties
+    agentId: string;
+    channelId: string;
+    name: string;
+    description?: string;
+    capabilities?: string[];
+    metadata?: Record<string, any>;
+    
+    // Connection details
+    host: string;
+    port: number;
+    secure: boolean;
+    
+    // API access
+    keyId: string;
+    secretKey: string;
+    apiUrl: string;
+    apiKey: string;
+    
+    // SDK domain key (internal - set by MxfSDK)
+    sdkDomainKey?: string;
+    
+    // Behavioral properties
+    autoRegister?: boolean;
+    autoReconnect?: boolean;
+    reconnectAttempts?: number;
+    reconnectDelay?: number;
+    requestTimeoutMs?: number; // Added missing property
+    useMessageAggregate?: boolean; // Enable message aggregation for high-volume agents
+    disableTaskHandling?: boolean; // Disable automatic task handling (for admin/utility agents that only register MCP servers)
+    
+    // Control loop properties
+    maxObservations?: number;
+    cycleInterval?: number;
+    maxIterations?: number;                  // Max LLM iterations per task (default: 10, increase for game scenarios)
+
+    // LLM properties
+    agentConfigPrompt: string;              // Agent's identity and role configuration prompt (renamed from systemPrompt)
+    temperature?: number;
+    maxTokens?: number;
+    maxHistory?: number;
+    maxMessageSize?: number;                // Max size in bytes for a single message (default: 100KB) - prevents MongoDB 16MB limit errors
+    defaultModel?: string;
+    llmProvider?: string;                   // e.g., 'openrouter', 'azure-openai', 'openai', 'anthropic'
+    enableTooling?: boolean;
+    reasoning?: LlmReasoningConfig;        // Optional reasoning configuration for advanced models
+    
+    // Provider-specific configuration
+    // For Azure OpenAI, use:
+    //   providerOptions: {
+    //     endpoint: 'https://your-resource.openai.azure.com/',
+    //     deployment: 'gpt-4-1-mini',
+    //     apiVersion: '2024-04-01-preview'
+    //   }
+    providerOptions?: Record<string, any>;
+    
+    // Tool access control
+    allowedTools?: string[];
+    circuitBreakerExemptTools?: string[];    // Tools exempt from circuit breaker detection (for game tools, etc.)
+    
+    // Name resolution and interpretation settings
+    commonNames?: string[];                                        // Alternative names/aliases for this agent
+    preferredResponseMode?: 'tools' | 'natural' | 'mixed';       // How agent prefers to respond
+    interpretationEnabled?: boolean;                               // Enable SystemLLM interpretation (default: true)
+    actionHistoryWindow?: number;                                  // Number of recent actions to include (default: 20)
+    
+    // Utilities
+    logger?: any;
+    
+    // MXP Protocol Configuration
+    mxpEnabled?: boolean;
+    mxpPreferredFormat?: 'auto' | 'mxp' | 'natural-language';
+    mxpForceEncryption?: boolean;
+
+    // Client-side tool execution
+    /** Enable client-side tool execution for eligible stateless tools (default: false) */
+    enableClientToolExecution?: boolean;
+    /** External MCP server IDs to spawn client-side instead of server-side */
+    clientExternalMcpServers?: string[];
+}
+
+/**
+ * Extended Agent configuration interface with additional properties used internally
+ */
+export interface InternalAgentConfig extends AgentConfig {
+    channelService?: any;
+}
+
+// For backward compatibility
+export type MxfAgentConfig = AgentConfig;

package/src/interfaces/Channel.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 Interface
+ * Defines the structure of a channel in the MXF
+ */
+export interface IChannel {
+    id: string;
+    name: string;
+    active: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, any>;
+    
+    // Channel-level access control and configuration
+    allowedTools?: string[];
+    systemLlmEnabled?: boolean;
+}

package/src/interfaces/ChannelConfig.ts

@@ -0,0 +1,59 @@
+/**
+ * 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/
+ */
+
+/**
+ * MCP server configuration for channel registration
+ */
+export interface ChannelMcpServerConfig {
+    id: string;
+    name: string;
+    command?: string;
+    args?: string[];
+    transport?: 'stdio' | 'http';
+    url?: string;
+    autoStart?: boolean;
+    environmentVariables?: Record<string, string>;
+    restartOnCrash?: boolean;
+    keepAliveMinutes?: number;
+}
+
+/**
+ * Channel configuration interface
+ */
+export interface ChannelConfig {
+    name: string;
+    description: string;
+    isPrivate: boolean;
+    requireApproval: boolean;
+    maxAgents: number;
+    allowAnonymous: boolean;
+    metadata: Record<string, any>;
+    
+    // Channel-level tool access control
+    // Empty array (default) = no restrictions, agents use their own allowedTools
+    // Non-empty array = agents can only use tools in BOTH channel's and agent's allowedTools
+    allowedTools?: string[];
+    
+    // Disable SystemLLM for this channel (for games, custom orchestration, etc.)
+    systemLlmEnabled?: boolean;
+    
+    // MCP servers to register for this channel at creation time
+    mcpServers?: ChannelMcpServerConfig[];
+}

package/src/interfaces/ChannelConnectionConfig.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 connection configuration
+ */
+export interface ChannelConnectionConfig {
+    serverUrl: string;
+    keyId?: string;
+    secretKey?: string;
+    autoReconnect?: boolean;
+    reconnectDelay?: number;
+    reconnectAttempts?: number;
+    debug?: boolean;
+    apiUrl?: string;
+    capabilities?: string[];
+    allowedTools?: string[];  // Tools the agent is allowed to use
+    sdkDomainKey?: string;  // SDK domain key for server authentication (set by MxfSDK)
+}

package/src/interfaces/ChannelInfo.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 information interface
+ */
+export interface ChannelInfo {
+    channelId: string;
+    name: string;
+    description?: string;
+    createdAt: Date;
+    active: boolean;
+    memberCount?: number;
+    metadata?: Record<string, any>;
+}
+

package/src/interfaces/ConversationMessage.ts

@@ -0,0 +1,109 @@
+/**
+ * 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/
+ */
+
+/**
+ * Context layer types - what part of the agent's context does this message represent?
+ */
+export type ContextLayer = 
+    | 'system'        // Framework rules and core instructions
+    | 'identity'      // Agent configuration and identity
+    | 'task'          // Current task description
+    | 'conversation'  // Actual agent-to-agent dialogue
+    | 'action'        // Action history and recent activities
+    | 'current'       // Current message being responded to
+    | 'tool-result';  // Tool execution results
+
+/**
+ * Message type - semantic meaning of the message
+ */
+export type MessageType = 
+    | 'framework-rules'         // MXF operating environment
+    | 'agent-config'            // Agent identity and capabilities
+    | 'task-description'        // Task assignment and requirements
+    | 'agent-message-sent'      // Message sent by this agent
+    | 'agent-message-received'  // Message received from another agent
+    | 'tool-result'             // Result from tool execution
+    | 'system-notice'           // System intervention or notice
+    | 'action-history'          // Historical action summary
+    | 'llm-response';           // Direct LLM response
+
+/**
+ * Enhanced conversation message metadata
+ * 
+ * This metadata provides semantic information about messages to enable:
+ * - Provider-specific message structuring (Azure vs OpenRouter vs Anthropic)
+ * - Intelligent filtering and reordering
+ * - Context management and optimization
+ * - Relationship tracking between messages
+ */
+export interface ConversationMessageMetadata {
+    // Context Layer: What part of the agent's context is this?
+    contextLayer?: ContextLayer;
+    
+    // Message Type: What is the semantic meaning of this message?
+    messageType?: MessageType;
+    
+    // Relationships: How does this message relate to others?
+    inReplyTo?: string;        // Message ID this responds to
+    tool_call_id?: string;     // For tool results - which tool call this responds to
+    fromAgentId?: string;      // Who sent this message
+    toAgentId?: string;        // Who is this message for (if directed)
+    
+    // Processing Hints: How should this message be handled?
+    requiresResponse?: boolean;   // Does this message need a response?
+    ephemeral?: boolean;          // Don't persist long-term (e.g., system notices)
+    excludeFromMcp?: boolean;     // Skip when sending to LLM (internal only)
+    
+    // Backward Compatibility: Deprecated fields (keep for now)
+    layer?: string;               // DEPRECATED: Use contextLayer
+    isToolResult?: boolean;       // DEPRECATED: Use messageType === 'tool-result'
+    isSystemLLM?: boolean;        // DEPRECATED: Use messageType === 'system-notice'
+    agentId?: string;             // DEPRECATED: Use fromAgentId
+    messageContent?: string;      // DEPRECATED: Use content field directly
+    
+    // Original/Legacy: Allow any other fields for backward compatibility
+    [key: string]: any;
+}
+
+/**
+ * Unified conversation message interface
+ * 
+ * Represents a single message in an agent's conversation history with rich metadata
+ * to enable intelligent processing by MCP clients and other consumers.
+ * 
+ * Design Principles:
+ * - Single source of truth: What's stored is what's used
+ * - Rich metadata: Semantic information enables intelligent handling
+ * - Provider agnostic: MCP clients interpret metadata for their specific needs
+ * - Backward compatible: Optional metadata fields don't break existing code
+ */
+export interface ConversationMessage {
+    // Core fields (always present)
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    timestamp: number;
+    
+    // Enhanced metadata (optional, backward compatible)
+    metadata?: ConversationMessageMetadata;
+    
+    // Tool calls (for assistant messages that trigger tool execution)
+    tool_calls?: any[];
+}

package/src/interfaces/ILlmTopicExtractor.ts

@@ -0,0 +1,76 @@
+/**
+ * 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/
+ */
+
+/**
+ * Interface for LLM services that can extract conversation topics and generate summaries
+ * 
+ * This interface defines the contract for LLM-based topic extraction and conversation
+ * summarization. SystemLlmService implements this functionality directly.
+ */
+
+import { Observable } from 'rxjs';
+import { ChannelMessage, ConversationTopic } from '../types/ChannelContext.js';
+
+/**
+ * Options for topic extraction
+ */
+export interface ITopicExtractionOptions {
+    minRelevance?: number;
+    temperature?: number;
+    maxTokens?: number;
+    model?: string;
+}
+
+/**
+ * Options for conversation summarization
+ */
+export interface IConversationSummaryOptions {
+    temperature?: number;
+    maxTokens?: number;
+    model?: string;
+    includeContext?: boolean;
+}
+
+/**
+ * Interface for LLM services that can extract conversation topics and generate summaries
+ */
+export interface ILlmTopicExtractor {
+    /**
+     * Extract topics from channel messages
+     * @param messages - Array of channel messages
+     * @param options - Optional configuration
+     * @returns Observable of conversation topics
+     */
+    extractTopics(
+        messages: ChannelMessage[],
+        options?: ITopicExtractionOptions
+    ): Observable<ConversationTopic[]>;
+
+    /**
+     * Generate conversation summary from channel messages
+     * @param messages - Array of channel messages
+     * @param options - Optional configuration
+     * @returns Observable of summary string
+     */
+    generateConversationSummary(
+        messages: ChannelMessage[],
+        options?: IConversationSummaryOptions
+    ): Observable<string>;
+}

package/src/interfaces/SocketServiceInterface.ts

@@ -0,0 +1,104 @@
+/**
+ * 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/
+ */
+
+/**
+ * Socket Service Interface
+ * 
+ * This interface defines the public API for the SocketService that handler modules need to access.
+ * It ensures proper separation of concerns while allowing the handlers to perform necessary operations.
+ */
+
+import { Server as SocketServer, Socket } from 'socket.io';
+
+/**
+ * Interface for agent socket information
+ */
+export interface AgentSocketInfo {
+    socket: Socket | null;
+    channelId: string;
+    connected: boolean;
+    lastActivity: number;
+}
+
+/**
+ * Socket Service Interface
+ * Defines the public methods that handlers can access
+ */
+export interface ISocketService {
+    /**
+     * Register a socket with an agent ID
+     * @param socket Socket to register
+     * @param agentId Agent ID to associate with the socket
+     * @param channelId Channel ID for the socket context
+     */
+    registerSocket(socket: Socket, agentId: string, channelId: string): void;
+    
+    /**
+     * Unregister a socket
+     * @param socketId Socket ID to unregister
+     * @param agentId Agent ID associated with the socket
+     */
+    unregisterSocket(socketId: string, agentId: string): void;
+    
+    /**
+     * Update the heartbeat timestamp for an agent
+     * @param agentId Agent ID to update heartbeat for
+     */
+    updateHeartbeat(agentId: string): void;
+    
+    /**
+     * Get the socket information for an agent
+     * @param agentId Agent ID to get socket info for
+     * @returns Socket information or null if not found
+     */
+    getAgentSocketInfo(agentId: string): AgentSocketInfo | null;
+    
+    /**
+     * Get the socket for an agent by its ID
+     * @param agentId Agent ID to find the socket for
+     * @returns The socket for the agent, or null if not found
+     */
+    getSocketByAgentId(agentId: string): Socket | null;
+    
+    /**
+     * Get the Socket.IO server instance
+     * @returns The Socket.IO server or null if not initialized
+     */
+    getSocketServer(): SocketServer | null;
+    
+    /**
+     * Get the normalized channel name for a given channel ID
+     * @param channelId Channel ID to normalize
+     * @returns Normalized channel name
+     */
+    getNormalizedChannelName(channelId: string): string;
+    
+    /**
+     * Get all heartbeats for monitoring
+     * @returns Map of agent IDs to last activity timestamps
+     */
+    getAllHeartbeats(): Map<string, number>;
+    
+    /**
+     * Check if the socket service is running
+     * @returns True if the socket server is initialized and running
+     */
+    isRunning(): boolean;
+}

package/src/interfaces/TaskInterfaces.ts

@@ -0,0 +1,53 @@
+/**
+ * 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/
+ */
+
+/**
+ * TaskInterfaces.ts
+ * 
+ * Defines interfaces and types for task requests and responses between agents
+ * in the Model Exchange Framework.
+ */
+
+/**
+ * Interface for task requests
+ */
+export interface SimpleTaskRequest {
+    taskId: string;
+    fromAgentId: string;
+    toAgentId: string;
+    content: string;
+    title?: string; // Task title for display and context
+    description?: string; // Full task description (same as content, for compatibility)
+    metadata?: any; // Task metadata including completion agent designation
+}
+
+/**
+ * Interface for task responses
+ */
+export interface SimpleTaskResponse {
+    taskId: string;
+    toAgentId: string;
+    content: string;
+}
+
+/**
+ * Callback for handling task requests
+ */
+export type TaskRequestHandler = (task: SimpleTaskRequest) => Promise<SimpleTaskResponse>;