@mxf-dev/core 2.0.5 → 3.0.0

package/src/events/EventNames.ts

@@ -224,6 +224,11 @@ import type { ProgressPayloads } from './event-definitions/ProgressEvents.js';
 export { ProgressEvents };
 export type { ProgressPayloads };
 
+import { SdkEvents } from './event-definitions/SdkEvents.js';
+import type { SdkPayloads } from './event-definitions/SdkEvents.js';
+export { SdkEvents };
+export type { SdkPayloads };
+
 /**
  * Socket Authentication Events
  * Used for socket authentication success/failure communication
@@ -236,41 +241,42 @@ export const AuthEvents = {
 /**
  * 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 LlmBudget = LlmBudgetEvents;
-    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;
-}
+export const Events = {
+    Core: CoreSocketEvents,
+    Agent: AgentEvents,
+    Message: MessageEvents,
+    Channel: ChannelEventsInternal,
+    Key: KeyEvents,
+    Task: TaskEvents,
+    LlmService: LlmServiceEvents,
+    ControlLoop: ControlLoopEvents,
+    Orpar: OrparEvents,
+    Heartbeat: HeartbeatEvents,
+    Mcp: McpEvents,
+    Memory: MemoryEventsInternal,
+    System: SystemEvents,
+    Analytics: AnalyticsEvents,
+    Config: ConfigEvents,
+    Bulk: BulkEvents,
+    Auth: AuthEvents,
+    Mxp: MxpEvents,
+    Meilisearch: MeilisearchEvents,
+    LlmBudget: LlmBudgetEvents,
+    CodeExecution: CodeExecutionEvents,
+    Shell: ShellExecutionEvents,
+    Workflow: WorkflowEvents,
+    InferenceParameter: InferenceParameterEvents,
+    Plan: PlanEvents,
+    MemoryUtility: MemoryUtilityEvents,
+    OrparMemory: OrparMemoryEvents,
+    Dag: DagEvents,
+    KnowledgeGraph: KnowledgeGraphEvents,
+    TensorFlow: TensorFlowEvents,
+    UserInput: UserInputEvents,
+    Compaction: CompactionEvents,
+    Progress: ProgressEvents,
+    Sdk: SdkEvents,
+} as const;
 
 /**
  * Complete event map combining all event payloads
@@ -306,7 +312,8 @@ export type EventMap =
     TensorFlowPayloads &
     UserInputPayloads &
     CompactionPayloads &
-    ProgressPayloads;
+    ProgressPayloads &
+    SdkPayloads;
 
 /**
  * Event name type - any valid event name

package/src/events/PublicEvents.ts

@@ -165,6 +165,13 @@ export const PUBLIC_MEILISEARCH_EVENTS = [
     Events.Meilisearch.BACKFILL_PARTIAL,
 ] as const;
 
+/**
+ * Public SDK Events - the SDK's own user connection
+ */
+export const PUBLIC_SDK_EVENTS = [
+    Events.Sdk.RECONNECTED,
+] as const;
+
 /**
  * Combined array of all public events
  */
@@ -179,6 +186,7 @@ export const PUBLIC_EVENTS = [
     ...PUBLIC_CHANNEL_EVENTS,
     ...PUBLIC_USER_INPUT_EVENTS,
     ...PUBLIC_MEILISEARCH_EVENTS,
+    ...PUBLIC_SDK_EVENTS,
 ] as const;
 
 /**

package/src/events/ServerEventBus.ts

@@ -27,16 +27,10 @@
  */
 
 import { Subject } from 'rxjs';
-import type { Server as SocketIOServer } from 'socket.io';
-import { ControlLoopEvents } from './event-definitions/ControlLoopEvents.js';
-import { OrparEvents } from './event-definitions/OrparEvents.js';
-import { McpEvents } from './event-definitions/McpEvents.js';
-import { TaskEvents } from './event-definitions/TaskEvents.js';
 import {
     AnyEventName,
     BaseEventBusImplementation,
     EventMessage,
-    isReservedEvent,
     PayloadOf
 } from './EventBusBase.js';
 import { createStrictValidator } from '../utils/validation.js';
