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

package/dist/KadiClient.js

@@ -0,0 +1,1162 @@
+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';
+// 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;
+    scope;
+    networks;
+    brokerUrls;
+    abilityAgentJSON;
+    logger;
+    protocolHandler;
+    toolHandlers = new Map();
+    _abilities = new Map();
+    _brokerConnections = [];
+    _isConnected = false;
+    _agentId = '';
+    _idFactory;
+    _pendingResponses = new Map();
+    _pendingToolCalls = new Map();
+    _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.scope = options.scope || 'global';
+        this.networks = options.networks || ['global'];
+        this.brokerUrls =
+            options.brokerUrls || (options.brokerUrl ? [options.brokerUrl] : []);
+        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})`);
+        // 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));
+            }
+        }
+    }
+    /**
+     * 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
+        if (this.protocol === 'broker' && this._brokerConnections.length > 0) {
+            this.logger.debug('publishEvent', `Publishing broker event: ${eventName}`);
+            const broker = this._brokerConnections[0];
+            if (broker.ws && broker.ws.readyState === WebSocket.OPEN) {
+                const eventMessage = {
+                    jsonrpc: '2.0',
+                    method: KadiMessages.EVENT_PUBLISH,
+                    params: {
+                        channel: eventName, // RabbitMQ calls this "routing key"
+                        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 brokers (for event subscription and/or broker protocol)
+     */
+    async connectToBrokers(urls) {
+        // Allow any protocol to connect to brokers for event subscription
+        // The protocol only determines how this client itself serves, not what it can connect to
+        const brokerUrls = urls || [
+            process.env.KADI_BROKER_URL || 'ws://localhost:8080'
+        ];
+        this.logger.info('connectToBrokers', `Connecting to ${brokerUrls.length} broker(s)`);
+        for (const url of brokerUrls) {
+            await this.connectToBroker(url);
+        }
+        this._isConnected = true;
+        this.emit('connected');
+    }
+    /**
+     * Connect to a single broker
+     */
+    async connectToBroker(url) {
+        this.logger.info('connectToBroker', `Connecting to broker at ${url}`);
+        const ws = new WebSocket(url);
+        const connection = {
+            url,
+            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', `Disconnected from ${url}`);
+                // Clean up heartbeat timer
+                if (connection.heartbeatTimer) {
+                    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;
+            // ! DO NOT USE CONSOLE.LOG use the the logger
+            console.log(`[KadiClient] 📤 SENDING REQUEST:`, JSON.stringify(message, null, 2));
+            const timeout = setTimeout(() => {
+                // ! DO NOT USE CONSOLE.LOG use the the logger
+                console.log(`[KadiClient] ⏰ TIMEOUT for request ${id} (${message.method})`);
+                this._pendingResponses.delete(id);
+                reject(new Error(`Request timeout: ${message.method}`));
+            }, 30000);
+            this._pendingResponses.set(id, {
+                resolve: resolve,
+                reject,
+                timer: timeout
+            });
+            // ! DO NOT USE CONSOLE.LOG use the the logger
+            console.log(`[KadiClient] 📝 STORED pending response for 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 {
+            console.log(`[KadiClient] 🔧 EXECUTING TOOL: ${toolName} with params:`, toolInput);
+            const result = await method.handler(toolInput);
+            console.log(`[KadiClient] ✅ TOOL RESULT for ${toolName}:`, result);
+            // Send kadi.ability.result with success result
+            const resultMessage = {
+                jsonrpc: '2.0',
+                method: KadiMessages.ABILITY_RESULT,
+                params: {
+                    requestId,
+                    toSessionId: from,
+                    result
+                }
+            };
+            console.log(`[KadiClient] 📤 SENDING RESULT:`, JSON.stringify(resultMessage, null, 2));
+            connection.ws.send(JSON.stringify(resultMessage));
+        }
+        catch (error) {
+            console.log(`[KadiClient] ❌ TOOL ERROR for ${toolName}:`, error);
+            // 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,
+                    scope: this.scope
+                });
+            }
+        }
+        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
+                    return new Promise(() => { });
+                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.protocol !== 'broker' || 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;
+        }
+    }
+    /**
+     * Load an external ability
+     */
+    async loadAbility(nameOrPath, protocol = 'native', options = {}) {
+        const ability = await loadAbility(nameOrPath, protocol, options);
+        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
+     */
+    async disconnect() {
+        for (const connection of this._brokerConnections) {
+            // Clean up heartbeat timer before closing
+            if (connection.heartbeatTimer) {
+                clearInterval(connection.heartbeatTimer);
+                connection.heartbeatTimer = undefined;
+            }
+            if (connection.ws) {
+                connection.ws.close();
+            }
+        }
+        this._brokerConnections.length = 0;
+        this._isConnected = false;
+        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
+     */
+    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
+                for (const [registeredPattern] of this._eventSubscriptions) {
+                    if (this._matchesPattern(envelope.eventName, registeredPattern)) {
+                        this.logger.debug('subscribeToEvent', `Pattern matched (${envelope.eventName} vs ${registeredPattern}), dispatching event`);
+                        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.
+         */
+        if (this.brokerUrls && this.brokerUrls.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
+     * TODO: I do not understand this function
+     *
+     * @private
+     * @param pattern Pattern that matched
+     * @param data Event data
+     */
+    _dispatchEvent(pattern, data) {
+        const callbacks = this._eventSubscriptions.get(pattern);
+        if (callbacks) {
+            callbacks.forEach((callback) => {
+                try {
+                    callback(data);
+                }
+                catch (error) {
+                    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