@mxf-dev/core 1.0.0

package/src/events/EventNames.ts

@@ -0,0 +1,308 @@
+/**
+ * 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/
+ */
+
+/**
+ * Event Names and Payload Types
+ * 
+ * This file centralizes all event names and their associated payload types used in the framework 
+ * to avoid string literals and prevent mismatches between emitters and listeners.
+ * 
+ * THIS IS THE SINGLE SOURCE OF TRUTH for all event names and payload types in the framework.
+ * Both the server and SDK import from this file.
+ */
+
+/**
+ * Core Socket.IO events that are part of the Socket.IO library itself
+ */
+export const CoreSocketEvents = {
+    // Standard Socket.IO events
+    CONNECT: 'connect', // Fired when the client successfully connects to the server
+    DISCONNECT: 'disconnect', // Fired when the client disconnects from the server
+    CONNECT_ERROR: 'connect_error', // Fired when the connection cannot be established
+    RECONNECT: 'reconnect', // Fired when the client successfully reconnects after disconnection
+    RECONNECT_ATTEMPT: 'reconnect_attempt', // Fired when attempting to reconnect
+    RECONNECT_ERROR: 'reconnect_error', // Fired when a reconnection attempt error occurs
+    RECONNECT_FAILED: 'reconnect_failed', // Fired when all reconnection attempts have failed
+    ERROR: 'error', // Fired when an error occurs in Socket.IO
+
+    // Socket.IO protocol events
+    CONNECTION: 'connection', // Fired on the server when a new client connects
+    PING: 'ping', // Internal ping event to check connection health
+    PONG: 'pong', // Response to ping event
+};
+
+/**
+ * Reserved socket.io events that should not be re-emitted to prevent loops and conflicts
+ */
+export const SOCKET_RESERVED_EVENTS = Object.values(CoreSocketEvents);
+
+export type SocketReservedEventType = typeof SOCKET_RESERVED_EVENTS[number];
+
+/**
+ * Payload types for Core Socket.IO events
+ */
+export interface CoreSocketPayloads {
+    'connect': void;
+    'disconnect': { reason: string };
+    'connect_error': Error;
+    'reconnect': number;
+    'reconnect_attempt': number;
+    'reconnect_error': Error;
+    'reconnect_failed': void;
+    'error': Error;
+    'connection': { socketId: string };
+    'ping': any;
+    'pong': any;
+}
+
+import { AgentEvents } from './event-definitions/AgentEvents.js';
+import type { AgentPayloads, AgentRegistrationEvent, AgentConnectionEvent } from './event-definitions/AgentEvents.js';
+export { AgentEvents };
+export type { AgentPayloads, AgentRegistrationEvent, AgentConnectionEvent };
+
+import { MessageEvents } from './event-definitions/MessageEvents.js';
+import type { MessagePayloads, AgentMessageEvent } from './event-definitions/MessageEvents.js';
+export { MessageEvents };
+export type { MessagePayloads, AgentMessageEvent };
+
+import { Events as ChannelEventsInternal, ChannelActionTypes } from './event-definitions/ChannelEvents.js';
+import type { ChannelPayloads, ChannelActionType, ChannelCreationEvent } from './event-definitions/ChannelEvents.js';
+export { ChannelEventsInternal as ChannelEvents, ChannelActionTypes };
+export type { ChannelPayloads, ChannelActionType, ChannelCreationEvent };
+
+import { MemoryEvents as MemoryEventsInternal, MemoryEvents } from './event-definitions/MemoryEvents.js';
+import type { MemoryPayloads, MemoryUpdateEvent, MemoryCreateEvent, MemoryScope, MemoryGetEvent, MemoryDeleteEvent, MemorySyncEvent } from './event-definitions/MemoryEvents.js';
+export { MemoryEvents };
+export type { MemoryPayloads, MemoryUpdateEvent, MemoryCreateEvent, MemoryScope, MemoryGetEvent, MemoryDeleteEvent, MemorySyncEvent };
+
+import { TaskEvents } from './event-definitions/TaskEvents.js';
+import type { TaskPayloads, TaskRequestEvent, TaskResponseEvent } from './event-definitions/TaskEvents.js';
+export { TaskEvents };
+export type { TaskPayloads, TaskRequestEvent, TaskResponseEvent };
+
+import { LlmServiceEvents } from './event-definitions/LlmEvents.js';
+import type { LlmServicePayloads } from './event-definitions/LlmEvents.js';
+export { LlmServiceEvents };
+export type { LlmServicePayloads };
+
+import { HeartbeatEvents } from './event-definitions/HeartbeatEvents.js';
+import type { HeartbeatPayloads } from './event-definitions/HeartbeatEvents.js';
+export { HeartbeatEvents };
+export type { HeartbeatPayloads };
+
+import { McpEvents } from './event-definitions/McpEvents.js';
+import type { McpPayloads } from './event-definitions/McpEvents.js';
+export { McpEvents };
+export type { McpPayloads };
+
+import { ControlLoopEvents } from './event-definitions/ControlLoopEvents.js';
+import type { ControlLoopPayloads } from './event-definitions/ControlLoopEvents.js';
+export { ControlLoopEvents };
+export type { ControlLoopPayloads };
+
+import { OrparEvents } from './event-definitions/OrparEvents.js';
+import type { OrparPayloads } from './event-definitions/OrparEvents.js';
+export { OrparEvents };
+export type { OrparPayloads };
+
+import { SystemEvents } from './event-definitions/SystemEvents.js';
+export { SystemEvents };
+
+import { AnalyticsEvents } from './event-definitions/AnalyticsEvents.js';
+import type { AnalyticsPayloads } from './event-definitions/AnalyticsEvents.js';
+export { AnalyticsEvents };
+export type { AnalyticsPayloads };
+
+import { ConfigEvents } from './event-definitions/ConfigEvents.js';
+import type { ConfigPayloads } from './event-definitions/ConfigEvents.js';
+export { ConfigEvents };
+export type { ConfigPayloads };
+
+import { BulkEvents } from './event-definitions/BulkEvents.js';
+import type { BulkPayloads } from './event-definitions/BulkEvents.js';
+export { BulkEvents };
+export type { BulkPayloads };
+
+import { MxpEvents } from './event-definitions/MxpEvents.js';
+import type { MxpPayloads } from './event-definitions/MxpEvents.js';
+export { MxpEvents };
+export type { MxpPayloads };
+
+import { KeyEvents } from './event-definitions/KeyEvents.js';
+import type { KeyPayloads } from './event-definitions/KeyEvents.js';
+export { KeyEvents };
+export type { KeyPayloads };
+
+import { MeilisearchEvents } from './event-definitions/MeilisearchEvents.js';
+import type { MeilisearchPayloads } from './event-definitions/MeilisearchEvents.js';
+export { MeilisearchEvents };
+export type { MeilisearchPayloads };
+
+import { CodeExecutionEvents } from './event-definitions/CodeExecutionEvents.js';
+import type { CodeExecutionPayloads } from './event-definitions/CodeExecutionEvents.js';
+export { CodeExecutionEvents };
+export type { CodeExecutionPayloads };
+
+import { ShellExecutionEvents } from './event-definitions/ShellExecutionEvents.js';
+import type { ShellExecutionPayloads } from './event-definitions/ShellExecutionEvents.js';
+export { ShellExecutionEvents };
+export type { ShellExecutionPayloads };
+
+import { WorkflowEvents } from './event-definitions/WorkflowEvents.js';
+import type { WorkflowPayloads } from './event-definitions/WorkflowEvents.js';
+export { WorkflowEvents };
+export type { WorkflowPayloads };
+
+import { InferenceParameterEvents } from './event-definitions/InferenceParameterEvents.js';
+import type { InferenceParameterPayloads } from './event-definitions/InferenceParameterEvents.js';
+export { InferenceParameterEvents };
+export type { InferenceParameterPayloads };
+
+import { PlanEvents } from './event-definitions/PlanEvents.js';
+import type { PlanPayloads, PlanStepCompletedEventData } from './event-definitions/PlanEvents.js';
+export { PlanEvents };
+export type { PlanPayloads, PlanStepCompletedEventData };
+
+import { MemoryUtilityEvents } from './event-definitions/MemoryUtilityEvents.js';
+import type { MemoryUtilityPayloads } from './event-definitions/MemoryUtilityEvents.js';
+export { MemoryUtilityEvents };
+export type { MemoryUtilityPayloads };
+
+import { OrparMemoryEvents } from './event-definitions/OrparMemoryEvents.js';
+import type { OrparMemoryPayloads } from './event-definitions/OrparMemoryEvents.js';
+export { OrparMemoryEvents };
+export type { OrparMemoryPayloads };
+
+import { DagEvents } from './event-definitions/DagEvents.js';
+import type { DagPayloads } from './event-definitions/DagEvents.js';
+export { DagEvents };
+export type { DagPayloads };
+
+import { KnowledgeGraphEvents } from './event-definitions/KnowledgeGraphEvents.js';
+import type { KnowledgeGraphPayloads } from './event-definitions/KnowledgeGraphEvents.js';
+export { KnowledgeGraphEvents };
+export type { KnowledgeGraphPayloads };
+
+import { TensorFlowEvents } from './event-definitions/TensorFlowEvents.js';
+import type { TensorFlowPayloads } from './event-definitions/TensorFlowEvents.js';
+export { TensorFlowEvents };
+export type { TensorFlowPayloads };
+
+import { UserInputEvents } from './event-definitions/UserInputEvents.js';
+import type { UserInputPayloads } from './event-definitions/UserInputEvents.js';
+export { UserInputEvents };
+export type { UserInputPayloads };
+
+import { CompactionEvents } from './event-definitions/CompactionEvents.js';
+import type { CompactionPayloads } from './event-definitions/CompactionEvents.js';
+export { CompactionEvents };
+export type { CompactionPayloads };
+
+import { ProgressEvents } from './event-definitions/ProgressEvents.js';
+import type { ProgressPayloads } from './event-definitions/ProgressEvents.js';
+export { ProgressEvents };
+export type { ProgressPayloads };
+
+/**
+ * Socket Authentication Events
+ * Used for socket authentication success/failure communication
+ */
+export const AuthEvents = {
+    SUCCESS: 'auth:success',
+    ERROR: 'auth:error'
+} as const;
+
+/**
+ * Unified export of all events for convenience
+ */
+export namespace Events {
+    export const Core = CoreSocketEvents;
+    export const Agent = AgentEvents;
+    export const Message = MessageEvents;
+    export const Channel = ChannelEventsInternal;
+    export const Key = KeyEvents;
+    export const Task = TaskEvents;
+    export const LlmService = LlmServiceEvents;
+    export const ControlLoop = ControlLoopEvents;
+    export const Orpar = OrparEvents;
+    export const Heartbeat = HeartbeatEvents;
+    export const Mcp = McpEvents;
+    export const Memory = MemoryEventsInternal;
+    export const System = SystemEvents;
+    export const Analytics = AnalyticsEvents;
+    export const Config = ConfigEvents;
+    export const Bulk = BulkEvents;
+    export const Auth = AuthEvents;
+    export const Mxp = MxpEvents;
+    export const Meilisearch = MeilisearchEvents;
+    export const CodeExecution = CodeExecutionEvents;
+    export const Shell = ShellExecutionEvents;
+    export const Workflow = WorkflowEvents;
+    export const InferenceParameter = InferenceParameterEvents;
+    export const Plan = PlanEvents;
+    export const MemoryUtility = MemoryUtilityEvents;
+    export const OrparMemory = OrparMemoryEvents;
+    export const Dag = DagEvents;
+    export const KnowledgeGraph = KnowledgeGraphEvents;
+    export const TensorFlow = TensorFlowEvents;
+    export const UserInput = UserInputEvents;
+    export const Compaction = CompactionEvents;
+    export const Progress = ProgressEvents;
+}
+
+/**
+ * Complete event map combining all event payloads
+ */
+export type EventMap =
+    CoreSocketPayloads &
+    AgentPayloads &
+    MessagePayloads &
+    ChannelPayloads &
+    KeyPayloads &
+    TaskPayloads &
+    LlmServicePayloads &
+    ControlLoopPayloads &
+    OrparPayloads &
+    HeartbeatPayloads &
+    McpPayloads &
+    MemoryPayloads &
+    AnalyticsPayloads &
+    ConfigPayloads &
+    BulkPayloads &
+    MxpPayloads &
+    MeilisearchPayloads &
+    CodeExecutionPayloads &
+    ShellExecutionPayloads &
+    WorkflowPayloads &
+    InferenceParameterPayloads &
+    PlanPayloads &
+    MemoryUtilityPayloads &
+    OrparMemoryPayloads &
+    DagPayloads &
+    KnowledgeGraphPayloads &
+    TensorFlowPayloads &
+    UserInputPayloads &
+    CompactionPayloads &
+    ProgressPayloads;
+
+/**
+ * Event name type - any valid event name
+ */
+export type EventName = keyof EventMap;

