@kadi.build/core 0.0.1-alpha.4 → 0.0.1-alpha.5

package/dist/KadiClient.js

@@ -7,6 +7,7 @@ import { StdioTransport } from './transports/StdioTransport.js';
 import { createComponentLogger } from './utils/logger.js';
 import { IdFactory, KadiMessages } from './messages/BrokerMessages.js';
 import { loadAbility } from './loadAbility.js';
+import { getAgentJSON } from './utils/agentUtils.js';
 // Internal event transport constants
 // These are NOT user events - they're internal mechanisms for transporting events between protocols
 /**
@@ -83,9 +84,10 @@ export class KadiClient extends EventEmitter {
     description;
     role;
     protocol;
-    scope;
+    network;
     networks;
-    brokerUrls;
+    brokers;
+    defaultBroker;
     abilityAgentJSON;
     logger;
     protocolHandler;
@@ -97,6 +99,24 @@ export class KadiClient extends EventEmitter {
     _idFactory;
     _pendingResponses = new Map();
     _pendingToolCalls = new Map();
+    _currentBroker; // The currently active broker name
+    /**
+     * Resolver function for the native protocol serve promise.
+     * When serve() is called with native protocol, it creates a promise to keep
+     * the process alive. This resolver allows us to resolve that promise during
+     * disconnect(), enabling clean shutdown of native abilities.
+     */
+    _nativeServePromiseResolve;
+    /**
+     * Stores all event subscriptions as a Map of pattern → array of callback functions
+     * Example structure:
+     * {
+     *   'user.login' => [handleLogin, logLoginEvent],      // 2 functions listening to user.login
+     *   'payment.*' => [processPayment],                   // 1 function listening to all payment events
+     *   'system.shutdown' => [saveState, cleanupResources] // 2 functions for shutdown
+     * }
+     * When an event arrives, we check which patterns match and call all their callbacks
+     */
     _eventSubscriptions = new Map();
     constructor(options = {}) {
         super();
@@ -108,14 +128,17 @@ export class KadiClient extends EventEmitter {
         this.role = options.role || 'ability';
         this.protocol =
             options.protocol || process.env.KADI_PROTOCOL || 'native';
-        this.scope = options.scope || 'global';
+        this.network = options.network || options.scope || 'global'; // Support legacy 'scope' parameter
         this.networks = options.networks || ['global'];
-        this.brokerUrls =
-            options.brokerUrls || (options.brokerUrl ? [options.brokerUrl] : []);
+        // Broker integration logic with agent.json fallback
+        this.brokers = this.resolveBrokerConfiguration(options);
+        this.defaultBroker = this.resolveDefaultBroker(options);
+        this._currentBroker = this.defaultBroker; // Initialize current broker to default
         this.abilityAgentJSON = options.abilityAgentJSON;
         // Initialize ID factory
         this._idFactory = new IdFactory();
         this.logger.lifecycle('constructor', `Creating client: ${this.name}@${this.version} (role: ${this.role}, protocol: ${this.protocol})`);
+        this.logger.debug('constructor', `Resolved ${Object.keys(this.brokers).length} brokers, default: ${this.defaultBroker}`);
         // Create protocol handler for stdio (broker is handled internally)
         if (this.protocol !== 'broker') {
             this.protocolHandler = ProtocolHandlerFactory.create(this.protocol, options);
@@ -129,6 +152,119 @@ export class KadiClient extends EventEmitter {
             }
         }
     }
+    /**
+     * Get the currently active broker name
+     */
+    get currentBroker() {
+        return this._currentBroker;
+    }
+    /**
+     * Set the currently active broker
+     * @param brokerName The name of the broker to use
+     * @throws Error if the broker name doesn't exist in configuration
+     */
+    setCurrentBroker(brokerName) {
+        if (!this.brokers[brokerName]) {
+            const availableBrokers = Object.keys(this.brokers);
+            throw new Error(`Broker '${brokerName}' not found in configuration.\n` +
+                `Available brokers: ${availableBrokers.join(', ') || 'none'}`);
+        }
+        this._currentBroker = brokerName;
+        this.logger.info('setCurrentBroker', `Switched current broker to: ${brokerName}`);
+    }
+    /**
+     * Get the current broker's connection (if connected)
+     */
+    getCurrentBrokerConnection() {
+        if (!this._currentBroker) {
+            throw new Error('No current broker set');
+        }
+        const brokerUrl = this.brokers[this._currentBroker];
+        const connection = this._brokerConnections.find((c) => c.url === brokerUrl);
+        if (!connection) {
+            throw new Error(`Not connected to broker '${this._currentBroker}' (${brokerUrl}). ` +
+                `Call connectToBrokers() first.`);
+        }
+        return connection;
+    }
+    /**
+     * Resolve broker configuration with agent.json integration
+     * Precedence: Code brokers > agent.json brokers > environment defaults
+     */
+    resolveBrokerConfiguration(options) {
+        this.logger.debug('resolveBrokerConfiguration', 'Entering broker resolution');
+        // If brokers specified in code, use them (override behavior)
+        if (options.brokers && Object.keys(options.brokers).length > 0) {
+            this.logger.info('resolveBrokerConfiguration', `Using ${Object.keys(options.brokers).length} brokers from code configuration`);
+            this.logger.debug('resolveBrokerConfiguration', `Code brokers: ${Object.keys(options.brokers).join(', ')}`);
+            return options.brokers;
+        }
+        // Try to load brokers from agent.json
+        try {
+            const agentJson = getAgentJSON();
+            if (agentJson?.brokers && Object.keys(agentJson.brokers).length > 0) {
+                this.logger.info('resolveBrokerConfiguration', `Using ${Object.keys(agentJson.brokers).length} brokers from agent.json`);
+                this.logger.debug('resolveBrokerConfiguration', `agent.json brokers: ${Object.keys(agentJson.brokers).join(', ')}`);
+                return agentJson.brokers;
+            }
+            else {
+                this.logger.debug('resolveBrokerConfiguration', 'No brokers found in agent.json');
+            }
+        }
+        catch (error) {
+            this.logger.warn('resolveBrokerConfiguration', `Failed to load agent.json: ${error instanceof Error ? error.message : error}`);
+        }
+        // Fallback to environment/default
+        const fallbackUrl = process.env.KADI_BROKER_URL || 'ws://localhost:8080';
+        const fallbackBrokers = { default: fallbackUrl };
+        this.logger.info('resolveBrokerConfiguration', `Using fallback broker configuration: default -> ${fallbackUrl}`);
+        this.logger.debug('resolveBrokerConfiguration', 'Exiting broker resolution with fallback');
+        return fallbackBrokers;
+    }
+    /**
+     * Resolve default broker with fallback logic
+     * Priority: Explicit defaultBroker > agent.json defaultBroker > 'prod' key > first broker key
+     */
+    resolveDefaultBroker(options) {
+        this.logger.debug('resolveDefaultBroker', 'Entering default broker resolution');
+        const brokerKeys = Object.keys(this.brokers);
+        // If no brokers available, no default possible
+        if (brokerKeys.length === 0) {
+            this.logger.warn('resolveDefaultBroker', 'No brokers available, cannot determine default');
+            return undefined;
+        }
+        // Check explicit defaultBroker from code
+        if (options.defaultBroker) {
+            if (this.brokers[options.defaultBroker]) {
+                this.logger.info('resolveDefaultBroker', `Using explicit default broker from code: ${options.defaultBroker}`);
+                return options.defaultBroker;
+            }
+            else {
+                this.logger.warn('resolveDefaultBroker', `Specified default broker '${options.defaultBroker}' not found in broker list`);
+            }
+        }
+        // Check defaultBroker from agent.json
+        try {
+            const agentJson = getAgentJSON();
+            if (agentJson?.defaultBroker && this.brokers[agentJson.defaultBroker]) {
+                this.logger.info('resolveDefaultBroker', `Using default broker from agent.json: ${agentJson.defaultBroker}`);
+                return agentJson.defaultBroker;
+            }
+        }
+        catch (error) {
+            this.logger.debug('resolveDefaultBroker', `Could not check agent.json for default broker: ${error instanceof Error ? error.message : error}`);
+        }
+        // Fallback to 'prod' if it exists
+        if (this.brokers['prod']) {
+            this.logger.info('resolveDefaultBroker', 'Using fallback default broker: prod');
+            return 'prod';
+        }
+        // Final fallback: first broker in the list
+        const firstBroker = brokerKeys[0];
+        this.logger.info('resolveDefaultBroker', `Using first available broker as default: ${firstBroker}`);
+        this.logger.debug('resolveDefaultBroker', 'Exiting default broker resolution');
+        return firstBroker;
+    }
     /**
      * Register a tool for this service
      *
@@ -213,15 +349,22 @@ export class KadiClient extends EventEmitter {
             return;
         }
         // For broker, send event message
+        // TODO: To make things consistent with the above, we can create a
+        // TODO: PublishEvent function inside BrokerTransport. Another reason
+        // TODO: why i think we should do this is because the BrokerTransport
+        // TODO: Implements the Transport interface which (optionally) has
+        // TODO: a publishEvent function
         if (this.protocol === 'broker' && this._brokerConnections.length > 0) {
             this.logger.debug('publishEvent', `Publishing broker event: ${eventName}`);
+            // TODO: Instead of picking the first broker, we should pick the
+            // TODO: the currently active broker name. See: "_currentBroker?: string;"
             const broker = this._brokerConnections[0];
             if (broker.ws && broker.ws.readyState === WebSocket.OPEN) {
                 const eventMessage = {
                     jsonrpc: '2.0',
                     method: KadiMessages.EVENT_PUBLISH,
                     params: {
-                        channel: eventName, // RabbitMQ calls this "routing key"
+                        channel: eventName, // RabbitMQ calls this a "routing key"
                         data
                     }
                 };
@@ -237,29 +380,77 @@ export class KadiClient extends EventEmitter {
         }
     }
     /**
-     * Connect to brokers (for event subscription and/or broker protocol)
+     * Connect to all configured brokers (for event subscription and/or broker protocol)
+     * Always connects to ALL brokers defined in this.brokers for maximum redundancy
      */
-    async connectToBrokers(urls) {
+    async connectToBrokers() {
+        this.logger.debug('connectToBrokers', 'Entering broker connection process');
+        // Check if already connected to avoid duplicate connections
+        if (this._brokerConnections.length > 0) {
+            this.logger.debug('connectToBrokers', 'Already connected to brokers, skipping');
+            return;
+        }
         // Allow any protocol to connect to brokers for event subscription
         // The protocol only determines how this client itself serves, not what it can connect to
-        const brokerUrls = urls || [
-            process.env.KADI_BROKER_URL || 'ws://localhost:8080'
-        ];
-        this.logger.info('connectToBrokers', `Connecting to ${brokerUrls.length} broker(s)`);
-        for (const url of brokerUrls) {
-            await this.connectToBroker(url);
+        const brokerNames = Object.keys(this.brokers);
+        const brokerUrls = Object.values(this.brokers);
+        if (brokerUrls.length === 0) {
+            const fallbackUrl = process.env.KADI_BROKER_URL || 'ws://localhost:8080';
+            this.logger.warn('connectToBrokers', `No brokers configured, using fallback: default -> ${fallbackUrl}`);
+            await this.connectToBroker(fallbackUrl, 'default');
+            this._isConnected = true;
+            this.emit('connected');
+            this.logger.debug('connectToBrokers', 'Exiting broker connection process with fallback');
+            return;
+        }
+        this.logger.info('connectToBrokers', `Connecting to ${brokerUrls.length} configured broker(s): ${brokerNames.join(', ')}`);
+        const connectionPromises = brokerNames.map(async (brokerName, index) => {
+            const url = brokerUrls[index];
+            try {
+                await this.connectToBroker(url, brokerName);
+                this.logger.info('connectToBrokers', `✅ Successfully connected to broker: ${brokerName} (${url})`);
+                return { brokerName, url, success: true, error: null };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                this.logger.warn('connectToBrokers', `❌ Failed to connect to broker ${brokerName} (${url}): ${errorMessage}`);
+                return { brokerName, url, success: false, error: errorMessage };
+            }
+        });
+        const results = await Promise.allSettled(connectionPromises);
+        const connectionResults = results.map((result, index) => result.status === 'fulfilled'
+            ? result.value
+            : { url: brokerUrls[index], success: false, error: 'Promise rejected' });
+        const successfulConnections = connectionResults.filter((result) => result.success);
+        const failedConnections = connectionResults.filter((result) => !result.success);
+        if (successfulConnections.length === 0) {
+            const errorMessage = `Failed to connect to any brokers. Attempted: ${brokerUrls.join(', ')}`;
+            this.logger.error('connectToBrokers', errorMessage);
+            throw new Error(errorMessage);
+        }
+        this.logger.info('connectToBrokers', `Connected to ${successfulConnections.length}/${brokerUrls.length} brokers`);
+        if (failedConnections.length > 0) {
+            this.logger.warn('connectToBrokers', `Some brokers failed to connect: ${failedConnections.map((f) => f.url).join(', ')}`);
         }
         this._isConnected = true;
         this.emit('connected');
     }
+    /**
+     * Check if connected to a specific broker URL
+     */
+    isConnectedToBroker(url) {
+        return this._brokerConnections.some((conn) => conn.url === url);
+    }
     /**
      * Connect to a single broker
      */
-    async connectToBroker(url) {
-        this.logger.info('connectToBroker', `Connecting to broker at ${url}`);
+    async connectToBroker(url, brokerName) {
+        const displayName = brokerName ? `${brokerName} (${url})` : url;
+        this.logger.info('connectToBroker', `Connecting to broker: ${displayName}`);
         const ws = new WebSocket(url);
         const connection = {
             url,
+            brokerName,
             ws,
             isAuthenticated: false,
             agentId: '' // Use agentId instead of sessionId
@@ -290,9 +481,10 @@ export class KadiClient extends EventEmitter {
                 this.handleBrokerMessage(connection, data.toString());
             });
             ws.on('close', () => {
-                this.logger.info('connectToBroker', `Disconnected from ${url}`);
+                this.logger.info('connectToBroker', `WebSocket close event for ${brokerName} (${url})`);
                 // Clean up heartbeat timer
                 if (connection.heartbeatTimer) {
+                    this.logger.debug('connectToBroker', `Cleaning up heartbeat timer in close event for ${brokerName}`);
                     clearInterval(connection.heartbeatTimer);
                     connection.heartbeatTimer = undefined;
                     this.logger.debug('connectToBroker', 'Heartbeat timer cleaned up');
@@ -414,11 +606,9 @@ export class KadiClient extends EventEmitter {
     sendRequest(connection, message) {
         return new Promise((resolve, reject) => {
             const id = message.id;
-            // ! DO NOT USE CONSOLE.LOG use the the logger
-            console.log(`[KadiClient] 📤 SENDING REQUEST:`, JSON.stringify(message, null, 2));
+            this.logger.trace('sendBrokerRequest', `Sending ${message.method} request (ID: ${id})`);
             const timeout = setTimeout(() => {
-                // ! DO NOT USE CONSOLE.LOG use the the logger
-                console.log(`[KadiClient] ⏰ TIMEOUT for request ${id} (${message.method})`);
+                this.logger.warn('sendBrokerRequest', `Request timeout for ${message.method} (ID: ${id})`);
                 this._pendingResponses.delete(id);
                 reject(new Error(`Request timeout: ${message.method}`));
             }, 30000);
@@ -427,8 +617,7 @@ export class KadiClient extends EventEmitter {
                 reject,
                 timer: timeout
             });
-            // ! DO NOT USE CONSOLE.LOG use the the logger
-            console.log(`[KadiClient] 📝 STORED pending response for ID: ${id}`);
+            this.logger.trace('sendBrokerRequest', `Stored pending response for ${message.method} (ID: ${id})`);
             connection.ws.send(JSON.stringify(message));
         });
     }
@@ -533,9 +722,9 @@ export class KadiClient extends EventEmitter {
             return;
         }
         try {
-            console.log(`[KadiClient] 🔧 EXECUTING TOOL: ${toolName} with params:`, toolInput);
+            this.logger.debug('handleToolInvocation', `Executing tool: ${toolName}`);
             const result = await method.handler(toolInput);
-            console.log(`[KadiClient] ✅ TOOL RESULT for ${toolName}:`, result);
+            this.logger.debug('handleToolInvocation', `Tool ${toolName} completed successfully`);
             // Send kadi.ability.result with success result
             const resultMessage = {
                 jsonrpc: '2.0',
@@ -546,11 +735,11 @@ export class KadiClient extends EventEmitter {
                     result
                 }
             };
-            console.log(`[KadiClient] 📤 SENDING RESULT:`, JSON.stringify(resultMessage, null, 2));
+            this.logger.trace('handleToolInvocation', `Sending result for tool: ${toolName}`);
             connection.ws.send(JSON.stringify(resultMessage));
         }
         catch (error) {
-            console.log(`[KadiClient] ❌ TOOL ERROR for ${toolName}:`, error);
+            this.logger.error('handleToolInvocation', `Tool ${toolName} failed: ${error.message}`);
             // Send kadi.ability.result with error
             const errorMessage = {
                 jsonrpc: '2.0',
@@ -619,7 +808,7 @@ export class KadiClient extends EventEmitter {
                     name: this.name,
                     version: this.version,
                     description: this.description,
-                    scope: this.scope
+                    network: this.network
                 });
             }
         }
@@ -632,8 +821,15 @@ export class KadiClient extends EventEmitter {
                         protocol: this.protocol,
                         tools: this.getToolNames()
                     });
-                    // Keep process alive
-                    return new Promise(() => { });
+                    // Keep process alive with a cancelable promise.
+                    // When abilities are loaded natively, they still call serve() which
+                    // creates this promise. We store the resolver so disconnect() can
+                    // resolve it later, allowing the process to exit cleanly.
+                    // Without this, the unresolved promise would keep the Node.js event
+                    // loop running forever, preventing graceful shutdown.
+                    return new Promise((resolve) => {
+                        this._nativeServePromiseResolve = resolve;
+                    });
                 case 'stdio':
                     // For stdio serving, delegate to StdioTransport's serve method
                     // This handles JSON-RPC over stdin/stdout when running as a child process
@@ -729,7 +925,7 @@ export class KadiClient extends EventEmitter {
      * @returns The result from the remote tool invocation
      */
     async callTool(targetAgent, toolName, params) {
-        if (this.protocol !== 'broker' || this._brokerConnections.length === 0) {
+        if (this._brokerConnections.length === 0) {
             throw new Error('Must be connected to broker to call remote tools');
         }
         const broker = this._brokerConnections[0];
@@ -768,10 +964,130 @@ export class KadiClient extends EventEmitter {
         }
     }
     /**
-     * Load an external ability
+     * Send a request directly to the broker
+     * Uses the current broker or the specified broker
+     *
+     * @param method The RPC method to call (e.g., 'kadi.ability.list')
+     * @param params The parameters for the method
+     * @param brokerName Optional broker name to use (overrides current broker)
+     * @returns The response from the broker
+     */
+    async sendBrokerRequest(method, params, brokerName) {
+        // If specific broker requested, temporarily use it
+        const originalBroker = this._currentBroker;
+        if (brokerName) {
+            this.setCurrentBroker(brokerName);
+        }
+        try {
+            const connection = this.getCurrentBrokerConnection();
+            const request = {
+                jsonrpc: '2.0',
+                method,
+                params,
+                id: this._idFactory.next()
+            };
+            const response = await this.sendRequest(connection, request);
+            if ('error' in response && response.error) {
+                throw new Error(`Broker request failed: ${response.error.message || 'Unknown error'}`);
+            }
+            return response.result;
+        }
+        finally {
+            // Restore original broker if we changed it
+            if (brokerName && originalBroker) {
+                this._currentBroker = originalBroker;
+            }
+        }
+    }
+    /**
+     * Load an external ability and make its methods available for calling
+     *
+     * This is the KadiClient's convenient wrapper for loading abilities. It handles
+     * broker resolution from your client config and delegates the actual loading
+     * to the standalone loadAbility() function.
+     *
+     * Note: This method delegates to the standalone loadAbility() function after
+     * resolving broker configurations. If you need more control or don't have a
+     * KadiClient instance, you can use the standalone loadAbility() function directly.
+     *
+     * @param nameOrPath - Which ability to load. Can be:
+     *   - "ability-name" - loads from your installed abilities
+     *   - "/path/to/ability" - loads from a folder path
+     *
+     * @param protocol - How to connect to the ability:
+     *   - 'native': Load directly into this process (fastest, same language only)
+     *   - 'stdio': Spawn as child process, communicate via stdin/stdout (any language)
+     *   - 'broker': Connect via broker (ability runs anywhere, most flexible)
+     *
+     * @param options - Configuration for how to load the ability:
+     *
+     *   broker: Which named broker to use (from your KadiClient config). Only for 'broker' protocol.
+     *     Example: 'prod', 'local', 'staging'
+     *     Uses your current/default broker if not specified.
+     *
+     *   brokerUrl: Direct broker WebSocket URL. Only for 'broker' protocol.
+     *     Example: 'ws://localhost:8080', 'wss://broker.company.com'
+     *     Overrides the 'broker' option if provided.
+     *
+     *   spawnAbility: Whether to start the ability first. Only for 'broker' protocol.
+     *     - true: Start the ability process AND connect to it (useful for development)
+     *     - false (default): Just connect to an already-running ability
+     *     Most production setups use false since abilities run independently.
+     *
+     *   networks: Which KADI networks to search for the ability. Only for 'broker' protocol.
+     *     Example: ['global', 'team-alpha', 'dev-environment']
+     *     search specific networks to find them. Defaults to ['global'] if not specified.
+     *
+     * @returns A proxy object that lets you call the ability's methods directly.
+     *   Example: ability.processData({input: "hello"}) calls the ability's processData method.
+     *
+     * @example
+     * // Load a JavaScript ability in the same process (fastest)
+     * const mathLib = await client.loadAbility('math-utils', 'native');
+     * const result = await mathLib.add({a: 5, b: 3}); // Returns 8
+     *
+     * @example
+     * // Load a Go/Python/Rust ability via child process
+     * const imageProcessor = await client.loadAbility('image-resizer', 'stdio');
+     * const thumbnail = await imageProcessor.resize({image: buffer, size: '100x100'});
+     *
+     * @example
+     * // Connect to an ability running on a remote broker (using named broker from config)
+     * const aiService = await client.loadAbility('gpt-analyzer', 'broker', {
+     *   broker: 'prod',  // Use the 'prod' broker from KadiClient config
+     *   networks: ['ai-services', 'global']  // Look in these networks
+     * });
+     * const analysis = await aiService.analyze({text: "Hello world"});
      */
     async loadAbility(nameOrPath, protocol = 'native', options = {}) {
-        const ability = await loadAbility(nameOrPath, protocol, options);
+        // For broker protocol, resolve broker name to URL
+        let resolvedOptions = { ...options };
+        if (protocol === 'broker') {
+            // If brokerUrl not provided, resolve from broker name or use current/default
+            if (!options.brokerUrl) {
+                const brokerName = options.broker || this._currentBroker || this.defaultBroker;
+                if (!brokerName) {
+                    throw new Error(`No broker specified. Either provide 'broker' option or set a default broker.`);
+                }
+                if (!this.brokers[brokerName]) {
+                    const availableBrokers = Object.keys(this.brokers);
+                    throw new Error(`Broker '${brokerName}' not found in configuration.\n` +
+                        `Available brokers: ${availableBrokers.join(', ') || 'none'}\n` +
+                        `Add broker to KadiClient config or agent.json.`);
+                }
+                // If a specific broker was requested, update current broker
+                if (options.broker) {
+                    this.setCurrentBroker(brokerName);
+                }
+                resolvedOptions.brokerUrl = this.brokers[brokerName];
+                this.logger.debug('loadAbility', `Resolved broker '${brokerName}' to URL: ${resolvedOptions.brokerUrl}`);
+            }
+        }
+        // Pass the client instance for broker protocol to reuse connection
+        const optionsWithClient = protocol === 'broker'
+            ? { ...resolvedOptions, existingClient: this }
+            : resolvedOptions;
+        const ability = await loadAbility(nameOrPath, protocol, optionsWithClient);
         this._abilities.set(ability.name, ability);
         // For native/stdio protocols, connect ability events to this client's event system
         if (protocol === 'native' || protocol === 'stdio') {
@@ -804,21 +1120,40 @@ export class KadiClient extends EventEmitter {
         return ability;
     }
     /**
-     * Disconnect from brokers
+     * Disconnect from brokers and cleanup resources
      */
     async disconnect() {
+        this.logger.info('disconnect', `Starting disconnect for ${this.name}`);
+        // Resolve the native serve promise if it exists
+        // This is critical for native protocol abilities to shut down cleanly.
+        // When an ability calls serve() in native mode, it creates a promise
+        // that keeps the process alive. By resolving it here, we allow the
+        // Node.js event loop to exit naturally.
+        if (this._nativeServePromiseResolve) {
+            this.logger.debug('disconnect', 'Resolving native serve promise to allow clean shutdown');
+            this._nativeServePromiseResolve();
+            this._nativeServePromiseResolve = undefined;
+        }
+        // Disconnect from all broker connections (if any)
+        this.logger.info('disconnect', `Disconnecting from ${this._brokerConnections.length} broker connections`);
         for (const connection of this._brokerConnections) {
             // Clean up heartbeat timer before closing
             if (connection.heartbeatTimer) {
+                this.logger.debug('disconnect', `Clearing heartbeat timer for ${connection.brokerName}`);
                 clearInterval(connection.heartbeatTimer);
                 connection.heartbeatTimer = undefined;
             }
             if (connection.ws) {
+                this.logger.debug('disconnect', `Closing WebSocket for ${connection.brokerName}`);
                 connection.ws.close();
             }
         }
         this._brokerConnections.length = 0;
         this._isConnected = false;
+        // Remove all event listeners
+        this.logger.debug('disconnect', 'Removing all internal event listeners');
+        this.removeAllListeners();
+        this.logger.info('disconnect', `Disconnect complete for ${this.name}`);
         this.emit('disconnected');
     }
     /**
@@ -836,6 +1171,7 @@ export class KadiClient extends EventEmitter {
     }
     /**
      * Find agent.json file
+     * TODO: Not sure, but maybe this function can be moved to pathUtils.ts?
      */
     async _findAgentJson() {
         const possiblePaths = [
@@ -971,9 +1307,13 @@ export class KadiClient extends EventEmitter {
             this.on(ABILITY_EVENT_TRANSPORT, (envelope) => {
                 this.logger.trace('subscribeToEvent', `Received ${ABILITY_EVENT_TRANSPORT}: ${envelope.eventName}`);
                 // Check all registered patterns to see which subscriptions match this event
+                // _eventSubscriptions is a Map like: {'user.login' => [callbacks], 'payment.*' => [callbacks]}
+                // We loop through each pattern to see if the incoming event matches
                 for (const [registeredPattern] of this._eventSubscriptions) {
+                    // Example: If event is 'user.login' and pattern is 'user.*', this matches!
                     if (this._matchesPattern(envelope.eventName, registeredPattern)) {
                         this.logger.debug('subscribeToEvent', `Pattern matched (${envelope.eventName} vs ${registeredPattern}), dispatching event`);
+                        // Found a match! Call all callbacks registered for this pattern
                         this._dispatchEvent(registeredPattern, envelope.data);
                     }
                 }
@@ -1002,8 +1342,11 @@ export class KadiClient extends EventEmitter {
         /**
          * Subscribe to broker events for this specific pattern.
          * Broker subscriptions are per-pattern, unlike the transport listeners above.
+         * Only connect to broker if we're actually using the broker protocol.
          */
-        if (this.brokerUrls && this.brokerUrls.length > 0) {
+        if (this.protocol === 'broker' &&
+            this.brokers &&
+            Object.keys(this.brokers).length > 0) {
             if (this._brokerConnections.length === 0) {
                 this.logger.debug('subscribeToEvent', 'Connecting to broker for event subscription');
                 this.connectToBrokers()
@@ -1127,21 +1470,34 @@ export class KadiClient extends EventEmitter {
         return false;
     }
     /**
-     * Dispatch event to subscribers
-     * TODO: I do not understand this function
+     * Dispatch event to subscribers - This is the final delivery step
+     *
+     * After all the routing through transports and pattern matching,
+     * this function actually calls the user's callback functions with the event data.
+     *
+     * Example: If user did `client.subscribeToEvent('user.login', myFunction)`
+     * then when 'user.login' event arrives, this calls `myFunction(eventData)`
      *
      * @private
-     * @param pattern Pattern that matched
-     * @param data Event data
+     * @param pattern Pattern that matched (e.g., 'user.login' or 'payment.*')
+     * @param data Event data to pass to the callbacks
      */
     _dispatchEvent(pattern, data) {
+        // Get all callback functions registered for this pattern
+        // Example: If pattern is 'user.login', this gets [callback1, callback2] array
         const callbacks = this._eventSubscriptions.get(pattern);
         if (callbacks) {
+            // Call each registered callback with the event data
+            // If multiple functions subscribed to same pattern, all get called
             callbacks.forEach((callback) => {
                 try {
+                    // This is THE moment the user's function gets called!
+                    // Example: callback(data) might be userFunction({userId: 123, timestamp: ...})
                     callback(data);
                 }
                 catch (error) {
+                    // If user's callback throws error, log it but continue with other callbacks
+                    // This prevents one bad callback from breaking all event delivery
                     this.logger.error('_dispatchEvent', `Error in event callback for ${pattern}:`, error);
                 }
             });