@@ -52,25 +46,6 @@ const validator = createStrictValidator('ServerEventBus');
  * Server-side event bus interface
  */
 export interface IServerEventBus extends BaseEventBusImplementation {
-    /**
-     * Set the Socket.IO server instance
-     * @param io Socket.IO server instance
-     * @returns this (for chaining)
-     */
-    setSocketServer(io: SocketIOServer): this;
-    
-    /**
-     * Clear the Socket.IO server instance
-     * @returns this (for chaining)
-     */
-    clearSocketServer(): this;
-    
-    /**
-     * Remove all server event listeners
-     * @returns this (for chaining)
-     */
-    removeAllSocketListeners(): this;
-
     /**
      * Clean up all subscriptions and listeners
      * @returns this (for chaining)
@@ -82,41 +57,6 @@ export interface IServerEventBus extends BaseEventBusImplementation {
  * Server-side event bus implementation
  */
 export class ServerEventBus extends BaseEventBusImplementation implements IServerEventBus {
-    /**
-     * Events delivered to specific agents/channels by eventForwardingHandlers.
-     * Broadcasting these over io.emit() would deliver them twice.
-     */
-    private static readonly AGENT_SPECIFIC_EVENTS: ReadonlySet<string> = new Set<string>([
-        ...Object.values(ControlLoopEvents),
-        ...Object.values(OrparEvents),
-        // MCP response events
-        McpEvents.TOOL_RESULT,
-        McpEvents.TOOL_ERROR,
-        McpEvents.TOOL_REGISTERED,
-        McpEvents.TOOL_UNREGISTERED,
-        McpEvents.MXF_TOOL_LIST_RESULT,
-        McpEvents.MXF_TOOL_LIST_ERROR,
-        McpEvents.RESOURCE_RESULT,
-        McpEvents.RESOURCE_ERROR,
-        McpEvents.EXTERNAL_SERVER_REGISTERED,
-        McpEvents.EXTERNAL_SERVER_UNREGISTERED,
-        McpEvents.EXTERNAL_SERVER_REGISTRATION_FAILED,
-        McpEvents.CHANNEL_SERVER_REGISTERED,
-        McpEvents.CHANNEL_SERVER_UNREGISTERED,
-        McpEvents.CHANNEL_SERVER_REGISTRATION_FAILED,
-        // Task lifecycle events
-        TaskEvents.CREATED,
-        TaskEvents.ASSIGNED,
-        TaskEvents.STARTED,
-        TaskEvents.PROGRESS_UPDATED,
-        TaskEvents.COMPLETED,
-        TaskEvents.FAILED,
-        TaskEvents.ERROR,
-        TaskEvents.CANCELLED,
-    ]);
-
-    private ioInstance: SocketIOServer | null = null;
-
     /**
      * Create a new ServerEventBus
      * @param eventSubject Subject to use for events
@@ -126,85 +66,26 @@ export class ServerEventBus extends BaseEventBusImplementation implements IServe
     }
     
     /**
-     * Set the Socket.IO server instance
-     * @param io Socket.IO server instance
-     * @returns this (for chaining)
-     */
-    public setSocketServer(io: SocketIOServer): this {
-        try {
-            validator.assertIsObject(io);
-            validator.assertHasFunction(io, 'emit');
-            validator.assertHasFunction(io, 'to');
-            
-            this.ioInstance = io;
-            
-        } catch (error) {
-            logger.error('[ServerEventBus] Error setting Socket.IO server:', error instanceof Error ? error.message : String(error));
-            throw new Error(`Error setting Socket.IO server: ${error instanceof Error ? error.message : 'Invalid server instance'}`);
-        }
-        
-        return this;
-    }
-    
-    /**
-     * Clear the Socket.IO server instance
-     * @returns this (for chaining)
-     */
-    public clearSocketServer(): this {
-        this.ioInstance = null;
-        
-        
-        return this;
-    }
-    
-    /**
-     * Forward an emitted event to the Socket.IO server.
-     *
      * Called by BaseEventBusImplementation.emit() after validation and local
-     * delivery.
-     *
-     * Agent-specific events are NOT broadcast with io.emit(). They are routed
-     * to individual agents/channels by eventForwardingHandlers. Broadcasting
-     * them would duplicate delivery: the SDK's ClientEventBus.setupClientSocketForwarding()
-     * re-injects everything the socket receives back into the shared RxJS Subject,
-     * so a broadcast event would be seen twice (once from the Subject push, once
-     * from the socket re-injection).
+     * delivery. The server bus has no transport: EventBus events often contain
+     * private memory, prompts, tool results, or channel data, and a partial
+     * denylist would turn every newly added event into an unauthenticated
+     * global broadcast. Reviewed routing belongs to eventForwardingHandlers,
+     * which selects an authenticated agent or Socket.IO room explicitly, so
+     * this bus holds no Socket.IO server reference at all.
      */
     protected override forwardToTransport<K extends AnyEventName>(event: K, payload: PayloadOf<K>): void {
-        if (!this.ioInstance) {
-            return;
-        }
-
-        const eventName = String(event);
-        if (isReservedEvent(eventName) || ServerEventBus.AGENT_SPECIFIC_EVENTS.has(eventName)) {
-            return;
-        }
-
-        this.ioInstance.emit(eventName, payload);
-    }
-
-    /**
-     * Drop the Socket.IO server reference so no further events are broadcast.
-     *
-     * The bus attaches no listeners to the Socket.IO server — it only calls
-     * io.emit() — so there is nothing else to detach here.
-     *
-     * @returns this (for chaining)
-     */
-    public removeAllSocketListeners(): this {
-        this.ioInstance = null;
-
-        return this;
+        void event;
+        void payload;
     }
 
     /**
-     * Dispose every subscription and detach the Socket.IO server.
+     * Dispose every subscription.
      *
      * @returns this (for chaining)
      */
     public cleanup(): this {
         this.removeAllListeners();
-        this.removeAllSocketListeners();
 
         return this;
     }

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

@@ -23,6 +23,12 @@
  */
 export const ControlLoopEvents = {
     INITIALIZE: 'controlLoop:initialize', // Request to initialize a control loop
+    START_REQUEST: 'controlLoop:start:request', // Request to start a control loop
+    STOP_REQUEST: 'controlLoop:stop:request', // Request to stop a control loop
+    OBSERVATION_SUBMIT: 'controlLoop:observation:submit', // Submit an observation
+    EXECUTION_REQUEST: 'controlLoop:execution:request', // Request action execution
+    PLAN_SUBMIT: 'controlLoop:plan:submit', // Submit an agent-generated plan
+    REFLECTION_SUBMIT: 'controlLoop:reflection:submit', // Submit an agent reflection
     INITIALIZED: 'controlLoop:initialized', // Control loop has been initialized
     STARTED: 'controlLoop:started', // Control loop has been started
     OBSERVATION: 'controlLoop:observation', // Observation submitted to control loop
@@ -45,6 +51,12 @@ export const ControlLoopEvents = {
  */
 export interface ControlLoopPayloads {
     'controlLoop:initialize': { loopId: string, timestamp: number };
+    'controlLoop:start:request': { loopId: string, timestamp: number };
+    'controlLoop:stop:request': { loopId: string, timestamp: number, reason?: string };
+    'controlLoop:observation:submit': { loopId: string, timestamp: number, observation: unknown };
+    'controlLoop:execution:request': { loopId: string, timestamp: number, action: unknown };
+    'controlLoop:plan:submit': { loopId: string, timestamp: number, plan: unknown };
+    'controlLoop:reflection:submit': { loopId: string, timestamp: number, reflection: unknown };
     'controlLoop:initialized': { loopId: string, timestamp: number };
     'controlLoop:started': { loopId: string, timestamp: number };
     'controlLoop:observation': { loopId: string, timestamp: number, observation: any };

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

@@ -0,0 +1,58 @@
+/**
+ * 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/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+import { BaseEventPayload } from '../../schemas/EventPayloadSchema.js';
+
+/**
+ * SDK connection lifecycle events.
+ *
+ * These describe the SDK's own user connection, not an agent. They are
+ * delivered to local subscribers only (EventBus.client.emitLocal) and never
+ * sent over the socket.
+ */
+export const SdkEvents = {
+    /**
+     * The socket manager re-established the user connection and the server
+     * re-authenticated it, without a connect() call waiting on the result.
+     * Anything the server forgot while the connection was down — registered
+     * channel MCP server processes, for example — may need to be set up again.
+     */
+    RECONNECTED: 'sdk:reconnected',
+} as const;
+
+/**
+ * Data carried by SdkEvents.RECONNECTED.
+ */
+export interface SdkReconnectedEventData {
+    /** Server-confirmed user id of the re-authenticated connection. */
+    userId: string;
+    /**
+     * Transport reconnect attempts reported by the socket manager, or null
+     * when the manager did not report one before authentication succeeded.
+     */
+    attempt: number | null;
+}
+
+/**
+ * SDK event payload types
+ */
+export interface SdkPayloads {
+    'sdk:reconnected': BaseEventPayload<SdkReconnectedEventData>;
+}

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

@@ -98,7 +98,7 @@ export type TaskProgressEvent = TaskEventPayload & {
 export type TaskCompletedEvent = TaskEventPayload & {
     data: {
         task: ChannelTask;
-        result: any;
+        result: unknown;
         duration: number; // in minutes
     };
 };
@@ -172,7 +172,7 @@ export interface TaskPayloads {
     'task:fail_request': TaskEventPayload & { data: { task: ChannelTask; error: string } };
     'task:cancel_request': TaskEventPayload & { data: { task: ChannelTask; reason?: string } };
     'task:assign_request': TaskEventPayload & { data: { task: ChannelTask; agentId: AgentId } };
-    'task:update_request': TaskEventPayload & { data: { task: ChannelTask; updates: Record<string, any> } };
+    'task:update_request': TaskEventPayload;
     'task:workload_analyze_request': TaskEventPayload & { data: { channelId: ChannelId } };
     
     // Core task lifecycle events

package/src/index.ts

@@ -9,6 +9,21 @@ export type { EventName } from './events/EventNames.js';
 export { EventBus } from './events/EventBus.js';
 export { Logger } from './utils/Logger.js';
 export { ConfigManager } from './config/ConfigManager.js';
+export {
+    CORE_MXF_TOOLS,
+    isCoreToolName,
+} from './constants/CoreTools.js';
+export type { CoreMxfTool } from './constants/CoreTools.js';
+export {
+    MemoryPersistenceLevel,
+    MemoryScope,
+} from './types/MemoryTypes.js';
+export type {
+    IAgentMemory,
+    IChannelMemory,
+    IRelationshipMemory,
+    MemoryData,
+} from './types/MemoryTypes.js';
 export {
     DEFAULT_SERVER_CONFIG,
     getServerConfig,

package/src/interfaces/AgentInterfaces.ts

@@ -104,6 +104,11 @@ export interface AgentConfig {
     providerOptions?: Record<string, any>;
     
     // Tool access control
+    /**
+     * Requested subset of the authenticated channel key's tool grant.
+     * `undefined` selects MXF's curated core-tool set; `[]` denies every tool.
+     * A client request can narrow its credential grant but cannot expand it.
+     */
     allowedTools?: string[];
     circuitBreakerExemptTools?: string[];    // Tools exempt from circuit breaker detection (for game tools, etc.)
     

package/src/interfaces/ChannelConfig.ts

@@ -26,8 +26,8 @@ export interface ChannelMcpServerConfig {
     name: string;
     command?: string;
     args?: string[];
-    transport?: 'stdio' | 'http';
-    url?: string;
+    /** Caller-supplied runtime registration currently supports stdio only. */
+    transport?: 'stdio';
     autoStart?: boolean;
     environmentVariables?: Record<string, string>;
     restartOnCrash?: boolean;

package/src/interfaces/ConversationMessage.ts

@@ -41,6 +41,11 @@ export type MessageType =
     | 'agent-message-received'  // Message received from another agent
     | 'tool-result'             // Result from tool execution
     | 'system-notice'           // System intervention or notice
+    | 'system-event'            // Framework event injected into conversation context
+    | 'systemllm-coordination'  // Ephemeral SystemLLM coordination context
+    | 'channel-message-immediate' // Channel notification awaiting agent review
+    | 'error_feedback'          // Validation or execution feedback
+    | 'error_correction_trigger' // Prompt to correct an earlier invalid action
     | 'action-history'          // Historical action summary
     | 'llm-response';           // Direct LLM response
 

package/src/interfaces/IMemoryPersistence.ts

@@ -13,9 +13,38 @@
  */
 
 import { Observable } from 'rxjs';
-import { IAgentMemory, IChannelMemory } from '../types/MemoryTypes.js';
+import {
+    IAgentMemory,
+    IChannelMemory,
+    IRelationshipMemory,
+    MemoryScope
+} from '../types/MemoryTypes.js';
 import { MemoryUtilitySubdocument } from '../types/MemoryUtilityTypes.js';
 
+/**
+ * A mutation against one reserved field in a channel-memory document.
+ *
+ * Append mutations are deliberately expressed as database operations instead of
+ * read/modify/write replacements. That lets the persistence adapter retain every
+ * concurrently submitted batch with one atomic document update.
+ */
+export type ChannelMemoryAtomicMutation =
+    | { kind: 'append_messages'; messages: unknown[] }
+    | { kind: 'replace_context'; context: unknown; expectedUpdatedAt?: number }
+    | { kind: 'append_context_history'; entries: unknown[]; retainLast: number }
+    | { kind: 'delete_messages' }
+    | { kind: 'delete_context' }
+    | { kind: 'delete_context_history' };
+
+export interface ChannelMemoryAtomicMutationResult {
+    /** Whether the targeted channel/key existed for this operation. */
+    found: boolean;
+    /** The authoritative document after the mutation, or null for a missing delete target. */
+    memory: IChannelMemory | null;
+    /** The authoritative value of the reserved field after the mutation. */
+    value: unknown;
+}
+
 export interface IMemoryPersistence {
     /** Load an agent's memory document. */
     getAgentMemory(agentId: string): Observable<IAgentMemory>;
@@ -26,6 +55,31 @@ export interface IMemoryPersistence {
     /** Persist a channel's memory document. */
     saveChannelMemory(memory: IChannelMemory): Observable<IChannelMemory>;
 
+    /** Load a channel's memory document. */
+    getChannelMemory(channelId: string): Observable<IChannelMemory>;
+
+    /**
+     * Atomically mutate one reserved channel-memory field and return the
+     * authoritative post-update document/value.
+     */
+    mutateChannelMemory(
+        channelId: string,
+        mutation: ChannelMemoryAtomicMutation
+    ): Observable<ChannelMemoryAtomicMutationResult>;
+
+    /** Load relationship memory using its full tenant identity. */
+    getRelationshipMemory?(
+        agentId1: string,
+        agentId2: string,
+        channelId: string
+    ): Observable<IRelationshipMemory>;
+
+    /** Persist relationship memory using its full tenant identity. */
+    saveRelationshipMemory?(memory: IRelationshipMemory): Observable<IRelationshipMemory>;
+
+    /** Delete one exact memory scope identity from persistent storage. */
+    deleteMemory?(scope: MemoryScope, id: string | string[]): Observable<boolean>;
+
     /**
      * Persist the MULS utility subdocument for a single memory.
      *

package/src/interfaces/SocketServiceInterface.ts

@@ -73,9 +73,10 @@ export interface ISocketService {
     /**
      * 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
+     * @param channelId Authenticated channel the event is scoped to
+     * @returns The socket for the agent in that exact channel, or null if not found
      */
-    getSocketByAgentId(agentId: string): Socket | null;
+    getSocketByAgentId(agentId: string, channelId: string): Socket | null;
     
     /**
      * Get the Socket.IO server instance

package/src/interfaces/TaskInterfaces.ts

@@ -35,7 +35,16 @@ export interface SimpleTaskRequest {
     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
+    /** Agent designated to report the task's terminal outcome; the server enforces it. */
+    completionAgentId?: string;
+    /** Every agent assigned to the task. */
+    assignedAgentIds?: string[];
+    /**
+     * Task metadata. Role flags (isCompletionAgent, multiAgentTask, agentRole)
+     * are present only on the late-assignment flows; the creator's own
+     * metadata is passed through on direct assignment.
+     */
+    metadata?: Record<string, unknown>;
 }
 
 /**
@@ -51,3 +60,9 @@ export interface SimpleTaskResponse {
  * Callback for handling task requests
  */
 export type TaskRequestHandler = (task: SimpleTaskRequest) => Promise<SimpleTaskResponse>;
+
+/** Terminal outcomes the server broadcasts for a task. */
+export type TaskOutcome = 'completed' | 'failed' | 'cancelled';
+
+/** Called once when the task this agent was assigned reaches a terminal outcome. */
+export type TaskEndedHandler = (taskId: string, outcome: TaskOutcome) => void;

package/src/models/agent.ts

@@ -40,7 +40,6 @@ export interface IAgent extends Document {
     keyId?: string;            // API key used as lookup for this agent
     role?: string;             // Agent's role (e.g., "assistant", "specialist")
     specialization?: string;   // Agent's area of specialization
-    allowedTools?: string[];   // Tool access control - list of allowed MCP tools
     
     // Agent context (read-only)
     context?: {
@@ -123,11 +122,6 @@ const AgentSchema: Schema = new Schema(
         specialization: {
             type: String
         },
-        allowedTools: {
-            type: [String],
-            required: false,
-            default: undefined  // undefined = all tools allowed
-        },
         
         // Agent context
         context: {