package/src/events/PublicEvents.ts

@@ -0,0 +1,231 @@
+/**
+ * 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/
+ */
+
+/**
+ * Public Events
+ * 
+ * Defines which events are safe for external developer consumption.
+ * Internal/sensitive events are NOT exposed through agent.on() API.
+ */
+
+import { Events } from './EventNames.js';
+
+/**
+ * Public Agent Events - Safe for developers to listen to
+ */
+export const PUBLIC_AGENT_EVENTS = [
+    Events.Agent.CONNECTED,
+    Events.Agent.DISCONNECTED,
+    Events.Agent.REGISTERED,
+    Events.Agent.REGISTRATION_FAILED,
+    Events.Agent.STATUS_CHANGE,
+    Events.Agent.ERROR,
+    Events.Agent.JOIN_CHANNEL,
+    Events.Agent.LEAVE_CHANNEL,
+    Events.Agent.LLM_RESPONSE,
+    Events.Agent.LLM_REASONING,
+    Events.Agent.LLM_REASONING_PARSED,
+    Events.Agent.LLM_REASONING_TOOLS_SYNTHESIZED,
+    Events.Agent.LLM_USAGE,
+    Events.Agent.TASK_ASSIGNED,
+] as const;
+
+/**
+ * Public Message Events - Core messaging functionality
+ */
+export const PUBLIC_MESSAGE_EVENTS = [
+    Events.Message.CHANNEL_MESSAGE,
+    Events.Message.AGENT_MESSAGE,
+    Events.Message.CHANNEL_MESSAGE_DELIVERED,
+    Events.Message.AGENT_MESSAGE_DELIVERED,
+    Events.Message.MESSAGE_SEND_FAILED,
+    Events.Message.MESSAGE_ERROR,
+] as const;
+
+/**
+ * Public Task Events - Task lifecycle
+ */
+export const PUBLIC_TASK_EVENTS = [
+    Events.Task.ASSIGNED,
+    Events.Task.COMPLETED,
+    Events.Task.FAILED,
+    Events.Task.PROGRESS_UPDATED,
+    Events.Task.CREATED,
+    Events.Task.REQUEST,
+    Events.Task.RESPONSE,
+] as const;
+
+/**
+ * Public MCP/Tool Events - Tool execution feedback and server management
+ */
+export const PUBLIC_MCP_EVENTS = [
+    Events.Mcp.TOOL_CALL,
+    Events.Mcp.TOOL_RESULT,
+    Events.Mcp.TOOL_ERROR,
+    Events.Mcp.TOOL_REGISTERED,
+    Events.Mcp.TOOL_LIST_RESULT,
+    Events.Mcp.EXTERNAL_SERVER_REGISTERED,
+    Events.Mcp.EXTERNAL_SERVER_UNREGISTERED,
+    Events.Mcp.EXTERNAL_SERVER_TOOLS_DISCOVERED,
+    Events.Mcp.EXTERNAL_SERVER_REGISTRATION_FAILED,
+] as const;
+
+/**
+ * Public Memory Events - Memory operation results
+ */
+export const PUBLIC_MEMORY_EVENTS = [
+    Events.Memory.GET_RESULT,
+    Events.Memory.UPDATE_RESULT,
+    Events.Memory.CREATE_RESULT,
+    Events.Memory.DELETE_RESULT,
+    Events.Memory.SYNC_COMPLETE,
+    Events.Memory.GET_ERROR,
+    Events.Memory.UPDATE_ERROR,
+    Events.Memory.CREATE_ERROR,
+] as const;
+
+/**
+ * Public Control Loop Events - Server-orchestrated reasoning phases
+ */
+export const PUBLIC_CONTROL_LOOP_EVENTS = [
+    Events.ControlLoop.OBSERVATION,
+    Events.ControlLoop.REASONING,
+    Events.ControlLoop.PLAN,
+    Events.ControlLoop.ACTION,
+    Events.ControlLoop.REFLECTION,
+    Events.ControlLoop.EXECUTION,
+    Events.ControlLoop.ERROR,
+] as const;
+
+/**
+ * Public ORPAR Events - Agent-driven cognitive cycle documentation
+ *
+ * These events are emitted when agents explicitly call orpar_* tools to document
+ * their cognitive process. They are DISTINCT from ControlLoopEvents which are
+ * emitted by the server-orchestrated control loop system.
+ */
+export const PUBLIC_ORPAR_EVENTS = [
+    Events.Orpar.OBSERVE,
+    Events.Orpar.REASON,
+    Events.Orpar.PLAN,
+    Events.Orpar.ACT,
+    Events.Orpar.REFLECT,
+    Events.Orpar.STATUS,
+    Events.Orpar.ERROR,
+] as const;
+
+/**
+ * Public Channel Events - Channel lifecycle
+ */
+export const PUBLIC_CHANNEL_EVENTS = [
+    Events.Channel.AGENT_JOINED,
+    Events.Channel.AGENT_LEFT,
+    Events.Channel.CONTEXT.UPDATED,
+    Events.Channel.CREATED,
+    Events.Channel.UPDATED,
+] as const;
+
+/**
+ * Public User Input Events - User input prompting and collection
+ */
+export const PUBLIC_USER_INPUT_EVENTS = [
+    Events.UserInput.REQUEST,
+    Events.UserInput.RESPONSE,
+    Events.UserInput.CANCELLED,
+    Events.UserInput.TIMEOUT,
+] as const;
+
+/**
+ * Public Meilisearch Events - Semantic search operations
+ */
+export const PUBLIC_MEILISEARCH_EVENTS = [
+    'meilisearch:index',
+    'meilisearch:backfill:complete',
+    'meilisearch:backfill:partial',
+    'meilisearch:search',
+] as const;
+
+/**
+ * Combined array of all public events
+ */
+export const PUBLIC_EVENTS = [
+    ...PUBLIC_AGENT_EVENTS,
+    ...PUBLIC_MESSAGE_EVENTS,
+    ...PUBLIC_TASK_EVENTS,
+    ...PUBLIC_MCP_EVENTS,
+    ...PUBLIC_MEMORY_EVENTS,
+    ...PUBLIC_CONTROL_LOOP_EVENTS,
+    ...PUBLIC_ORPAR_EVENTS,
+    ...PUBLIC_CHANNEL_EVENTS,
+    ...PUBLIC_USER_INPUT_EVENTS,
+    ...PUBLIC_MEILISEARCH_EVENTS,
+] as const;
+
+/**
+ * Type representing all public event names
+ */
+export type PublicEventName = typeof PUBLIC_EVENTS[number];
+
+/**
+ * Check if an event is safe for public consumption
+ * 
+ * @param eventName - Event name to check
+ * @returns True if event is in the public whitelist
+ */
+export const isPublicEvent = (eventName: string): eventName is PublicEventName => {
+    return (PUBLIC_EVENTS as readonly string[]).includes(eventName);
+};
+
+/**
+ * Get human-readable category for a public event
+ * 
+ * @param eventName - Public event name
+ * @returns Event category or 'unknown'
+ */
+export const getEventCategory = (eventName: PublicEventName): string => {
+    if (PUBLIC_AGENT_EVENTS.includes(eventName as any)) return 'agent';
+    if (PUBLIC_MESSAGE_EVENTS.includes(eventName as any)) return 'message';
+    if (PUBLIC_TASK_EVENTS.includes(eventName as any)) return 'task';
+    if (PUBLIC_MCP_EVENTS.includes(eventName as any)) return 'mcp';
+    if (PUBLIC_MEMORY_EVENTS.includes(eventName as any)) return 'memory';
+    if (PUBLIC_CONTROL_LOOP_EVENTS.includes(eventName as any)) return 'controlLoop';
+    if (PUBLIC_ORPAR_EVENTS.includes(eventName as any)) return 'orpar';
+    if (PUBLIC_CHANNEL_EVENTS.includes(eventName as any)) return 'channel';
+    if (PUBLIC_USER_INPUT_EVENTS.includes(eventName as any)) return 'userInput';
+    if (PUBLIC_MEILISEARCH_EVENTS.includes(eventName as any)) return 'meilisearch';
+    return 'unknown';
+};
+
+/**
+ * INTERNAL/SENSITIVE EVENTS (NOT EXPOSED)
+ * 
+ * These events are for framework internal use only:
+ * - Events.System.* - System internals
+ * - Events.Heartbeat.* - Connection health monitoring
+ * - Events.LlmService.* - Internal SystemLLM operations
+ * - Events.Analytics.* - Internal metrics collection
+ * - Events.Config.* - Internal configuration changes
+ * - Events.Bulk.* - Internal bulk operations
+ * - Events.Auth.* - Authentication flow (security sensitive)
+ * - Events.Core.* - Low-level Socket.IO events
+ * - Events.Mxp.ENCRYPTION_* - Security/encryption internals
+ * 
+ * Attempting to listen to these through agent.on() will throw an error.
+ */