@kadi.build/core 0.0.1-alpha.9 → 0.1.0

package/dist/KadiClient.js

@@ -1,1572 +0,0 @@
-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 { CoreErrorCodes } from './errors/error-codes.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__';
-/**
- * TransportHandlerFactory - creates the appropriate handler for the chosen transport
- */
-class TransportHandlerFactory {
-    static create(transport, options = {}) {
-        switch (transport?.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(),
-                    // Not used in server mode; required by constructor
-                    startCmd: ''
-                });
-            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;
-    transport;
-    network;
-    networks;
-    brokers;
-    defaultBroker;
-    abilityAgentJSON;
-    logger;
-    transportHandler;
-    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';
-        const envTransport = process.env.KADI_TRANSPORT || process.env.KADI_PROTOCOL;
-        this.transport = (options.transport ||
-            envTransport ||
-            'native');
-        this.network = options.network || 'global';
-        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}, transport: ${this.transport})`);
-        this.logger.debug('constructor', `Resolved ${Object.keys(this.brokers).length} brokers, default: ${this.defaultBroker}`);
-        // Create transport handler for stdio (broker is handled internally)
-        if (this.transport !== 'broker') {
-            this.transportHandler = TransportHandlerFactory.create(this.transport, options);
-            // Forward events from the transport handler
-            if (this.transportHandler) {
-                this.transportHandler.on('start', (data) => this.emit('start', { ...data, transport: this.transport }));
-                this.transportHandler.on('error', (error) => this.emit('error', error));
-                this.transportHandler.on('stop', () => this.emit('stop'));
-                this.transportHandler.on('request', (data) => this.emit('request', data));
-                this.transportHandler.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}, transport: ${this.transport}, data: ${JSON.stringify(data)}`);
-        // For native protocol, emit directly using internal transport event
-        if (this.transport === '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.transport === 'stdio') {
-            this.logger.trace('publishEvent', `Checking stdio handler: ${!!this.transportHandler}, hasPublishEvent: ${typeof this.transportHandler?.publishEvent}`);
-            if (this.transportHandler &&
-                typeof this.transportHandler.publishEvent === 'function') {
-                this.logger.debug('publishEvent', 'Delegating to stdio transport handler');
-                this.transportHandler.publishEvent(eventName, data);
-            }
-            else {
-                this.logger.warn('publishEvent', `No transport handler available for stdio transport - handler: ${!!this.transportHandler}`);
-            }
-            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.transport === 'broker' && this._brokerConnections.length > 0) {
-            this.logger.debug('publishEvent', `Publishing broker event: ${eventName}`);
-            // Send via the currently selected broker connection
-            const broker = this.getCurrentBrokerConnection();
-            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.transport === '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 transport to connect to brokers for event subscription
-        // The transport only determines how this client 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: CoreErrorCodes.CORE_TOOL_NOT_FOUND.code,
-                        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: CoreErrorCodes.CORE_TOOL_INVOCATION_FAILED.code,
-                        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() {
-        this.logger.lifecycle('serve', `Starting to serve: ${this.name}`);
-        try {
-            switch (this.transport) {
-                case 'native':
-                    // No serving needed - methods called directly
-                    this.logger.info('serve', `Serving ${this.name} via native transport`);
-                    this.emit('start', {
-                        transport: this.transport,
-                        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.transportHandler) {
-                        await this.transportHandler.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.transportHandler = 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 transport: ${this.transport}`);
-            }
-        }
-        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.transport !== 'broker' || this._brokerConnections.length === 0) {
-            throw new Error('Must be connected to broker to discover remote methods');
-        }
-        const broker = this.getCurrentBrokerConnection();
-        // 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.getCurrentBrokerConnection();
-        // 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.
-     *
-     *   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, transport = 'native', options = {}) {
-        // For broker transport, resolve broker name to URL
-        const resolvedOptions = { ...options };
-        if (transport === '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 transport to reuse connection
-        const optionsWithClient = transport === 'broker'
-            ? { ...resolvedOptions, existingClient: this }
-            : resolvedOptions;
-        const ability = await loadAbility(nameOrPath, transport, optionsWithClient);
-        this._abilities.set(ability.name, ability);
-        // For native/stdio transports, connect ability events to this client's event system
-        if (transport === 'native' || transport === 'stdio') {
-            this.logger.debug('loadAbility', `Connecting ability events for ${transport} transport`);
-            // 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
-     */
-    async subscribeToEvent(pattern, callback) {
-        this.logger.debug('subscribeToEvent', `Subscribing to pattern: ${pattern}`);
-        // 1. Validate pattern (same for all transports)
-        this._validateEventPattern(pattern);
-        // 2. Store subscription locally (same for all transports)
-        this._storeEventSubscription(pattern, callback);
-        // 3. Ensure transport is ready (one-time setup, cached)
-        await this._ensureEventTransportReady();
-        // 4. Transport-specific pattern subscription
-        await this._subscribeToPattern(pattern);
-        // 5. Return unsubscribe function (same for all transports)
-        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
-     */
-    async subscribeToEvents(patterns, callback) {
-        const unsubscribeFunctions = [];
-        for (const pattern of patterns) {
-            const unsubscribe = await 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)
-     */
-    async onceEvent(pattern, callback) {
-        const unsubscribe = await 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;
-    /**
-     * 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.getCurrentBrokerConnection();
-        if (!broker.ws || broker.ws.readyState !== WebSocket.OPEN) {
-            throw new Error('Broker connection not ready');
-        }
-        try {
-            // Send a JSON-RPC request and await the broker's ACK to remove timing races
-            const request = {
-                jsonrpc: '2.0',
-                method: KadiMessages.EVENT_SUBSCRIBE,
-                params: {
-                    channels: [pattern],
-                    networkId: this.networks[0] || 'global'
-                },
-                id: this._idFactory.next()
-            };
-            const response = await this.sendRequest(broker, request);
-            this.logger.debug('_subscribeToBrokerEvent', `Subscribed to: ${pattern} (${JSON.stringify(response.result)})`);
-            // 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.transport === 'broker') {
-            // Send unsubscribe message to broker
-            const broker = this.getCurrentBrokerConnection();
-            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.transport === '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() {
-        try {
-            return this.getCurrentBrokerConnection();
-        }
-        catch {
-            return undefined;
-        }
-    }
-    _eventTransportReady = null;
-    /**
-     * Validate event pattern for all transports
-     * @private
-     */
-    _validateEventPattern(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.transport !== 'broker' && pattern.includes('*')) {
-            throw new Error(`Wildcard patterns not supported in ${this.transport} transport. Use exact event names.`);
-        }
-    }
-    /**
-     * Store event subscription locally
-     * @private
-     */
-    _storeEventSubscription(pattern, callback) {
-        if (!this._eventSubscriptions.has(pattern)) {
-            this._eventSubscriptions.set(pattern, []);
-        }
-        this._eventSubscriptions.get(pattern).push(callback);
-    }
-    /**
-     * Ensure event transport is ready (one-time setup, cached)
-     * @private
-     */
-    async _ensureEventTransportReady() {
-        // Cache the setup promise to avoid duplicate initialization
-        if (!this._eventTransportReady) {
-            this._eventTransportReady = this._initializeEventTransport();
-        }
-        return this._eventTransportReady;
-    }
-    /**
-     * Initialize event transport (one-time setup)
-     * @private
-     */
-    async _initializeEventTransport() {
-        this.logger.debug('_initializeEventTransport', `Initializing ${this.transport} transport`);
-        switch (this.transport) {
-            case 'broker':
-                // Connect to brokers if needed
-                if (this.brokers && Object.keys(this.brokers).length > 0) {
-                    if (this._brokerConnections.length === 0) {
-                        await this.connectToBrokers();
-                    }
-                    // Setup event delivery handler
-                    this._setupBrokerEventHandler();
-                }
-                break;
-            case 'native':
-                // Setup ABILITY_EVENT_TRANSPORT listener
-                this._setupNativeEventListener();
-                break;
-            case 'stdio':
-                // Setup stdio event listener
-                this._setupStdioEventListener();
-                break;
-            default:
-                throw new Error(`Unknown transport: ${this.transport}`);
-        }
-        this.logger.debug('_initializeEventTransport', `${this.transport} transport initialized`);
-    }
-    /**
-     * Transport-specific pattern subscription
-     * @private
-     */
-    async _subscribeToPattern(pattern) {
-        switch (this.transport) {
-            case 'broker':
-                // Broker needs per-pattern subscription with ACK
-                if (this.brokers && Object.keys(this.brokers).length > 0) {
-                    await this._subscribeToBrokerEvent(pattern);
-                }
-                break;
-            case 'native':
-            case 'stdio':
-                // These transports don't need per-pattern subscription
-                // Their listeners handle all events automatically
-                this.logger.debug('_subscribeToPattern', `${this.transport} transport ready for pattern: ${pattern}`);
-                break;
-            default:
-                throw new Error(`Unknown transport: ${this.transport}`);
-        }
-    }
-    /**
-     * Setup native event listener for ABILITY_EVENT_TRANSPORT
-     * @private
-     */
-    _setupNativeEventListener() {
-        if (this._eventTransportSetup) {
-            this.logger.debug('_setupNativeEventListener', 'Native event listener already setup');
-            return;
-        }
-        this.logger.debug('_setupNativeEventListener', 'Setting up ABILITY_EVENT_TRANSPORT listener');
-        this.on(ABILITY_EVENT_TRANSPORT, (envelope) => {
-            this.logger.trace('_setupNativeEventListener', `Received ${ABILITY_EVENT_TRANSPORT}: ${envelope.eventName}`);
-            // Check all registered patterns to see which subscriptions match this event
-            for (const [registeredPattern] of this._eventSubscriptions) {
-                if (this._matchesPattern(envelope.eventName, registeredPattern)) {
-                    this.logger.debug('_setupNativeEventListener', `Pattern matched (${envelope.eventName} vs ${registeredPattern}), dispatching event`);
-                    this._dispatchEvent(registeredPattern, envelope.data);
-                }
-            }
-        });
-        this._eventTransportSetup = true;
-    }
-    /**
-     * Setup stdio event listener with dual event path support
-     *
-     * IMPORTANT: Stdio transport needs TWO event paths because:
-     * 1. Direct stdio events: from the stdio process itself via transportHandler
-     * 2. Native events: from abilities loaded BY the stdio process via ABILITY_EVENT_TRANSPORT
-     *
-     * Example flow:
-     * KadiClient (stdio transport) → StdioProcess → LoadedAbility (native events)
-     *
-     * Both the stdio process AND any abilities it loads can publish events,
-     * so we need listeners for both event delivery mechanisms.
-     *
-     * @private
-     */
-    _setupStdioEventListener() {
-        if (this._eventTransportSetup) {
-            this.logger.debug('_setupStdioEventListener', 'Stdio event listener already setup');
-            return;
-        }
-        this.logger.debug('_setupStdioEventListener', 'Setting up stdio transport event listener');
-        // PATH 1: Setup native listener for events from abilities loaded by the stdio process
-        // These come through ABILITY_EVENT_TRANSPORT when abilities use the native event system
-        this._setupNativeEventListener();
-        // PATH 2: Setup direct stdio transport listener for events from the stdio process itself
-        // These come directly through the transportHandler's 'event' channel
-        if (this.transportHandler &&
-            typeof this.transportHandler.on === 'function') {
-            this.transportHandler.on('event', (event) => {
-                if (event.name) {
-                    this.logger.trace('_setupStdioEventListener', `Received direct stdio transport event: ${event.name}`);
-                    // Check all registered patterns
-                    for (const [registeredPattern] of this._eventSubscriptions) {
-                        if (this._matchesPattern(event.name, registeredPattern)) {
-                            this.logger.debug('_setupStdioEventListener', `Direct stdio event matched pattern: ${event.name} vs ${registeredPattern}`);
-                            this._dispatchEvent(registeredPattern, event.data);
-                        }
-                    }
-                }
-            });
-        }
-    }
-}
-export default KadiClient;
-//# sourceMappingURL=KadiClient.js.map