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

package/dist/KadiClient.js

@@ -0,0 +1,1518 @@
+import { EventEmitter } from 'events';
+import WebSocket from 'ws';
+import crypto from 'node:crypto';
+import fs from 'fs';
+import path from 'path';
+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
+/**
+ * ABILITY_EVENT_TRANSPORT - Internal event used to transport events from loaded abilities
+ * to the main client. When an ability (loaded via native/stdio) publishes an event like
+ * 'echo.test-event', we wrap it in this transport event to move it from the ability
+ * context to the main client context, where it can be unwrapped and delivered to
+ * user subscriptions.
+ *
+ * Think of it like an envelope: The actual event ('echo.test-event') is the letter,
+ * and ABILITY_EVENT_TRANSPORT is the envelope we put it in for delivery.
+ */
+const ABILITY_EVENT_TRANSPORT = '__KADI_INTERNAL_ABILITY_EVENT_TRANSPORT__';
+/**
+ * ProtocolHandlerFactory - Creates the right handler for each communication protocol
+ */
+class ProtocolHandlerFactory {
+    static create(protocol, options = {}) {
+        switch (protocol?.toLowerCase()) {
+            case 'native':
+                // No handler needed - direct method calls
+                return undefined;
+            case 'stdio':
+                // Use StdioTransport for child process communication
+                return new StdioTransport({
+                    abilityName: options.name || 'unnamed-client',
+                    abilityVersion: options.version || '1.0.0',
+                    abilityDir: process.cwd(),
+                    startCmd: 'node index.js',
+                    manifest: options
+                });
+            case 'broker':
+                // For broker protocol, we handle it directly in KadiClient
+                // No separate handler needed as KadiClient has built-in broker support
+                return undefined;
+            default:
+                return undefined;
+        }
+    }
+}
+/**
+ * KadiClient - Unified client for KADI protocol
+ *
+ * This class combines the functionality of KadiAgent and KadiAbility,
+ * providing a single interface for:
+ *
+ * 1. Registering tools that can be called by others
+ * 2. Calling remote tools on other services
+ * 3. Supporting multiple protocols (native, stdio, broker)
+ * 4. Connecting to broker with configurable role (agent, ability, service)
+ *
+ * @example
+ * ```typescript
+ * // Create as an ability
+ * const service = new KadiClient({
+ *   name: 'math-service',
+ *   role: 'ability',
+ *   protocol: 'broker'
+ * });
+ *
+ * // Register tools
+ * service.registerTool('add', async ({a, b}) => ({result: a + b}));
+ *
+ * // With schema
+ * service.tool('multiply', async ({a, b}) => ({result: a * b}));
+ *
+ * // Start serving
+ * await service.serve();
+ * ```
+ */
+export class KadiClient extends EventEmitter {
+    name;
+    version;
+    description;
+    role;
+    protocol;
+    network;
+    networks;
+    brokers;
+    defaultBroker;
+    abilityAgentJSON;
+    logger;
+    protocolHandler;
+    toolHandlers = new Map();
+    _abilities = new Map();
+    _brokerConnections = [];
+    _isConnected = false;
+    _agentId = '';
+    _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();
+        this.logger = createComponentLogger(`KadiClient:${options.name || 'unnamed'}`);
+        // Store configuration
+        this.name = options.name || 'unnamed-client';
+        this.version = options.version || '1.0.0';
+        this.description = options.description || '';
+        this.role = options.role || 'ability';
+        this.protocol =
+            options.protocol || process.env.KADI_PROTOCOL || 'native';
+        this.network = options.network || options.scope || 'global'; // Support legacy 'scope' parameter
+        this.networks = options.networks || ['global'];
+        // 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);
+            // Forward events from protocol handler
+            if (this.protocolHandler) {
+                this.protocolHandler.on('start', (data) => this.emit('start', { ...data, protocol: this.protocol }));
+                this.protocolHandler.on('error', (error) => this.emit('error', error));
+                this.protocolHandler.on('stop', () => this.emit('stop'));
+                this.protocolHandler.on('request', (data) => this.emit('request', data));
+                this.protocolHandler.on('response', (data) => this.emit('response', data));
+            }
+        }
+    }
+    /**
+     * 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
+     *
+     * @param name - Tool name
+     * @param handler - Handler function
+     * @param schema - Optional schema
+     * @returns This instance for chaining
+     */
+    registerTool(name, handler, schema) {
+        if (typeof name !== 'string') {
+            throw new TypeError('Tool name must be a string');
+        }
+        if (typeof handler !== 'function') {
+            throw new TypeError('Tool handler must be a function');
+        }
+        this.logger.trace('registerTool', `Registering tool: ${name}`);
+        this.toolHandlers.set(name, {
+            name,
+            handler,
+            schema
+        });
+        return this;
+    }
+    /**
+     * Get all registered tool names
+     */
+    getToolNames() {
+        return Array.from(this.toolHandlers.keys()).filter((name) => !name.startsWith('__kadi_'));
+    }
+    /**
+     * Get all registered tools (agent compatibility)
+     */
+    getTools() {
+        return this.getToolNames();
+    }
+    /**
+     * Check if a tool is registered
+     */
+    hasTool(name) {
+        return this.toolHandlers.has(name);
+    }
+    /**
+     * Get tool handler
+     */
+    getToolHandler(name) {
+        const tool = this.toolHandlers.get(name);
+        return tool?.handler;
+    }
+    /**
+     * Get tool schema
+     */
+    getToolSchema(name) {
+        const tool = this.toolHandlers.get(name);
+        return tool?.schema;
+    }
+    /**
+     * Publish an event
+     */
+    publishEvent(eventName, data = {}) {
+        if (typeof eventName !== 'string' || !eventName) {
+            throw new TypeError('Event name must be a non-empty string');
+        }
+        this.logger.trace('publishEvent', `Publishing event: ${eventName}, protocol: ${this.protocol}, data: ${JSON.stringify(data)}`);
+        // For native protocol, emit directly using internal transport event
+        if (this.protocol === 'native') {
+            this.logger.debug('publishEvent', `Emitting ${ABILITY_EVENT_TRANSPORT} for native protocol`);
+            // Wrap the user event in our transport envelope
+            this.emit(ABILITY_EVENT_TRANSPORT, { name: eventName, data });
+            return;
+        }
+        // For stdio, delegate to handler
+        if (this.protocol === 'stdio') {
+            this.logger.trace('publishEvent', `Checking stdio handler: ${!!this.protocolHandler}, hasPublishEvent: ${typeof this.protocolHandler?.publishEvent}`);
+            if (this.protocolHandler &&
+                typeof this.protocolHandler.publishEvent === 'function') {
+                this.logger.debug('publishEvent', 'Delegating to stdio protocolHandler');
+                this.protocolHandler.publishEvent(eventName, data);
+            }
+            else {
+                this.logger.warn('publishEvent', `No protocolHandler available for stdio protocol - handler: ${!!this.protocolHandler}`);
+            }
+            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 a "routing key"
+                        data
+                    }
+                };
+                this.logger.trace('publishEvent', `Sending broker event message: ${JSON.stringify(eventMessage)}`);
+                broker.ws.send(JSON.stringify(eventMessage));
+            }
+            else {
+                this.logger.warn('publishEvent', 'Broker connection not ready');
+            }
+        }
+        else if (this.protocol === 'broker') {
+            this.logger.warn('publishEvent', 'No broker connections available');
+        }
+    }
+    /**
+     * 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() {
+        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 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, 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
+        };
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error(`Connection timeout to ${url}`));
+            }, 10000);
+            ws.on('open', async () => {
+                clearTimeout(timeout);
+                this.logger.debug('connectToBroker', `WebSocket connected to ${url}`);
+                try {
+                    // Perform handshake
+                    await this.performHandshake(connection);
+                    this._brokerConnections.push(connection);
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            ws.on('error', (error) => {
+                clearTimeout(timeout);
+                this.logger.error('connectToBroker', `WebSocket error: ${error.message}`);
+                reject(error);
+            });
+            ws.on('message', (data) => {
+                this.handleBrokerMessage(connection, data.toString());
+            });
+            ws.on('close', () => {
+                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');
+                }
+                const index = this._brokerConnections.indexOf(connection);
+                if (index !== -1) {
+                    this._brokerConnections.splice(index, 1);
+                }
+            });
+        });
+    }
+    /**
+     * Perform KADI protocol handshake
+     */
+    async performHandshake(connection) {
+        this.logger.debug('performHandshake', 'Starting KADI protocol handshake');
+        // Generate ephemeral keys
+        const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519');
+        // Step 1: Send hello
+        const helloMsg = {
+            jsonrpc: '2.0',
+            method: KadiMessages.SESSION_HELLO,
+            params: {
+                role: this.role,
+                version: this.version
+            },
+            id: this._idFactory.next()
+        };
+        const helloResponse = await this.sendRequest(connection, helloMsg);
+        const helloResult = helloResponse.result;
+        const nonce = helloResult?.nonce;
+        if (!nonce)
+            throw new Error('No nonce received');
+        // Store the heartbeat interval for later use
+        const heartbeatIntervalSec = helloResult?.heartbeatIntervalSec || 0;
+        // Step 2: Authenticate
+        const signature = crypto
+            .sign(null, Buffer.from(nonce), privateKey)
+            .toString('base64');
+        const authMsg = {
+            jsonrpc: '2.0',
+            method: KadiMessages.SESSION_AUTHENTICATE,
+            params: {
+                publicKey: publicKey
+                    .export({ format: 'der', type: 'spki' })
+                    .toString('base64'),
+                signature,
+                nonce,
+                wantNewId: true
+            },
+            id: this._idFactory.next()
+        };
+        const authResponse = await this.sendRequest(connection, authMsg);
+        const authResult = authResponse.result;
+        this._agentId = authResult?.agentId;
+        connection.isAuthenticated = true;
+        // Step 3: Register capabilities
+        await this.registerCapabilities(connection);
+        // Step 4: Start heartbeat if required
+        if (heartbeatIntervalSec > 0) {
+            this.startHeartbeat(connection, heartbeatIntervalSec);
+        }
+        this.logger.info('performHandshake', `Authenticated as ${this._agentId}`);
+    }
+    /**
+     * Start heartbeat to keep broker connection alive
+     * Sends ping messages at the specified interval to prevent timeout
+     */
+    startHeartbeat(connection, intervalSec) {
+        this.logger.debug('startHeartbeat', `Starting heartbeat with ${intervalSec}s interval`);
+        // Clear any existing heartbeat timer
+        if (connection.heartbeatTimer) {
+            clearInterval(connection.heartbeatTimer);
+        }
+        // Send ping at the specified interval
+        connection.heartbeatTimer = setInterval(() => {
+            if (connection.ws.readyState === WebSocket.OPEN) {
+                const pingMsg = {
+                    jsonrpc: '2.0',
+                    method: KadiMessages.SESSION_PING,
+                    params: {}
+                };
+                const message = JSON.stringify(pingMsg);
+                connection.ws.send(message);
+                this.logger.trace('heartbeat', 'Sent ping to broker');
+            }
+            else {
+                // Connection closed, stop heartbeat
+                if (connection.heartbeatTimer) {
+                    clearInterval(connection.heartbeatTimer);
+                    connection.heartbeatTimer = undefined;
+                }
+                this.logger.debug('heartbeat', 'Connection closed, stopping heartbeat');
+            }
+        }, intervalSec * 1000);
+    }
+    /**
+     * Register capabilities with broker
+     */
+    async registerCapabilities(connection) {
+        const tools = await this.extractToolsForBroker();
+        const params = {
+            displayName: this.name,
+            networks: this.networks,
+            tools: tools
+        };
+        const registerMsg = {
+            jsonrpc: '2.0',
+            method: KadiMessages.AGENT_REGISTER,
+            params,
+            id: this._idFactory.next()
+        };
+        await this.sendRequest(connection, registerMsg);
+        this.logger.info('registerCapabilities', `Registered ${tools.length} tools`);
+    }
+    /**
+     * Send request to broker and wait for response
+     */
+    sendRequest(connection, message) {
+        return new Promise((resolve, reject) => {
+            const id = message.id;
+            this.logger.trace('sendBrokerRequest', `Sending ${message.method} request (ID: ${id})`);
+            const timeout = setTimeout(() => {
+                this.logger.warn('sendBrokerRequest', `Request timeout for ${message.method} (ID: ${id})`);
+                this._pendingResponses.delete(id);
+                reject(new Error(`Request timeout: ${message.method}`));
+            }, 30000);
+            this._pendingResponses.set(id, {
+                resolve: resolve,
+                reject,
+                timer: timeout
+            });
+            this.logger.trace('sendBrokerRequest', `Stored pending response for ${message.method} (ID: ${id})`);
+            connection.ws.send(JSON.stringify(message));
+        });
+    }
+    /**
+     * Handle incoming broker messages
+     */
+    handleBrokerMessage(connection, data) {
+        try {
+            const message = JSON.parse(data);
+            this.logger?.trace('handleBrokerMessage', `Received message: ${JSON.stringify(message)}`);
+            // Handle responses to our requests
+            if ('id' in message &&
+                message.id !== null &&
+                this._pendingResponses.has(message.id)) {
+                this.logger?.trace('handleBrokerMessage', `Found pending response for ID: ${message.id}`);
+                const pending = this._pendingResponses.get(message.id);
+                clearTimeout(pending.timer);
+                this._pendingResponses.delete(message.id);
+                if ('error' in message && message.error) {
+                    this.logger?.debug('handleBrokerMessage', `Error response: ${message.error.message}`);
+                    pending.reject(new Error(`${message.error.code}: ${message.error.message}`));
+                }
+                else {
+                    this.logger?.trace('handleBrokerMessage', `Success response for ID: ${message.id}`);
+                    pending.resolve(message);
+                }
+                return;
+            }
+            else if ('id' in message && message.id !== null) {
+                // Only log if there's an ID but we don't recognize it (unexpected response)
+                this.logger?.warn('handleBrokerMessage', `Received response with unrecognized ID: ${message.id}`);
+            }
+            // For notifications (no ID), this is normal - no need to log
+            // Handle incoming method calls (both agent.invoke and kadi.ability.call)
+            // Handle incoming tool invocation requests
+            // Using ABILITY_INVOKE for all tool invocations (broker-to-agent and client-to-client)
+            if ('method' in message &&
+                message.method === KadiMessages.ABILITY_INVOKE) {
+                this.handleToolInvocation(connection, message);
+                return;
+            }
+            // Handle tool invocation results
+            if ('method' in message &&
+                message.method === KadiMessages.ABILITY_RESULT) {
+                this.handleToolResult(message);
+                return;
+            }
+            // Handle other notifications
+            if ('method' in message && !('id' in message)) {
+                this.emit('notification', message);
+                // Also emit for our unified event system
+                this.emit('broker:message', message);
+            }
+        }
+        catch (error) {
+            this.logger.error('handleBrokerMessage', `Failed to parse message: ${error}`);
+        }
+    }
+    /**
+     * Handle tool invocation result from broker
+     */
+    handleToolResult(message) {
+        const { requestId, result, error, toSessionId } = message.params;
+        // Check if this result is for us
+        if (toSessionId !== this._agentId) {
+            return; // Not for us
+        }
+        // Find pending tool call
+        if (this._pendingToolCalls.has(requestId)) {
+            const pending = this._pendingToolCalls.get(requestId);
+            clearTimeout(pending.timer);
+            this._pendingToolCalls.delete(requestId);
+            if (error) {
+                pending.reject(new Error(`Tool call failed: ${error.message || error}`));
+            }
+            else {
+                pending.resolve(result);
+            }
+        }
+    }
+    /**
+     * Handle incoming tool invocation request
+     */
+    async handleToolInvocation(connection, request) {
+        const { requestId, from, toolName, toolInput } = request.params;
+        const method = this.toolHandlers.get(toolName);
+        if (!method) {
+            // Send kadi.ability.result with error
+            const errorMessage = {
+                jsonrpc: '2.0',
+                method: KadiMessages.ABILITY_RESULT,
+                params: {
+                    requestId,
+                    toSessionId: from,
+                    error: {
+                        code: 'TOOL_NOT_FOUND',
+                        message: `Tool ${toolName} not found`
+                    }
+                }
+            };
+            connection.ws.send(JSON.stringify(errorMessage));
+            return;
+        }
+        try {
+            this.logger.debug('handleToolInvocation', `Executing tool: ${toolName}`);
+            const result = await method.handler(toolInput);
+            this.logger.debug('handleToolInvocation', `Tool ${toolName} completed successfully`);
+            // Send kadi.ability.result with success result
+            const resultMessage = {
+                jsonrpc: '2.0',
+                method: KadiMessages.ABILITY_RESULT,
+                params: {
+                    requestId,
+                    toSessionId: from,
+                    result
+                }
+            };
+            this.logger.trace('handleToolInvocation', `Sending result for tool: ${toolName}`);
+            connection.ws.send(JSON.stringify(resultMessage));
+        }
+        catch (error) {
+            this.logger.error('handleToolInvocation', `Tool ${toolName} failed: ${error.message}`);
+            // Send kadi.ability.result with error
+            const errorMessage = {
+                jsonrpc: '2.0',
+                method: KadiMessages.ABILITY_RESULT,
+                params: {
+                    requestId,
+                    toSessionId: from,
+                    error: {
+                        code: 'EXECUTION_ERROR',
+                        message: error.message || 'Tool execution failed'
+                    }
+                }
+            };
+            connection.ws.send(JSON.stringify(errorMessage));
+        }
+    }
+    /**
+     * Extract tool definitions for broker registration
+     */
+    async extractToolsForBroker() {
+        const tools = [];
+        // Try to load from agent.json
+        const agentJsonExports = await this._loadAgentJsonExports();
+        for (const [name, method] of this.toolHandlers) {
+            if (name.startsWith('__kadi_'))
+                continue;
+            let schema = method.schema;
+            // Check agent.json if no inline schema
+            if (!schema) {
+                const exportSchema = agentJsonExports.find((exp) => exp.name === name);
+                if (exportSchema) {
+                    schema = {
+                        description: exportSchema.description,
+                        inputSchema: exportSchema.inputSchema,
+                        outputSchema: exportSchema.outputSchema
+                    };
+                }
+            }
+            if (!schema) {
+                this.logger.warn('extractToolsForBroker', `No schema for method '${name}', skipping`);
+                continue;
+            }
+            tools.push({
+                name,
+                description: schema.description || `Execute ${name}`,
+                inputSchema: schema.inputSchema || { type: 'object' },
+                outputSchema: schema.outputSchema || { type: 'object' } // Default to empty object schema
+            });
+        }
+        return tools;
+    }
+    /**
+     * Start serving (main entry point)
+     *
+     * @param options - Optional serve options
+     */
+    async serve(options = {}) {
+        this.logger.lifecycle('serve', `Starting to serve: ${this.name}`);
+        // Handle protocol override
+        if (options.mode && options.mode !== this.protocol) {
+            this.logger.info('serve', `Protocol override: ${this.protocol} -> ${options.mode}`);
+            this.protocol = options.mode;
+            // Recreate handler if needed
+            if (this.protocol !== 'broker') {
+                this.protocolHandler = ProtocolHandlerFactory.create(this.protocol, {
+                    name: this.name,
+                    version: this.version,
+                    description: this.description,
+                    network: this.network
+                });
+            }
+        }
+        try {
+            switch (this.protocol) {
+                case 'native':
+                    // No serving needed - methods called directly
+                    this.logger.info('serve', `Serving ${this.name} in native mode`);
+                    this.emit('start', {
+                        protocol: this.protocol,
+                        tools: this.getToolNames()
+                    });
+                    // 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
+                    if (this.protocolHandler) {
+                        await this.protocolHandler.serve(this);
+                        this.logger.info('serve', `Serving ${this.name} via stdio`);
+                    }
+                    else {
+                        // Create a StdioTransport for serving if one doesn't exist
+                        const transport = new StdioTransport({
+                            abilityName: this.name,
+                            abilityVersion: this.version || '1.0.0',
+                            abilityDir: process.cwd(),
+                            startCmd: '' // Not needed for server mode
+                        });
+                        this.protocolHandler = transport;
+                        await transport.serve(this);
+                    }
+                    break;
+                case 'broker':
+                    // Connect to broker and register
+                    await this.connectToBrokers();
+                    this.logger.info('serve', `Serving ${this.name} via broker`);
+                    // Keep process alive
+                    return new Promise(() => { });
+                default:
+                    throw new Error(`Unknown protocol: ${this.protocol}`);
+            }
+        }
+        catch (error) {
+            this.logger.error('serve', `Failed to start serving: ${error.message}`);
+            this.emit('error', error);
+            throw error;
+        }
+    }
+    /**
+     * Start the client (alias for serve for agent compatibility)
+     */
+    async start() {
+        return this.serve();
+    }
+    /**
+     * Discover tools available from a remote agent
+     *
+     * This function queries the broker to find what tools
+     * a specific remote agent provides.
+     *
+     * @param targetAgent - The name of the agent to discover tools from
+     * @returns Array of tool names available from the target agent
+     */
+    async discoverRemoteTools(targetAgent) {
+        if (this.protocol !== 'broker' || this._brokerConnections.length === 0) {
+            throw new Error('Must be connected to broker to discover remote methods');
+        }
+        const broker = this._brokerConnections[0];
+        // Use ABILITY_LIST to discover available tools from the target agent
+        const request = {
+            jsonrpc: '2.0',
+            method: KadiMessages.ABILITY_LIST,
+            params: {
+                targetAgent,
+                networks: this.networks
+            },
+            id: this._idFactory.next()
+        };
+        try {
+            const response = await this.sendRequest(broker, request);
+            const result = response.result;
+            // Handle different response formats
+            if (result.methods) {
+                return result.methods;
+            }
+            else if (result.tools) {
+                return result.tools.map((tool) => tool.name);
+            }
+            return [];
+        }
+        catch (error) {
+            this.logger.error('discoverRemoteTools', `Failed to discover tools from ${targetAgent}: ${error}`);
+            // Return empty array on error - the agent might not be connected
+            return [];
+        }
+    }
+    /**
+     * Call a tool on a remote agent via the broker
+     *
+     * This function sends an RPC call through the broker to invoke
+     * a specific tool on a remote agent.
+     *
+     * @param targetAgent - The name of the agent that has the tool
+     * @param toolName - The tool name to invoke
+     * @param params - The parameters to pass to the tool
+     * @returns The result from the remote tool invocation
+     */
+    async callTool(targetAgent, toolName, params) {
+        if (this._brokerConnections.length === 0) {
+            throw new Error('Must be connected to broker to call remote tools');
+        }
+        const broker = this._brokerConnections[0];
+        // Use ABILITY_INVOKE to call a remote agent's tool
+        const request = {
+            jsonrpc: '2.0',
+            method: KadiMessages.ABILITY_INVOKE,
+            params: {
+                targetAgent, // Which agent to call
+                toolName: toolName,
+                toolInput: params
+            },
+            id: this._idFactory.next()
+        };
+        // First, send the request and get the "pending" response
+        const pendingResponse = await this.sendRequest(broker, request);
+        const pendingResult = pendingResponse.result;
+        // Check if it's a pending response with requestId
+        if (pendingResult?.type === 'pending' && pendingResult?.requestId) {
+            // Wait for the actual result via kadi.ability.result
+            return new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    this._pendingToolCalls.delete(pendingResult.requestId);
+                    reject(new Error(`Tool call timeout: ${toolName}`));
+                }, 30000);
+                this._pendingToolCalls.set(pendingResult.requestId, {
+                    resolve: resolve,
+                    reject,
+                    timer: timeout
+                });
+            });
+        }
+        else {
+            // Immediate response (shouldn't happen for tool calls, but handle anyway)
+            return pendingResult;
+        }
+    }
+    /**
+     * 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 = {}) {
+        // 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') {
+            this.logger.debug('loadAbility', `Connecting ability events for ${protocol} protocol`);
+            // Forward events from the loaded ability to this client
+            this.logger.trace('loadAbility', 'Setting up ability.on(event) listener');
+            /**
+             * Forward events from the loaded ability to the main client's event system.
+             * The AbilityProxy emits events when it receives them from the transport,
+             * and we need to re-emit them using our internal transport mechanism
+             * so they can be delivered to user subscriptions.
+             *
+             * Note: We only need to listen to ability.on('event') - the ability.events
+             * is a legacy EventEmitter that mirrors the same events, so listening to
+             * both would cause duplicates.
+             */
+            ability.on('event', (eventData) => {
+                this.logger.trace('loadAbility', `Received event from ability: ${JSON.stringify(eventData)}`);
+                const eventName = eventData.eventName || eventData.name;
+                if (eventName) {
+                    this.logger.debug('loadAbility', `Forwarding event from ability: ${eventName}`);
+                    // Wrap the event in our internal transport envelope for delivery
+                    this.emit(ABILITY_EVENT_TRANSPORT, {
+                        eventName,
+                        data: eventData.data
+                    });
+                }
+            });
+        }
+        return ability;
+    }
+    /**
+     * 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');
+    }
+    /**
+     * Helper to load agent.json exports
+     */
+    async _loadAgentJsonExports() {
+        try {
+            const agentJsonPath = await this._findAgentJson();
+            const agentJson = JSON.parse(fs.readFileSync(agentJsonPath, 'utf8'));
+            return agentJson.exports || [];
+        }
+        catch (err) {
+            return [];
+        }
+    }
+    /**
+     * Find agent.json file
+     * TODO: Not sure, but maybe this function can be moved to pathUtils.ts?
+     */
+    async _findAgentJson() {
+        const possiblePaths = [
+            this.abilityAgentJSON,
+            path.join(process.cwd(), 'agent.json'),
+            path.join(path.dirname(process.argv[1]), 'agent.json'),
+            path.join(process.cwd(), '..', 'agent.json'),
+            path.join(process.cwd(), '..', '..', 'agent.json')
+        ].filter(Boolean);
+        for (const agentPath of possiblePaths) {
+            if (fs.existsSync(agentPath)) {
+                return agentPath;
+            }
+        }
+        throw new Error('agent.json not found');
+    }
+    /**
+     * Subscribe to events with unified API across all protocols
+     *
+     * @param pattern Event pattern - exact string for native/stdio, wildcards supported for broker
+     * @param callback Function to call when event is received
+     * @returns Unsubscribe function
+     */
+    subscribeToEvent(pattern, callback) {
+        this.logger.debug('subscribeToEvent', `Subscribing to pattern: ${pattern}`);
+        // Validate pattern - no colons allowed (RabbitMQ conflict)
+        if (pattern.includes(':')) {
+            throw new Error(`Colons (:) not allowed in event patterns due to RabbitMQ routing conflicts. Use dots (.) instead.`);
+        }
+        // Validate pattern based on protocol
+        if (this.protocol !== 'broker' && pattern.includes('*')) {
+            throw new Error(`Wildcard patterns not supported in ${this.protocol} protocol. Use exact event names.`);
+        }
+        // Store subscription
+        if (!this._eventSubscriptions.has(pattern)) {
+            this._eventSubscriptions.set(pattern, []);
+        }
+        this._eventSubscriptions.get(pattern).push(callback);
+        // Protocol-specific subscription setup
+        this._setupProtocolEventSubscription(pattern);
+        // Return unsubscribe function
+        return () => this.unsubscribeFromEvent(pattern, callback);
+    }
+    /**
+     * Subscribe to multiple events at once
+     *
+     * @param patterns Array of event patterns
+     * @param callback Function to call when any event is received (receives eventName and data)
+     * @returns Unsubscribe function that removes all subscriptions
+     */
+    subscribeToEvents(patterns, callback) {
+        const unsubscribeFunctions = [];
+        for (const pattern of patterns) {
+            const unsubscribe = this.subscribeToEvent(pattern, (data) => {
+                callback(pattern, data);
+            });
+            unsubscribeFunctions.push(unsubscribe);
+        }
+        // Return function that unsubscribes from all patterns
+        return () => {
+            unsubscribeFunctions.forEach((fn) => fn());
+        };
+    }
+    /**
+     * Unsubscribe from event pattern
+     *
+     * @param pattern Event pattern to unsubscribe from
+     * @param callback Optional specific callback to remove (if not provided, removes all)
+     */
+    unsubscribeFromEvent(pattern, callback) {
+        const callbacks = this._eventSubscriptions.get(pattern);
+        if (!callbacks)
+            return;
+        if (callback) {
+            // Remove specific callback
+            const index = callbacks.indexOf(callback);
+            if (index > -1) {
+                callbacks.splice(index, 1);
+            }
+        }
+        else {
+            // Remove all callbacks for this pattern
+            callbacks.length = 0;
+        }
+        // Clean up empty subscription
+        if (callbacks.length === 0) {
+            this._eventSubscriptions.delete(pattern);
+            this._cleanupProtocolEventSubscription(pattern);
+        }
+    }
+    /**
+     * Subscribe to an event only once
+     *
+     * @param pattern Event pattern
+     * @param callback Function to call when event is received (auto-unsubscribes after first call)
+     */
+    onceEvent(pattern, callback) {
+        const unsubscribe = this.subscribeToEvent(pattern, (data) => {
+            callback(data);
+            unsubscribe();
+        });
+    }
+    /**
+     * Setup universal event subscription that works regardless of client protocol
+     *
+     * @private
+     * @param pattern Event pattern to subscribe to
+     */
+    /**
+     * Marker to track if we've already set up the event transport infrastructure
+     */
+    _eventTransportSetup = false;
+    /**
+     * Setup the event transport infrastructure ONCE, then subscribe to specific patterns
+     * TODO: I do not understand this function very well - better step by step comments
+     * would be nice.
+     *
+     * @private
+     * @param pattern Event pattern to subscribe to (e.g., 'echo.test-event')
+     */
+    _setupProtocolEventSubscription(pattern) {
+        this.logger.debug('subscribeToEvent', `Subscribing to pattern: ${pattern}`);
+        // Set up the transport infrastructure only once
+        if (!this._eventTransportSetup) {
+            this._eventTransportSetup = true;
+            this.logger.debug('subscribeToEvent', 'Setting up event transport infrastructure (first time only)');
+            /**
+             * Set up listener for events from native/stdio loaded abilities.
+             * This listens for our internal transport event and unwraps the actual
+             * user events for delivery to subscriptions.
+             */
+            this.logger.trace('subscribeToEvent', `Setting up ${ABILITY_EVENT_TRANSPORT} listener`);
+            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);
+                    }
+                }
+            });
+            /**
+             * Set up listener for stdio transport events if we have a stdio handler.
+             * This is for when THIS client is running in stdio mode and receiving events.
+             */
+            if (this.protocolHandler &&
+                typeof this.protocolHandler.on === 'function') {
+                this.logger.debug('subscribeToEvent', 'Setting up stdio transport event listener');
+                this.protocolHandler.on('event', (event) => {
+                    if (event.name) {
+                        this.logger.trace('subscribeToEvent', `Received stdio transport event: ${event.name}`);
+                        // Check all registered patterns
+                        for (const [registeredPattern] of this._eventSubscriptions) {
+                            if (this._matchesPattern(event.name, registeredPattern)) {
+                                this.logger.debug('subscribeToEvent', `Stdio event matched pattern: ${event.name} vs ${registeredPattern}`);
+                                this._dispatchEvent(registeredPattern, event.data);
+                            }
+                        }
+                    }
+                });
+            }
+        }
+        /**
+         * 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.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()
+                    .then(() => {
+                    this.logger.debug('subscribeToEvent', `Subscribing to broker event: ${pattern}`);
+                    this._subscribeToBrokerEvent(pattern);
+                })
+                    .catch((error) => {
+                    this.logger.warn('subscribeToEvent', `Failed to connect to broker for events: ${error.message}`);
+                });
+            }
+            else {
+                this.logger.debug('subscribeToEvent', `Subscribing to broker event: ${pattern}`);
+                this._subscribeToBrokerEvent(pattern);
+            }
+        }
+    }
+    /**
+     * Subscribe to broker events
+     *
+     * @private
+     * @param pattern Event pattern to subscribe to
+     */
+    async _subscribeToBrokerEvent(pattern) {
+        if (this._brokerConnections.length === 0) {
+            throw new Error('Not connected to any broker. Call connectToBrokers() first.');
+        }
+        const broker = this._brokerConnections[0];
+        if (!broker.ws || broker.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('Broker connection not ready');
+        }
+        try {
+            const subscribeMessage = {
+                jsonrpc: '2.0',
+                method: KadiMessages.EVENT_SUBSCRIBE,
+                params: {
+                    channels: [pattern],
+                    networkId: this.networks[0] || 'global'
+                },
+                id: this._idFactory.next()
+            };
+            broker.ws.send(JSON.stringify(subscribeMessage));
+            this.logger.debug('_subscribeToBrokerEvent', `Sent subscription for: ${pattern}`);
+            // Setup EVENT_DELIVERY handler if not already done
+            if (!this._brokerEventHandlerSetup) {
+                this._setupBrokerEventHandler();
+            }
+        }
+        catch (error) {
+            this.logger.error('_subscribeToBrokerEvent', `Failed to subscribe to ${pattern}:`, error);
+            throw new Error(`Failed to subscribe to broker event '${pattern}': ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    /**
+     * Setup broker event delivery handler
+     *
+     * @private
+     */
+    _brokerEventHandlerSetup = false;
+    _setupBrokerEventHandler() {
+        if (this._brokerEventHandlerSetup)
+            return;
+        // Handle broker messages for EVENT_DELIVERY
+        this.on('broker:message', (message) => {
+            if (message.method === KadiMessages.EVENT_DELIVERY) {
+                const eventData = message.params;
+                this.logger.debug('_setupBrokerEventHandler', `Received event on channel: ${eventData.channel}`);
+                // Dispatch to matching subscribers
+                for (const [pattern, callbacks] of this._eventSubscriptions.entries()) {
+                    if (this._matchesPattern(eventData.channel, pattern)) {
+                        callbacks.forEach((callback) => callback(eventData.data));
+                    }
+                }
+                // Also emit for backward compatibility
+                this.emit('event', eventData);
+            }
+        });
+        this._brokerEventHandlerSetup = true;
+    }
+    /**
+     * Clean up protocol-specific event subscription
+     *
+     * @private
+     * @param pattern Event pattern to clean up
+     */
+    _cleanupProtocolEventSubscription(pattern) {
+        if (this.protocol === 'broker') {
+            // Send unsubscribe message to broker
+            const broker = this._brokerConnections[0];
+            if (broker?.ws && broker.ws.readyState === WebSocket.OPEN) {
+                const unsubscribeMessage = {
+                    jsonrpc: '2.0',
+                    method: KadiMessages.EVENT_UNSUBSCRIBE,
+                    params: {
+                        channels: [pattern],
+                        networkId: this.networks[0] || 'global'
+                    }
+                };
+                broker.ws.send(JSON.stringify(unsubscribeMessage));
+                this.logger.debug('_cleanupProtocolEventSubscription', `Unsubscribed from: ${pattern}`);
+            }
+        }
+    }
+    /**
+     * Check if event name matches pattern
+     *
+     * @private
+     * @param eventName Event name to check
+     * @param pattern Pattern to match against (supports wildcards for broker protocol)
+     * @returns True if matches
+     */
+    _matchesPattern(eventName, pattern) {
+        // Exact match for all protocols
+        if (eventName === pattern)
+            return true;
+        // Wildcard matching only for broker protocol
+        if (this.protocol === 'broker' && pattern.includes('*')) {
+            const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+            return regex.test(eventName);
+        }
+        return false;
+    }
+    /**
+     * 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 (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);
+                }
+            });
+        }
+    }
+    // Getters for compatibility
+    get isConnected() {
+        return this._isConnected;
+    }
+    get agentId() {
+        return this._agentId;
+    }
+    get broker() {
+        return this._brokerConnections[0];
+    }
+}
+export default KadiClient;
+//# sourceMappingURL=KadiClient.js.map